[Python-checkins] peps: Update PEP 426 based on distutils-sig feedback
nick.coghlan
python-checkins at python.org
Mon Feb 4 13:59:27 CET 2013
http://hg.python.org/peps/rev/7f36cb23fb6d
changeset: 4714:7f36cb23fb6d
user: Nick Coghlan <ncoghlan at gmail.com>
date: Mon Feb 04 22:55:22 2013 +1000
summary:
Update PEP 426 based on distutils-sig feedback
- include an example of Python-Requires + environment markers
- allow a bare Extension field (and give an example use case)
- be explicit that projects that refuse to use compliant version
numbering must continue to use metadata v1.1
- add guidelines for sorting across metadata versions
- add guidelines for dependencies across metadata versions
- point out that the new sort order is more consistent with that
of pkg_resources
- mention the implicit test and doc features in the rationale
for supporting optional features in general
- consistently use sentence case for headings, instead of a mix
of sentence case and title case
- other typo fixes
files:
pep-0426.txt | 140 ++++++++++++++++++++++++++++----------
1 files changed, 101 insertions(+), 39 deletions(-)
diff --git a/pep-0426.txt b/pep-0426.txt
--- a/pep-0426.txt
+++ b/pep-0426.txt
@@ -32,7 +32,7 @@
issues with the previous iteration of the standard version numbering scheme.
-Metadata Files
+Metadata files
==============
The syntax defined in this PEP is for use with Python distribution
@@ -64,7 +64,7 @@
the Metadata specification do not specify an encoding.
-Metadata Header Fields
+Metadata header fields
=======================
This section specifies the names and semantics of each of the
@@ -101,7 +101,7 @@
Version
-------
-A string containing the distribution's version number. See `Version Scheme`_
+A string containing the distribution's version number. See `Version scheme`_
below.
Example::
@@ -300,7 +300,7 @@
projects to depend only on having at least one of them installed.
A version declaration may be supplied and must follow the rules described
-in `Version Scheme`_. The distribution's version number will be implied
+in `Version scheme`_. The distribution's version number will be implied
if none is specified.
Examples::
@@ -336,7 +336,7 @@
project provides a substitute or replacement.
A version declaration may be supplied and must follow the rules described
-in `Version Specifiers`_.
+in `Version specifiers`_.
Possible uses for this field include handling project name changes and
project mergers.
@@ -365,7 +365,7 @@
as accessed with ``import x``.
Version declarations must follow the rules described in
-`Version Specifiers`_
+`Version specifiers`_
Distributions may also depend on optional features of other distributions.
See `Optional Features`_ for details.
@@ -398,9 +398,9 @@
Setup-Requires-Dist: custom_setup_command
-Dependencies mentioned in ``Setup-Requires-Dist`` may be installed exclusively
-for setup and are not guaranteed to be available at run time. If a
-dependency is needed during distribution creation or installation
+Dependencies mentioned in ``Setup-Requires-Dist`` may be installed
+exclusively for setup and are not guaranteed to be available at run time.
+If a dependency is needed during distribution creation or installation
*and* at run time, it should be listed under both ``Requires-Dist`` and
``Setup-Requires-Dist``.
@@ -411,19 +411,28 @@
This field specifies the Python version(s) that the distribution is
guaranteed to be compatible with.
-If specified multiple times, the Python version must satisfy all such
-constraints to be considered compatible (this is most useful in combination
-with appropriate `Environment markers`_)
-
-Version numbers must be in the format specified in `Version Specifiers`_.
+Version declarations must be in the format specified in
+`Version specifiers`_.
Examples::
- Requires-Python: 2.5
- Requires-Python: >2.1
+ Requires-Python: 3.2
+ Requires-Python: >3.1
Requires-Python: >=2.3.4
Requires-Python: >=2.5,<2.7
+If specified multiple times, the Python version must satisfy all such
+constraints to be considered compatible. This is most useful in combination
+with appropriate `Environment markers`_.
+
+For example, if a feature was initially introduced to Python as a
+Unix-specific addition, and then Windows support was added in the
+subsequent release, this could be indicated with the following pair
+of entries::
+
+ Requires-Python: >= 3.1
+ Requires-Python: >= 3.2; sys.platform == 'win32'
+
Requires-External (multiple use)
--------------------------------
@@ -439,7 +448,7 @@
Because they refer to non-Python software releases, version numbers
for this field are **not** required to conform to the format
-described in `Version Scheme`_: they should correspond to the
+described in `Version scheme`_: they should correspond to the
version scheme used by the external dependency.
Notice that there is no particular rule on the strings to be used.
@@ -504,12 +513,15 @@
Values in extension fields must still respect the general formatting
requirements for metadata headers.
-An ``Extension: Name`` entry with no corresponding extension fields is an
-error, as is an extension field with no corresponding ``Extension: Name``
-entry.
+A bare ``Extension: Name`` entry with no corresponding extension fields is
+permitted. It may, for example, indicate the expected presence of an
+additional metadata file rather than the presence of extension fields.
+An extension field with no corresponding ``Extension: Name`` entry is an
+error.
-Describing the Distribution
+
+Describing the distribution
===========================
The distribution metadata should include a longer description of the
@@ -534,20 +546,20 @@
authors should be conservative in the markup they use.
-Version Scheme
+Version scheme
==============
Version numbers must comply with the following scheme::
N.N[.N]+[{a|b|c|rc}N][.postN][.devN]
-Parser implementations should be aware that versions of the Metadata
-specification prior to v1.2 (PEP 345) do not specify a standard version
-numbering scheme. For metadata v1.2, it is recommended that implementations
-use the sorting scheme defined below rather than the one defined in PEP 386.
+Version numbers which do not comply with this scheme are an error. Projects
+which wish to use non-compliant version numbers must restrict themselves
+to metadata v1.1 (PEP 314) or earlier, as those versions do not mandate
+a particular versioning scheme.
-Suffixes and Ordering
+Suffixes and ordering
---------------------
The following suffixes are the only ones allowed at the given level of the
@@ -578,7 +590,7 @@
within the same numeric version.
-Example Version Order
+Example version order
---------------------
::
@@ -599,7 +611,30 @@
1.1.dev1
-Version Specifiers
+Ordering across different metadata versions
+-------------------------------------------
+
+After making a release with a given metadata version, it is assumed that
+projects will not revert to an older metadata version.
+
+Accordingly, and to allow projects with non-compliant version schemes
+to more easily migrate to the version scheme defined in this PEP,
+releases should be sorted by their declared metadata version *before*
+being sorted by the distribution version.
+
+Software that processes distribution metadata should account for the fact
+that metadata v1.0 (PEP 241) and metadata v1.1 (PEP 314) do not
+specify a standard version numbering or sorting scheme. This PEP does
+not mandate any particular approach to handling such versions, but
+acknowledges that the de facto standard for sorting such versions is
+the scheme used by the ``pkg_resources`` component of ``setuptools``.
+
+For metadata v1.2 (PEP 345), the recommended sort order is defined in
+PEP 386 (It is expected that projects where the defined PEP 386 sort
+order is incorrect will skip straight from metadata v1.1 to metadata v1.3).
+
+
+Version specifiers
==================
A version specifier consists of a series of version clauses, separated by
@@ -609,7 +644,7 @@
0.9, >= 1.0, != 1.3.4, < 2.0
Each version number must be in the standard format described in
-`Version Scheme`_.
+`Version scheme`_.
Comparison operators must be one of ``<``, ``>``, ``<=``, ``>=``, ``==``
and ``!=``.
@@ -658,7 +693,7 @@
to that version with the clause ``2.5.0``, while the clause ``2.5`` refers
to that entire series. Projects which omit the ".0" suffix for the first
release of a series, by using a version string like ``2.5`` rather than
-``2.5.0``, will need to use an explicit clause like ``2.5, < 2.5.1`` to
+``2.5.0``, will need to use an explicit clause like ``>= 2.5, < 2.5.1`` to
refer specifically to that initial release.
Some Examples:
@@ -687,6 +722,23 @@
pre-releases like 3.4a1.
+Depending on distributions that use non-compliant version schemes
+-----------------------------------------------------------------
+
+A distribution using this version of the metadata standard may need to depend
+on another distribution using an earlier version of the metadata standard
+and a non-compliant versioning scheme.
+
+The normal ``Requires-Dist`` and ``Setup-Requires-Dist`` fields can be used
+for such dependencies, so long as the dependency itself can be expressed
+using a compliant version specifier.
+
+For more exotic dependencies, a metadata extension would be needed in order
+to express the dependencies accurately while still obeying the restrictions
+on standard version specifiers. The ``Requires-External`` field may also
+be used, but would not be as amenable to automatic processing.
+
+
Environment markers
===================
@@ -775,7 +827,7 @@
permitted, but not required.
-Updating the Metadata Specification
+Updating the metadata specification
===================================
The metadata specification may be updated with clarifications without
@@ -786,7 +838,7 @@
defined in a new PEP.
-Summary of Differences From \PEP 345
+Summary of differences from \PEP 345
====================================
* Metadata-Version is now 1.3
@@ -804,6 +856,8 @@
* Changed interpretation of version specifiers
+* Explicit handling of ordering and dependencies across metadata versions
+
* Support for packaging, build and installation dependencies
* the new ``Setup-Requires-Dist`` field
@@ -858,7 +912,14 @@
of alpha releases like ``X.Ya1``. This is a far more logical sort order, as
projects already using both development releases and alphas/betas/release
candidates do not want their developmental releases sorted in
-between their release candidates and their full releases.
+between their release candidates and their full releases. There is no
+rationale for using ``dev`` releases in that position rather than
+merely creating additional release candidates.
+
+The updated sort order also means the sorting of ``dev`` versions is now
+consistent between the metadata standard and the pre-existing behaviour
+of ``pkg_resources`` (and hence the behaviour of current installation
+tools).
Making this change should make it easier for affected existing projects to
migrate to the latest version of the metadata standard.
@@ -910,9 +971,10 @@
The ``Requires-Dist`` and ``Setup-Requires-Dist`` fields then allow
distributions to require optional features of other distributions.
-One key motivation for this feature is to allow distributions to
-explicitly declare the dependencies needed to run their automatic
-tests, or build their documentation, without demanding those
+The ``test`` and ``doc`` features are implicitly defined for all
+distributions, as one key motivation for this feature is to encourage
+distributions to explicitly declare the dependencies needed to run
+their automatic tests, or build their documentation, without demanding those
dependencies be present in order to merely install or use the software.
@@ -925,7 +987,7 @@
distribution tools that do not support a particular extension.
It also works well in combination with the new ``Setup-Requires-Dist`` field
-to allow a distribution to depend on tools which *do* now how to handle
+to allow a distribution to depend on tools which *do* know how to handle
the chosen extension, and the new optional features mechanism, allowing
support for particular extensions to be provided as optional features.
@@ -968,7 +1030,7 @@
Version 1.1 is specified in PEP 314.
Version 1.2 is specified in PEP 345.
-The initial attempt at a standardised Version Scheme, along with the
+The initial attempt at a standardised version scheme, along with the
justifications for needing such a standard can be found in PEP 386.
.. [1] reStructuredText markup:
--
Repository URL: http://hg.python.org/peps
More information about the Python-checkins
mailing list