diff --git a/pep-0426.txt b/pep-0426.txt index f600cac3e..d939e7e80 100644 --- a/pep-0426.txt +++ b/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: