[Distutils] DRAFT PEP 396 - module version number
Hi distutilizers! At Pycon, I signed up to write an informational PEP on module version numbers. There have been some email discussion since then, and while I haven't completely worked my way through all those messages yet, I think I have covered the important top-level issues. I'm posting my current draft (as yet uncommitted to the new hg repository) here before taking it to python-dev. I'd love to get your feedback about any aspect of the PEP, but especially on deriving module version numbers from setup.cfg files, and on including them in metadata at build time (as opposed to installation time). Also, I'd appreciate any corrections based on my misunderstanding of distutils2/packaging and the relevant PEPs. Current draft attached below. Remember, this is an informational PEP, so its purpose is to codify best practices. Module authors will continue to have the freedom to do whatever they want. Cheers, -Barry PEP: 396 Title: Module Version Numbers Version: $Revision: 65628 $ Last-Modified: $Date: 2008-08-10 09:59:20 -0400 (Sun, 10 Aug 2008) $ Author: Barry Warsaw Status: Draft Type: Informational Content-Type: text/x-rst Created: 2011-03-16 Post-History: Abstract Given that it is useful and common to specify version numbers for Python modules, and given that different ways of doing this have grown organically within the Python community, it is useful to establish standard conventions for module authors to adhere to and reference. This informational PEP describes best practices for Python module authors who want to define the version number of their Python module. Conformance with this PEP is optional, however other Python tools (such as `distutils2` [1]_) may be adapted to use the conventions defined here. User Stories 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. Alice wants to specify a version number so that her users can tell which version they are using. Because her module lives entirely in one file, she wants to add the version number to that file. Bob has written a module called ``bob.py`` which he has shared with many users. ``bob.py`` contains a version number for the convenience of his users. 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. Because ``bob.py`` already specifies a version number which his users can access programmatically, he wants the same API to continue to work even though his users now get it from the Cheeseshop. Carole maintains several namespace packages, each of which are independently developed and distributed. In order for her users to properly specify dependencies on the right versions of her packages, she specifies the version numbers in the namespace package's ``setup.py`` file. Because Carol wants to have to update one version number per package, she specifies the version number in her module and has the ``setup.py`` extract the module version number at *sdist* tarball build time. David maintains a package in the standard library, and also produces standalone versions for other versions of Python. The standard library copy defines the version number in the module, and this same version number is used for the standalone distributions as well. Rationale = Python modules, both in the standard library and available from third parties, have long included version numbers. There are established de-facto standards for describing version numbers, and many ad-hoc ways have grown organically over the years. 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. PEP 8 [4]_ describes the use of a module attribute called ``__version__`` for recording "Subversion, CVS, or RCS" version strings using keyword expansion. In the PEP author's own email archives, the earliest example of the use of an ``__version__`` module attribute by independent module developers dates back to 1995. Another example of version information is the sqlite3 [5]_ library with its ``sqlite_version_info``, ``version``, and ``version_info`` attributes. It may not be immediately obvious which attribute contains a version number for the module, and which contains a version number for the underlying SQLite3 library. 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. Specification = #. In general, modules in the standard library SHOULD NOT have version numbers
Re: [Distutils] DRAFT PEP 396 - module version number
Hi Barry,
Thanks for writing this PEP. I’m +1 on the general idea, but not on all
sections. I agree with all text that I haven’t quoted; quoted parts are
commented with my reservations, suggested amendments and typo fixes.
Martin and Alexis are directly cc’d because I have asked them to confirm
or reply to two things that I wasn’t sure about.
> `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.
> 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.)
> 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 .
> 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.
> at *sdist* tarball build time.
Do non-UNIX people understand “tarball”? You could remove it or replace
it with “archive”.
> David maintains a package in the standard library, and also produces
> standalone versions for other versions of Python.
Thoughtful hat tip :)
> 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.
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.
> of an ``__version__`` module attribute by independent module
s/an/a/
> 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.
> #. 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”?
> #. 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.)
> #. 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) shou
Re: [Distutils] DRAFT PEP 396 - module version number
On 25/03/2011 02:52, Éric Araujo wrote: > .. [1] Distutils2 documentation > (http://distutils2.notmyidea.org/) Alexis, is this still the good link to use? Yes, at least for now. Waiting for docs.python.org ;) -- Alexis — http://notmyidea.org ___ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
Re: [Distutils] DRAFT PEP 396 - module version number
On March 24, 2011, Éric Araujo wrote: > > 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 . Éric, can you summarize the discussion that took place on these threads? As far as I can tell, no consensus was reached for a new terminology and so the old definition still prevails: http://docs.python.org/dev/distutils/introduction#concepts-terminology In that case, a "package" in PEP 396 would refer to: a module that contains other modules; typically contained in a directory in the filesystem and distinguished from other directories by the presence of a file __init__.py. I fell like the usage proposed for *The Bob Package* is pretty good, except for the choice of "upload". Of course, you don't upload the package, you upload "distributions" that contain that package. -- Yannick Gingras http://ygingras.net signature.asc Description: This is a digitally signed message part. ___ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
Re: [Distutils] DRAFT PEP 396 - module version number
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 . 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 Py
Re: [Distutils] DRAFT PEP 396 - module version number
On Mar 27, 2011, at 03:36 PM, Yannick Gingras wrote: >On March 24, 2011, Éric Araujo wrote: >> > 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 . > >Éric, can you summarize the discussion that took place on these >threads? As far as I can tell, no consensus was reached for a new >terminology and so the old definition still prevails: > > http://docs.python.org/dev/distutils/introduction#concepts-terminology As I mentioned in my follow up to Éric, if you really want to encourage adoption of specific terms, you're probably going to need to write a PEP that clearly defines them. Referencing a mailing list thread ain't gonna cut it. >In that case, a "package" in PEP 396 would refer to: > > a module that contains other modules; typically contained in a > directory in the filesystem and distinguished from other directories > by the presence of a file __init__.py. > >I fell like the usage proposed for *The Bob Package* is pretty good, >except for the choice of "upload". Of course, you don't upload the >package, you upload "distributions" that contain that package. See my previous follow up. -Barry signature.asc Description: PGP signature ___ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
Re: [Distutils] DRAFT PEP 396 - module version number
At 10:31 AM 4/5/2011 -0400, Barry Warsaw wrote: On Mar 25, 2011, at 03:52 AM, Ãric Araujo wrote: >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. Just as an FYI, "official" namespace packages have existed since Python 2.3; they are implemented using pkgutil.extend_path() -- added, IIRC, back when Guido and Barry were both working at Zope Corp. ;-) Setuptools and PEP 382 are simply enhanced implementations of the concept. >> #. 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. In principle, if you simply *must* have a non-empty __init__ module in a namespace package, and you really need to have a __version__ of that, then I suppose its __version__ should match the version of the project that supplies it. But yeah, I think it should still be considered a poor practice to put stuff in a namespace's __init__, even if/when PEP 382 makes it practical to implement non-empty __init__'s. ___ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
Re: [Distutils] DRAFT PEP 396 - module version number
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
.
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, s
Re: [Distutils] DRAFT PEP 396 - module version number
On Apr 09, 2011, at 06:23 PM, Éric Araujo wrote:
> Glad to read my review helped :)
Indeed, thanks.
> I also think that “bundle” is a nice term to name what the docs
> currently calls a distribution.
At the very least, *bundle* isn't completely overloaded 10x over in Pythonland
yet. :)
Another example of version information is the sqlite3 [5]_ library
>>> the sqlite3 module
>
> You overlooked that one.
Got it.
#. 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.
Really? We know what a module is, and we know what a namespace is, so given
the context, I think it should be clear.
> 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.
Perhaps. In lieu of a better idea it's fine for now.
-Barry
signature.asc
Description: PGP signature
___
Distutils-SIG maillist - Distutils-SIG@python.org
http://mail.python.org/mailman/listinfo/distutils-sig
Re: [Distutils] DRAFT PEP 396 - module version number
Hi, Just two things I thought about while perusing my archives yesterday. >>> #. 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. > > Really? We know what a module is, and we know what a namespace is, so given > the context, I think it should be clear. FYI, I noticed that PEP 382 (namespace packages) says “the namespace package itself” to refer to the corp/__init__.py file of the corp.somelib package. In the Python tutorial, we have things like “the __init__.py code”. So it looks like there’s no agreed term to refer to this module. A note about the setup.cfg field used to get the version from a file: It will definitely need to use another name than “version”: Tarek wants the setup.cfg field to be a direct translation from PEP 345 (modulo case insensitivity), so the description-file is another field, and version-file should certainly be one too. (I hope it’s short enough to comply with your wish of keeping the common case simple.) Regards ___ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
Re: [Distutils] DRAFT PEP 396 - module version number
Hi Éric, On Jun 07, 2011, at 05:30 PM, Éric Araujo wrote: >Just two things I thought about while perusing my archives yesterday. > #. 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. >> >> Really? We know what a module is, and we know what a namespace is, so given >> the context, I think it should be clear. > >FYI, I noticed that PEP 382 (namespace packages) says “the namespace >package itself” to refer to the corp/__init__.py file of the >corp.somelib package. In the Python tutorial, we have things like “the >__init__.py code”. So it looks like there’s no agreed term to refer to >this module. So, what *should* we call this thing? Note that in the PEP, I'm specifically talking about the namespace, not the file. Maybe "module's namespace" would be clearer? >A note about the setup.cfg field used to get the version from a file: It >will definitely need to use another name than “version”: Tarek wants the >setup.cfg field to be a direct translation from PEP 345 (modulo case >insensitivity), so the description-file is another field, and >version-file should certainly be one too. (I hope it’s short enough to >comply with your wish of keeping the common case simple.) The PEP currently uses `version-from-file` which seems okay to me. Would that work? -Barry signature.asc Description: PGP signature ___ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
Re: [Distutils] DRAFT PEP 396 - module version number
Barry Warsaw writes: > Hi Éric, > > On Jun 07, 2011, at 05:30 PM, Éric Araujo wrote: > > >Just two things I thought about while perusing my archives yesterday. > > > #. 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. […] Agreed. Damn English and its ample opportunities for ambiguity. > So, what *should* we call this thing? Note that in the PEP, I'm > specifically talking about the namespace, not the file. Maybe > "module's namespace" would be clearer? +1. I think the grammar could be even clearer: For modules which are also packages, the ``__version__`` attribute SHOULD be in the module's namespace. -- \ “The opposite of a correct statement is a false statement. But | `\ the opposite of a profound truth may well be another profound | _o__) truth.” —Niels Bohr | Ben Finney pgpRaz71oLCew.pgp Description: PGP signature ___ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
Re: [Distutils] DRAFT PEP 396 - module version number
On Tue, Jun 7, 2011 at 11:48 PM, Ben Finney wrote: > For modules which are also packages, the ``__version__`` attribute > SHOULD be in the module's namespace. This suggests to me that there's no need to describe it as a special case. A importable directory contains an __init__.py; it's represented as a module at runtime, just like any other. -Fred -- Fred L. Drake, Jr. "Give me the luxuries of life and I will willingly do without the necessities." --Frank Lloyd Wright ___ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
Re: [Distutils] DRAFT PEP 396 - module version number
Given Ben's and Fred's feedback, what do you think about this list in the Specification's section: #. In general, modules in the standard library SHOULD NOT have version numbers. They implicitly carry the version number of the Python release they are included in. #. On a case-by-case basis, standard library modules which are also released in standalone form for other Python versions MAY include a module version number when included in the standard library, and SHOULD include a version number when packaged separately. #. When a module (or package) includes a version number, the version SHOULD be available in the ``__version__`` attribute. #. For modules which live inside a namespace package, the sub-package name SHOULD include the ``__version__`` attribute. The namespace module itself SHOULD NOT include its own ``__version__`` attribute. #. The ``__version__`` attribute's value SHOULD be a string. #. Module version numbers SHOULD conform to the normalized version format specified in PEP 386 [6]_. #. Module version numbers SHOULD NOT contain version control system supplied revision numbers, or any other semantically different version numbers (e.g. underlying library version number). #. 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. -Barry signature.asc Description: PGP signature ___ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
Re: [Distutils] DRAFT PEP 396 - module version number
Barry Warsaw writes: > #. The ``__version__`` attribute's value SHOULD be a string. I may be fighting against the tide here; but this screams to me that the PEP should not be talking at all about “version number” (except to point out that they're strings, not numbers). Instead, the term should be “version string” throughout. Much damage is done to understanding version strings by calling them “version numbers”, with all the baggage about parsing and sequencing etc. that entails. We don't have to make the same mistake in this PEP. -- \ “He may look like an idiot and talk like an idiot but don't let | `\ that fool you. He really is an idiot.” —Groucho Marx | _o__) | Ben Finney pgpzMM8LaKN5W.pgp Description: PGP signature ___ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
Re: [Distutils] DRAFT PEP 396 - module version number
Barry Warsaw writes: > #. When a module (or package) includes a version number, the version >SHOULD be available in the ``__version__`` attribute. > > #. For modules which live inside a namespace package, the sub-package >name SHOULD include the ``__version__`` attribute. The namespace >module itself SHOULD NOT include its own ``__version__`` attribute. I still find a little ambiguity in “the ``__version__`` attribute”, but it's much improved, thanks. I think those paragraphs are good. -- \ “It is clear that thought is not free if the profession of | `\ certain opinions makes it impossible to earn a living.” | _o__) —Bertrand Russell, _Free Thought and Official Propaganda_, 1928 | Ben Finney pgpluWOIsEqsP.pgp Description: PGP signature ___ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
Re: [Distutils] DRAFT PEP 396 - module version number
On Wed, Jun 8, 2011 at 6:14 PM, Barry Warsaw wrote: > #. For modules which live inside a namespace package, the sub-package > name SHOULD include the ``__version__`` attribute. The namespace > module itself SHOULD NOT include its own ``__version__`` attribute. I've no idea what you're saying here. What's a sub-package? If you're referring to a package like zope.testing, I'd just call that a package; there's nothing special about that. I'd expect the __version__, if it exists, to be present in the file zope/testing/__init__.py. An namespace package, like zope or zc, should not have a __version__. Ben Finney wrote: > I may be fighting against the tide here; but this screams to me that the > PEP should not be talking at all about “version number” (except to point > out that they're strings, not numbers). Instead, the term should be > “version string” throughout. I'd rather we just say 'version' instead of 'version number' or 'version string'. Natural use of natural language is... natural. A separate sentence can state simply that versions are expressed as strings. -Fred -- Fred L. Drake, Jr. "Give me the luxuries of life and I will willingly do without the necessities." --Frank Lloyd Wright ___ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
Re: [Distutils] DRAFT PEP 396 - module version number
Fred Drake writes: > On Wed, Jun 8, 2011 at 6:14 PM, Barry Warsaw wrote: > > #. For modules which live inside a namespace package, the sub-package > > name SHOULD include the ``__version__`` attribute. The namespace > > module itself SHOULD NOT include its own ``__version__`` attribute. > > I've no idea what you're saying here. What's a sub-package? Moreover, how can a “sub-package name” include an attribute? I agree that needs to be clarified. > If you're referring to a package like zope.testing, I'd just call that a > package; there's nothing special about that. I'd expect the __version__, > if it exists, to be present in the file zope/testing/__init__.py. Yes, but how to specify that? The ‘__init__.py’ file is a module. What's that, then; a package module? > Ben Finney wrote: > > I may be fighting against the tide here; but this screams to me that the > > PEP should not be talking at all about “version number” (except to point > > out that they're strings, not numbers). Instead, the term should be > > “version string” throughout. > > I'd rather we just say 'version' instead of 'version number' or 'version > string'. Natural use of natural language is... natural. A separate > sentence can state simply that versions are expressed as strings. −1. A version is a state of the code base at a point in its development; what we're talking about here are strings which act as identifiers for versions of the code. I would argue for “version identifier”, but that has virtually no actual use :-) -- \ “I was sleeping the other night, alone, thanks to the | `\ exterminator.” —Emo Philips | _o__) | Ben Finney ___ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
Re: [Distutils] DRAFT PEP 396 - module version number
I wrote: > If you're referring to a package like zope.testing, I'd just call that a > package; there's nothing special about that. I'd expect the __version__, > if it exists, to be present in the file zope/testing/__init__.py. Ben Finney responded > Yes, but how to specify that? The ‘__init__.py’ file is a module. What's > that, then; a package module? The package zope.testing includes the module zope.testing (implemented in zope/testing/__init__.py), as well as other modules (zope.testing.cleanup for example). The zope.testing module SHOULD contain any appropriate __version__ attribute. The only real special cases are "namespace" packages like zc, zope, and many others. Since those are *not* tied to a single distribution, they SHOULD NOT have __version__ attributes. (I think we agree on this, but language is tedious, since there are many casual uses of the term 'package' here, and 'namespace packages' aren't as commonly known outside particular segments of the community.) -Fred -- Fred L. Drake, Jr. "Give me the luxuries of life and I will willingly do without the necessities." --Frank Lloyd Wright ___ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
Re: [Distutils] DRAFT PEP 396 - module version number
Hi, > The PEP currently uses `version-from-file` which seems okay to me. Would that > work? Yes, the PEP uses that field since I said I thought it could not reuse the version field; my email was meant to change “I think it should be another field” to “it must definitely be another field”. version-from-file is a good name if a regex is applied to extract a version from the first lines of a file; if the whole contents of the file are the version number (sorry Ben, I cannot call it something else :), it should be version-file to mirror description-file. Regards ___ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
Re: [Distutils] DRAFT PEP 396 - module version number
On Jun 09, 2011, at 10:42 AM, Ben Finney wrote: >Barry Warsaw writes: > >> #. The ``__version__`` attribute's value SHOULD be a string. > >I may be fighting against the tide here; but this screams to me that the >PEP should not be talking at all about “version number” (except to point >out that they're strings, not numbers). Instead, the term should be >“version string” throughout. As I was doing the last edit, I did think about that. The suggestion is not without merit, but I also think "version number" is a commonly accepted term for what this thing is. I mean, we've used that term for ages to describe things like 2.6.7, which clearly isn't a number. -Barry signature.asc Description: PGP signature ___ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
Re: [Distutils] DRAFT PEP 396 - module version number
On Jun 09, 2011, at 01:29 PM, Éric Araujo wrote: >Yes, the PEP uses that field since I said I thought it could not reuse >the version field; my email was meant to change “I think it should be >another field” to “it must definitely be another field”. > >version-from-file is a good name if a regex is applied to extract a >version from the first lines of a file; if the whole contents of the >file are the version number (sorry Ben, I cannot call it something else >:), it should be version-file to mirror description-file. Hi Éric, I hadn't thought about a file that only contains the version number, but that makes perfect sense. Here's what I propose for the PEP. Distutils2 -- 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. In consultation with the distutils-sig [9]_, two options are proposed. Both entail containing the version number in a file, and declaring that file in the ``setup.cfg``. When the entire contents of the file contains the version number, the ``version-file`` key will be used:: [metadata] version-file: version.txt When the version number is contained within a larger file, e.g. of Python code, such that the file must be parsed to extract the version, the key ``version-from-file`` will be used:: [metadata] version-from-file: elle.py A parsing method similar to that described above will be performed on the file named after the colon. The exact recipe for doing this will be discussed in the appropriate distutils2 development forum. Cheers, -Barry signature.asc Description: PGP signature ___ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
Re: [Distutils] DRAFT PEP 396 - module version number
On Jun 08, 2011, at 10:47 PM, Fred Drake wrote: >On Wed, Jun 8, 2011 at 6:14 PM, Barry Warsaw wrote: >> #. For modules which live inside a namespace package, the sub-package >> name SHOULD include the ``__version__`` attribute. The namespace >> module itself SHOULD NOT include its own ``__version__`` attribute. > >I've no idea what you're saying here. What's a sub-package? It's a package that lives within another package. >If you're referring to a package like zope.testing, I'd just call that a >package; there's nothing special about that. I'd expect the __version__, >if it exists, to be present in the file zope/testing/__init__.py. That's where I'd expect __version__ too, and it's what the PEP tries to say. Unfortunately, I think it's ambiguous to change "sub-package" to "package" here; it just isn't clear. We're hampered by a lack of consistent terminology in the Python world about these things. I'm willing to add some definitions to the PEP to help make things clearer, or to rewrite something, but we first need to agree on what to call these things. :) >An namespace package, like zope or zc, should not have a __version__. Agreed. Is this any clearer? #. For modules which live inside a namespace package, the module SHOULD include the ``__version__`` attribute. The namespace package itself SHOULD NOT include its own ``__version__`` attribute. >Ben Finney wrote: >> I may be fighting against the tide here; but this screams to me that the >> PEP should not be talking at all about “version number” (except to point >> out that they're strings, not numbers). Instead, the term should be >> “version string” throughout. > >I'd rather we just say 'version' instead of 'version number' or 'version >string'. Natural use of natural language is... natural. A separate >sentence can state simply that versions are expressed as strings. #. The ``__version__`` attribute's value SHOULD be a string. I still don't have a problem with using "version number" to express what these things are. We have oodles of existing practice on this. -Barry signature.asc Description: PGP signature ___ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
Re: [Distutils] DRAFT PEP 396 - module version number
On Jun 09, 2011, at 12:31 AM, Fred Drake wrote: >(I think we agree on this, but language is tedious, since there are many >casual uses of the term 'package' here, and 'namespace packages' aren't as >commonly known outside particular segments of the community.) I think "namespace package" is a pretty commonly accepted term in the Python community. See PEP 382. -Barry signature.asc Description: PGP signature ___ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
