[Python-checkins] peps: improve the readability of one section

[barry.warsaw]

http://hg.python.org/peps/rev/5e088d558b88
changeset:   4351:5e088d558b88
user:        Barry Warsaw <barry at python.org>
date:        Thu May 03 14:30:48 2012 -0400
summary:
  improve the readability of one section

files:
  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
--- a/pep-0396.txt
+++ b/pep-0396.txt
@@ -102,15 +102,13 @@
    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 @@
 
 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 @@
 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 @@
 .. [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
--- a/pep-0420.txt
+++ b/pep-0420.txt
@@ -174,7 +174,7 @@
 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

-- 
Repository URL: http://hg.python.org/peps