From 6f8d74ea28c100b984d02f0bd249be8e8a2b95d7 Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Thu, 3 May 2012 14:30:48 -0400 Subject: [PATCH] improve the readability of one section --- pep-0396.txt | 37 ++++++++++++++++++++++++------------- pep-0420.txt | 2 +- 2 files changed, 25 insertions(+), 14 deletions(-) diff --git a/pep-0396.txt b/pep-0396.txt index e653d4b5c..8fca4bd32 100644 --- a/pep-0396.txt +++ b/pep-0396.txt @@ -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/) diff --git a/pep-0420.txt b/pep-0420.txt index 0863b2448..e7b0a99be 100644 --- a/pep-0420.txt +++ b/pep-0420.txt @@ -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