[Distutils] it's happened - wheels without sdists (flit)

[Ian Cordasco]

On Mon, Mar 30, 2015 at 10:47 AM, Ionel Cristian Mărieș <contact at ionelmc.ro>
wrote:

> On Mon, Mar 30, 2015 at 6:39 PM, Xavier Fernandez <xav.fernandez at gmail.com
> > wrote:
>
>> I think the point was not to say that documentation is useless (and there
>> is some: http://flit.readthedocs.org/en/latest/ ) but that the
>> code/implementation is much simpler than the combination of
>> distutils/setuptools/bdist_wheel.
>>
>> On Mon, Mar 30, 2015 at 5:26 PM, Ian Cordasco <graffatcolmingov at gmail.com
>> > wrote:
>>
>>>
>>> So for new python programmers (or newbie users in general) reading the
>>> entire source of another package to understand it is a better experience?
>>>
>>> ​
> ​To put that in context, flit goes for less than 600 SLOC while
> distutils+setuptools+wheel amount to​ over 20000 SLOC. At that ratio
> arguments for distutils+setuptools+wheel documentation seem unreasonable.
>

To be clear, no one should ever be advocating to "just read the source" as
a form of documentation. This is why the Packaging guide exists (because no
one should ever be expected to read the distutils, setuptools, or wheel
source to use it).

Code is never as self-documenting as people like to believe. And since
we're talking about new users (without defining what they're new to)
reading the source should only be for educational purposes. cookiecutter
will serve new users better than flit or anything else. cookiecutter will
teach new users good package structure and take care of the (possibly hard
parts) of a setup.py. Then, when the "new user" goes to publish it, there's
tons of prior documentation on how to do it. If they run into problems
using flit they have the skimpy documentation or the source.

Yeah, it's "easy" to read 600 SLOC for you, but what about for some "new
user"? Are they new to python? Why do they have to care about reading the
source if something else will "just work" as documented for their "simple"
use case?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/distutils-sig/attachments/20150330/97c9ec2d/attachment.html>