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
This commit is contained in:
Nick Coghlan
parent
a9a4918339
commit
eadb70fc0d
140
pep-0426.txt
140
pep-0426.txt
|
|
@ -32,7 +32,7 @@ placed into a payload section. Finally, this version addresses several
|
|||
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 @@ ASCII. Parser implementations should be aware that older versions of
|
|||
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 @@ Example::
|
|||
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 @@ that it provides ``ExampleORM-somedb-bindings``, allowing other
|
|||
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 @@ Indicates that this project is no longer being developed. The named
|
|||
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 @@ Package Index`_; often the same as, but distinct from, the module names
|
|||
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 @@ Examples::
|
|||
|
||||
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 @@ Requires-Python (multiple use)
|
|||
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 @@ parentheses.
|
|||
|
||||
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 @@ extension fields ``Chili/Type:`` etc.
|
|||
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 @@ field as plain text without any special formatting. This means that
|
|||
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 @@ that within a particular project you do not mix `c` and `rc`, especially
|
|||
within the same numeric version.
|
||||
|
||||
|
||||
Example Version Order
|
||||
Example version order
|
||||
---------------------
|
||||
|
||||
::
|
||||
|
|
@ -599,7 +611,30 @@ Example Version Order
|
|||
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 @@ followed by a version number. For example::
|
|||
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 @@ first release in a series, such as ``2.5.0``, can easily refer specifically
|
|||
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 @@ Some Examples:
|
|||
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 @@ Listing these implicit features explicitly in a ``Provides-Extra`` field is
|
|||
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 @@ changing the meaning of existing fields, requires a new metadata version
|
|||
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 @@ Summary of Differences From \PEP 345
|
|||
|
||||
* 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 @@ PEP 386 is to sort top level developmental releases like ``X.Y.devN`` ahead
|
|||
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 @@ requested.
|
|||
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 @@ standard overal format metadata format for easy of processing by
|
|||
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.0 is specified in PEP 241.
|
|||
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:
|
||||
|
|
|
|||
Loading…
Reference in New Issue