[Distutils] DRAFT PEP 396 - module version number

[Éric Araujo]

 Hi,

 Glad to read my review helped :)

>> I know that the referenced PEP 345 call these things “software
>> packages”, but let’s try to use consistent terminology.  See threads
>> starting at
>> 
>> http://mail.python.org/pipermail/distutils-sig/2011-March/017438.html
>> and 
>> http://mail.python.org/pipermail/distutils-sig/2011-March/017450.html 
>> .
> I remember that discussion, but I don't actually remember if there 
> was
> agreement on terminology. ;)  I'm sympathetic to Jim's Elaboration On 
> PJE's
> Glossary.  That would make a worthy PEP for someone else to write 
> <wink>.

 Ah, right, I probably have extrapolated the distutils2 consensus.  I’m
 not sure I should be the one to write this PEP, I already have enough 
 of
 a nitpicker reputation.  Maybe if a distutils-sig veteran accepts to be
 a co-writer.

> In this case I'm changing it to *The Bob Bundle* since that's 
> sufficiently
> meaningless as to not be distracting.

 I also think that “bundle” is a nice term to name what the docs
 currently calls a distribution.

>>> Carole maintains several namespace packages, each of which are
>>> independently developed and distributed.
>> I am not sure we should advertise setuptools namespace packages, 
>> given
>> that standardization is under way (PEP 382).  [...]
> Right.  This is just a use case and it doesn't mention setuptools
> specifically, even though it does mention setup.py.  Everybody knows 
> what the
> latter is, and I can't think of any better way to phrase this, so I 
> guess I'll
> leave it.

 As PJE helpfully corrected, namespaces packages are not tied to
 setuptools, even though in practice they mostly are.  The current PEP
 text is therefore fine.

>>> of an ``__version__`` module attribute by independent module
>> s/an/a/
> Heh, yeah I'm old skool so I still pronounce it "under under".  
> Saying
> "dunder" just reminds me too much of The Office to take seriously. :)

 I write about Python much more than I talk about it, so I pronounce it
 “version” (or more exactly, I say “init” when I talk about “__init__”,
 or “underscore-underscore-init-underscore-underscore” when I need total
 explicitness).  I never read or heard “dunder”.

>>> Another example of version information is the sqlite3 [5]_ library
>> the sqlite3 module

 You overlooked that one.

>>> #. For modules which are also packages, the top level module 
>>> namespace
>>>    SHOULD include the ``__version__`` attribute.
>> Just a remark: I don’t remember ever reading the term “top-level 
>> module
>> namespace”.  It’s not hard to understand, but it might be helpful to
>> some readers if you add “(i.e. the :file:`{somepackage}/__init__.py`
>> file)”.  (The brackets will cause the enclosed text to be marked up 
>> as
>> replaceable text, just a nicety.)
> How about just removing "top-level"?
>
>     #. For modules which are also packages, the module namespace 
> SHOULD
>        include the ``__version__`` attribute.

 I’m still not sure “module namespace” will be clear to everyone.

> (Aside: using :file:`file.py` produces a warning when the PEP html is
> generated:

 Fooled again: it’s a Sphinx-specific role, not a docutils one.  Forget
 my advice and use ````.

>>> #. The ``version`` attribute in a classic distutils ``setup.py`` 
>>> file,
>>>    or the ``Version`` metadata field in a PEP 345 [7]_ SHOULD be
>>>    derived from the ``__version__`` field, or vice versa.
>> “In a PEP 345” what? :) file, I guess.
> Oops, IIUC there really isn't a PEP 345 "thing" so I've rewritten it 
> like
> this:

 There is actually a METADATA file, but your rewrite is good without
 mentioning that.

>>> Because the distutils2 style ``setup.cfg`` is declarative, we can't
>>> run any code to extract the ``__version__`` attribute, either via
>>> import or via parsing.  This PEP suggests a special key be allowed 
>>> for
>>> the ``version`` field in a ``setup.cfg`` file to indicate "get the
>>> version from this file".
>> With my distutils2 hat on, I recommend a KISS approach similar to 
>> what’s
>> done for the long description: just define another key in the 
>> setup.cfg
>> specification:
>>
>>  [metadata]
>>  version-from-file: elle.py
> It's an open issue, but we definitely want built-in support from
> distutils2/packaging.  This section was one of the main reasons why I 
> posted
> here first, because I really wanted to get feedback on how best to 
> support
> this in a setup.cfg file.  I've changed the example to your text 
> above, since
> it does seem cleaner.  Though if we get more universal adoption of 
> the PEP, I
> suspect version-from-file will be much more popular than version, so 
> we might
> want to address keeping the common case simple.

 Tarek already ruled last summer that field names in setup.cfg have to
 have their PEP 345 name.  I proposed to merge author name and email 
 into
 the author field, and to have the description field always refer to a
 file: author and author_email are still separate, and a new
 description_from_file fields has been added.  That’s why I think a new
 field has to be defined.  version-from should be a short enough name.  
 I
 also expect most people to use copy-paste or the interactive setup.cfg
 creation helper, so field name length should not be that big of an 
 issue.

 Now on to defuse FUD on python-dev.

 Regards