Hi Éric, Thanks for the feedback, and my apologies for the delay in responding.
On Mar 25, 2011, at 03:52 AM, Éric Araujo wrote: >> `distutils2` [1]_) may be adapted to use the conventions defined here. >Nit: I never rely on docutils/sphinx default role (using a bare `text` >without explicit :role:), cause I never remember what it is, and the >produced text may not be what you thought it would. EIBTI :). Thanks. >> Alice is writing a new module, called ``alice.py``, which she wants to >> share with other Python developers. ``alice.py`` is a simple module >> and lives in one file. >You should call the module alice and the file alice.py to eliminate >weirdness. (Ditto for other examples throughout the PEP.) Excellent point. >> Bob learns about the Cheeseshop [2]_, and adds some >> simple packaging using classic distutils so that he can upload *The >> Bob Package* to the Cheeseshop. >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>. In this case I'm changing it to *The Bob Bundle* since that's sufficiently meaningless as to not be distracting. >> 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). On one hand it would be >childish not to acknowledge that setuptools is widely used, on the other >hand in this particular time and place I think we should wait for >official namespace packages to be implemented and talk about those. >That said, even if the mechanism changes, the packaging-related parts >won’t, so the story is useful. Make that +0 after all. 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. >> at *sdist* tarball build time. >Do non-UNIX people understand “tarball”? You could remove it or replace >it with “archive”. Good point. I've rewritten this to read: "...extract the module version number when she builds the *sdist* archive." >> David maintains a package in the standard library, and also produces >> standalone versions for other versions of Python. >Thoughtful hat tip :) Kind of worked out that way! :) >> Often, version numbers >> can be retrieved from a module programmatically, by importing the >> module and inspecting an attribute. Classic Python distutils >> ``setup()`` functions [3]_ describe a ``version`` argument where the >> package's version number can be specified. >See above for package vs. distribution terminology. s/package's version number/release's version number/ >This makes me think: It is obvious to us that Python packages are a type >of Python modules, but the PEP could mention that near the beginning, to >make clear that your PEP is relevant to any kind of module, whatever its >physical incarnation. Hmmm. OT1H I can see your point, but OTOH, I can't really find a good place to squeeze that definition in, and I'm not certain defining this is a goal of the PEP. For example, I don't really like adding that to the Abstract, or as a separate section between Abstract and User Stories. I kind of think that it should be fairly self-evident for any experienced Pythonista. >> 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. :) (Sadly, I just missed April Fools, or I would have suggested a PEP to add a __mifflin__ attribute to all objects. What joy that would bring to Python conversations.) >> Another example of version information is the sqlite3 [5]_ library >the sqlite3 module > >> This informational PEP codifies established practice, and recommends >> standard ways of describing module version numbers, along with some >> use cases for when -- and when *not* -- to include them. Its adoption >> is purely voluntary, but other tools in the Python universe may >> support the standards defined herein. >You say “other tools“ without having referred to tools before, I find it >confusing (I’m not a native speaker, however). The text could mention >here that official tools will have opt-in support for the PEP: > > Its adoption is purely voluntary; the packaging tools in the standard > library will provide optional support for the standards defined herein > (see section XX), and other tools in the Python universe may comply > too. I rewrote this just slightly: This informational PEP codifies established practice, and recommends standard ways of describing module version numbers, along with some use cases for when -- and when *not* -- to include them. Its adoption by module authors is purely voluntary; packaging tools in the standard library will provide optional support for the standards defined herein, and other tools in the Python universe may comply as well. >> #. On a case-by-case basis, standard library modules which are also >> distributed as standalone packages for other Python versions MAY >Problematic “packages” again. What about this: “which are also released >in standalone form for other Python versions”? Looks good, thanks. >> #. 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. (Aside: using :file:`file.py` produces a warning when the PEP html is generated: pep-0396.txt:31: (ERROR/3) Unknown interpreted text role "file".) >> #. For modules which live inside a namespace package, the sub-package >> name SHOULD include the ``__version__`` attribute. >I think this works with both setuptools and PEP 382 namespace packages, >which is nice (see above questioning). > >> The namespace module itself SHOULD NOT include its own >> ``__version__`` attribute. >I guess this makes sense for setuptools namespace packages, but from my >understanding of PEP 382, it is possible to have a Python package that >is a namespace package and has submodules. (I hope Martin will correct >me if needed.) This thing (“portion” in PEP 382 lingo) should be >allowed to declare a version IMO. Agreed, if that is true. I kind of hope it's *not* true though! Anyway, this is a SHOULD NOT not MUST NOT so I think it's safe. >> #. The ``__version__`` attribute's value SHOULD be a simple string. >What’s a non-simple string? This may be only me, but here I think you >tried to be simple and had the opposite effect. I’d just use the simple >“a string” or the precise “a string (str object in 3.x)”. s/simple// >> #. 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: #. The ``version`` attribute in a classic distutils ``setup.py`` file, or the PEP 345 [7]_ ``Version`` metadata field SHOULD be derived from the ``__version__`` field, or vice versa. >I think this part should either take a position, that is choose one way >instead of vaguely telling about two ways, or be removed, given that the >section Deriving has the same info. I'm not sure we can make that recommendation yet though. I'd prefer to derive everything from the __version__, but I'm not sure there's agreement on that. Leaving it this way for now allows for some experimentation. >> They also need to be specified in either the classic distutils >> ``setup()`` function, as the ``version`` attribute in a ``setup.py``, >> or in the distutils2 ``setup.cfg`` file's ``version`` keyword, >I’d say the setup.py has a version argument and the setup.cfg has a >version key. > >> they need to get into the PEP 345 package metadata, preferably at >> *sdist* package build-time. >s/package metadata/metadata/; s/*sdist* package/*sdist*/ Module version numbers can appear in at least two places, and sometimes more. For example, in accordance with this PEP, they are available programmatically on the module's ``__version__`` attribute. In a classic distutils ``setup.py`` file, the ``setup()`` function takes a ``version`` argument, while the distutils2 ``setup.cfg`` file has a ``version`` key. The version number must also get into the PEP 345 metadata, preferably when the *sdist* archive is built. It's desirable for module authors to only have to specify the version number once, and have all the other uses derive from this single definition. >> In the PEP author's experience however, this can fail in some cases, >> such as when the module uses automatic Python 3 conversion via the >> ``2to3`` program. >Just to make this 100% explicit, you could add “because the setup.py >script is executed by Python 3 before the elle module has been converted”. I added this, though I'm not sure if flows as well. >> In that case, it's not much more difficult to write a little code >> to parse the ``__version__`` from the file rather than >The function could be simplified (use re.search, hard-code the re), but >that’s very minor. Indeed. > >> 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. >> An alternative is to only define the version number in setup.cfg and >> use the ``pkgutil`` module [8]_ to make it available >> programmatically. E.g. in ``elle.py``:: >> >> from distutils2._backport import pkgutil >> __version__ = pkgutil.get_distribution('elle').metadata['version'] >One of the main complaint against setuptools is that having to change >your application code because of the packaging tool used was not a good >idea. Having to use require instead of import or resource_whatever >instead of open (or get_data, the most sadly underused function in the >stdlib) because you use setuptools instead of distutils was a bad thing. > >As stated in the PEP, having a __version__ attribute in the module is >common, so my opinion is that making the packaging tool use that info is >the Right Thing™, and having the dependency in the reverse sense is >wrong. I don’t see a problem with having harmless duplication in the >*installed* system, once in elle.__version__ and once in the pkgutil >metadata database. I'm including this section because at Pycon, some people did express an interest in deriving the version number in this direction. I wanted to capture what that might look like. Since this is an informational PEP, I think it makes sense to include alternative approaches, but I tend to agree with you that it will be much more common to define module.__version__ and derive the metadata from that. >(FWIW, I personally think that it’s not crazy to have the version number >duplicated in the module, setup script, changelog, Sphinx conf.py file >and so on; other people like Ronny don’t even want to have the version >number in one file, but make their build process use the VCS tag. I >think this PEP addresses a useful middle ground.) Cool. > >> Static egg info >Is that the distutils 2.5+ generated metadata? You may want to read PEP >376 and update the terminology to “dist-info metadata” <0.2 wink>. I meant it in more general terms, that any metadata using the derived version number is better off being derived at build time rather than install time. PEP 376 doesn't really talk much about the process by which the metadata files are created, so I'm not sure referencing it is appropriate. Hmm, let me think about that section. (Side note: PEP 376 could probably benefit from a glossary. Its abstract starts off by using the term "project distributions" but doesn't provide any definition of what "project" means or what "distributions" are. As I mentioned before, if you want folks to adopt a specific terminology, I think you're going to need a separate informational PEP that explicitly defines that terminology.) Hmm, okay, I took a crack at rewriting this section: PEP 376 metadata ================ PEP 376 [9]_ defines a standard for static metadata, but doesn't describe the process by which this metadata gets created. It is highly desirable for the derived version information to be placed into the PEP 376 ``.dist-info`` metadata at build-time rather than install-time. This way, the metadata will be available for introspection even when the code is not installed. >> For example, a package's metadata can be made available via a simple >> HTTP GET operation on a URL within the package's presence on the >> Cheeseshop. >First, insert usual remark about “package” here; second, I think >discussing PyPI is out of scope here. The rationale that “the metadata >will be available for introspection even when the code is not installed“ >is already strong enough. > >> .. [1] Distutils2 documentation >> (http://distutils2.notmyidea.org/) >Alexis, is this still the good link to use? Again, thanks for the feedback. I'm going to do another pass through the PEP, then check it in, and post it to python-dev. Cheers, -Barry
signature.asc
Description: PGP signature
_______________________________________________ Distutils-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/distutils-sig
