improve the readability of one section

This commit is contained in:
Barry Warsaw 2012-05-03 14:30:48 -04:00
parent ca0189a132
commit 6f8d74ea28
2 changed files with 25 additions and 14 deletions

View File

@ -102,15 +102,13 @@ Specification
module version number when included in the standard library, and
SHOULD include a version number when packaged separately.
#. When a module includes a version number, it SHOULD be available in
the ``__version__`` attribute on that module.
#. When a module (or package) includes a version number, the version
SHOULD be available in the ``__version__`` attribute.
#. For modules which are also packages, the module's namespace SHOULD
include 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.
#. 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.
#. The ``__version__`` attribute's value SHOULD be a string.
@ -218,9 +216,20 @@ 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. This PEP suggests a special key be added to
the ``[metadata]`` section of the ``setup.cfg`` file to indicate "get
the version from this file". Something like this might work::
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
@ -240,7 +249,7 @@ programmatically. E.g. in ``elle.py``::
PEP 376 metadata
================
PEP 376 [9]_ defines a standard for static metadata, but doesn't
PEP 376 [10]_ 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
@ -274,7 +283,9 @@ References
.. [8] pkgutil - Package utilities
(http://distutils2.notmyidea.org/library/pkgutil.html)
.. [9] PEP 376, Database of Installed Python Distributions
.. [9] http://mail.python.org/pipermail/distutils-sig/2011-June/017862.html
.. [10] PEP 376, Database of Installed Python Distributions
(http://www.python.org/dev/peps/pep-0376/)

View File

@ -174,7 +174,7 @@ not contain a trailing path separator.
There is no impact on PEP 302 "loaders".
If an existing finder is not updated to support returning a string
from ``find_module``, the only impact is that such a loader will be
from ``find_module``, the only impact is that such a finder will be
unable to provide portions of a namespace package.
Packaging Implications