[Python-checkins] peps: Redraft PEP 426 (metadata 1.3)
nick.coghlan
python-checkins at python.org
Sun Feb 3 12:11:33 CET 2013
http://hg.python.org/peps/rev/8e61ec97109a
changeset: 4710:8e61ec97109a
user: Nick Coghlan <ncoghlan at gmail.com>
date: Sun Feb 03 21:11:16 2013 +1000
summary:
Redraft PEP 426 (metadata 1.3)
- saner version ordering and filtering
- explicit rationale for all major changes
- clarification of a few existing fields
files:
pep-0426.txt | 601 ++++++++++++++++++++++++++++----------
1 files changed, 446 insertions(+), 155 deletions(-)
diff --git a/pep-0426.txt b/pep-0426.txt
--- a/pep-0426.txt
+++ b/pep-0426.txt
@@ -2,8 +2,9 @@
Title: Metadata for Python Software Packages 1.3
Version: $Revision$
Last-Modified: $Date$
-Author: Daniel Holth <dholth at fastmail.fm>
-BDFL-Delegate: Nick Coghlan <ncoghlan at gmail.com>
+Author: Daniel Holth <dholth at fastmail.fm>,
+ Donald Stufft <donald at stufft.io>,
+ Nick Coghlan <ncoghlan at gmail.com>
Discussions-To: Distutils SIG
Status: Draft
Type: Standards Track
@@ -25,9 +26,11 @@
Version 1.3 of the metadata format adds fields designed to make
third-party packaging of Python Software easier and defines a formal
-extension mechanism. This version also adds the `extra` variable to the
+extension mechanism. It also adds the `extra` variable to the
`environment markers` specification and allows the description to be
-placed into a payload section.
+placed into a payload section. Finally, this version addresses several
+issues with the previous iteration of the standard version numbering scheme.
+
Metadata Files
==============
@@ -51,6 +54,7 @@
Other tools involved in Python distribution may also use this format.
+
Encoding
========
@@ -58,6 +62,7 @@
ASCII. Parser implementations should be aware that older versions of
the Metadata specification do not specify an encoding.
+
Fields
======
@@ -70,8 +75,9 @@
"Summary" must appear exactly once. The fields may appear in any order
within the header section of the file.
+
Metadata-Version
-::::::::::::::::
+----------------
Version of the file format; "1.3" is the only legal value.
@@ -81,7 +87,7 @@
Name
-::::
+----
The name of the distribution.
@@ -91,9 +97,10 @@
Version
-:::::::
+-------
-A string containing the distribution's version number.
+A string containing the distribution's version number. See `Version Scheme`_
+below.
Example::
@@ -101,7 +108,7 @@
Summary
-:::::::
+-------
A one-line summary of what the distribution does.
@@ -111,11 +118,13 @@
Platform (multiple use)
-:::::::::::::::::::::::
+-----------------------
A Platform specification describing an operating system supported by
the distribution which is not listed in the "Operating System" Trove classifiers.
-See "Classifier" below.
+See `Classifier`__ below.
+
+__ `Classifier (multiple use)`_
Examples::
@@ -124,7 +133,7 @@
Supported-Platform (multiple use)
-:::::::::::::::::::::::::::::::::
+---------------------------------
Binary distributions containing a metadata file will use the
Supported-Platform field in their metadata to specify the OS and
@@ -138,7 +147,7 @@
Description (optional, deprecated)
-::::::::::::::::::::::::::::::::::
+----------------------------------
A longer description of the distribution that can run to several
paragraphs. Software that deals with metadata should not assume
@@ -154,16 +163,16 @@
indicates the end of the headers section, any line separators in the
description must be suffixed by whitespace to indicate continuation.
-Since Metadata 1.3 the recommended place for the description is in the
-payload section of the document, after the last header. The description
+Starting with Metadata 1.3, the recommended place for the description is in
+the payload section of the document, after the last header. The description
does not need to be reformatted when it is included in the payload.
Keywords (optional)
-:::::::::::::::::::
+-------------------
-A list of additional keywords to be used to assist searching
-for the distribution in a larger catalog.
+A list of additional whitespace separated keywords to be used to assist
+searching for the distribution in a larger catalog.
Example::
@@ -171,7 +180,7 @@
Home-page (optional)
-::::::::::::::::::::
+--------------------
A string containing the URL for the distribution's home page.
@@ -181,7 +190,7 @@
Download-URL (optional)
-:::::::::::::::::::::::
+-----------------------
A string containing the URL from which this version of the distribution
can be downloaded. (This means that the URL can't be something like
@@ -189,7 +198,7 @@
Author (optional)
-:::::::::::::::::
+-----------------
A string containing the author's name at a minimum; additional
contact information may be provided.
@@ -201,7 +210,7 @@
Author-email (optional)
-:::::::::::::::::::::::
+-----------------------
A string containing the author's e-mail address. It contains a name
and e-mail address in the RFC 5322 recommended ``Address Specification``
@@ -213,7 +222,7 @@
Maintainer (optional)
-:::::::::::::::::::::
+---------------------
A string containing the maintainer's name at a minimum; additional
contact information may be provided.
@@ -229,7 +238,7 @@
Maintainer-email (optional)
-:::::::::::::::::::::::::::
+---------------------------
A string containing the maintainer's e-mail address. It has the same
format as ``Author-email``.
@@ -244,7 +253,7 @@
License (optional)
-::::::::::::::::::
+------------------
Text indicating the license covering the distribution where the license
is not a selection from the "License" Trove classifiers. See
@@ -265,7 +274,7 @@
Classifier (multiple use)
-:::::::::::::::::::::::::
+-------------------------
Each entry is a string giving a single classification value
for the distribution. Classifiers are described in PEP 301 [2].
@@ -277,7 +286,7 @@
Requires-Dist (multiple use)
-::::::::::::::::::::::::::::
+----------------------------
Each entry contains a string naming some other distutils
project required by this distribution.
@@ -293,67 +302,88 @@
Version declarations must follow the rules described in
`Version Specifiers`_
+Distributions may also depend on optional features of other distributions.
+See `Optional Features`_ for details.
+
Examples::
Requires-Dist: pkginfo
Requires-Dist: PasteDeploy
Requires-Dist: zope.interface (>3.5.0)
+Dependencies mentioned in ``Requires-Dist`` may be installed exclusively
+at run time and are not guaranteed to be available when creating or
+installing a package. 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``.
+
Setup-Requires-Dist (multiple use)
-::::::::::::::::::::::::::::::::::
+----------------------------------
-Like Requires-Dist, but names dependencies needed while the
-distributions's distutils / packaging `setup.py` / `setup.cfg` is run.
-Commonly used to bring in extra compiler support or a package needed
-to generate a manifest from version control.
+Like ``Requires-Dist``, but names dependencies needed in order to build,
+package or install the distribution. Commonly used to bring in extra
+compiler support or a package needed to generate a manifest from
+version control.
+
+Distributions may also depend on optional features of other distributions.
+See `Optional Features`_ for details.
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.
+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``.
Provides-Dist (multiple use)
-::::::::::::::::::::::::::::
+----------------------------
Each entry contains a string naming a requirement that is satisfied by
-installing this distribution. This field *must* include the project
-identified in the ``Name`` field, optionally followed by the version:
-Name (Version).
+installing this distribution. These strings must be of the form
+``Name`` or ``Name (Version)``, following the formats of the corresponding
+field definitions.
+
+For ease of metadata consumption, distributions are required to explicitly
+include a ``Provides-Dist`` entry for their own name and version. This also
+allows developers of a project to discourage users explicitly depending on
+the project (by deliberately omitting this entry).
A distribution may provide additional names, e.g. to indicate that
multiple projects have been merged into and replaced by a single
distribution or to indicate that this project is a substitute for another.
-For instance distribute (a fork of setuptools) could ``Provides-Dist``
-setuptools to prevent the conflicting package from being downloaded and
-installed when distribute is already installed. A distribution that has
-been merged with another might ``Provides-Dist`` the obsolete name(s)
-to satisfy any projects that require the obsolete distribution's name.
+For instance, distribute (a fork of setuptools) can include a
+``Provides-Dist: setuptools`` entry to prevent the conflicting
+package from being downloaded and installed when distribute is already
+installed. A distribution that has been merged with another might
+``Provides-Dist`` the obsolete name(s) to satisfy any projects that
+require the obsolete distribution's name.
A distribution may also provide a "virtual" project name, which does
not correspond to any separately-distributed project: such a name
might be used to indicate an abstract capability which could be supplied
by one of multiple projects. E.g., multiple projects might supply
RDBMS bindings for use by a given ORM: each project might declare
-that it provides ``ORM-bindings``, allowing other projects to depend
-only on having at most one of them installed.
+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 Specifiers`_. The distribution's version number will be implied
+in `Version Scheme`_. The distribution's version number will be implied
if none is specified.
Examples::
- Provides-Dist: OtherProject
+ Provides-Dist: ThisProject
Provides-Dist: AnotherProject (3.4)
Provides-Dist: virtual_package
Obsoleted-By (optional)
-:::::::::::::::::::::::
+-----------------------
Indicates that this project is no longer being developed. The named
project provides a substitute or replacement.
@@ -361,22 +391,28 @@
A version declaration may be supplied and must follow the rules described
in `Version Specifiers`_.
-The most common use of this field will be in case a project name changes.
+Possible uses for this field include handling project name changes and
+project mergers.
Examples::
Name: BadName
Obsoleted-By: AcceptableName
-
- Obsoleted-By: AcceptableName (>=4.0.0)
+ Name: SeparateProject
+ Obsoleted-By: MergedProject (>=4.0.0)
-Requires-Python (optional)
-::::::::::::::::::::::::::
+
+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`_.
Examples::
@@ -388,7 +424,7 @@
Requires-External (multiple use)
-::::::::::::::::::::::::::::::::
+--------------------------------
Each entry contains a string describing some dependency in the
system that the distribution is to be used. This field is intended to
@@ -401,7 +437,7 @@
Because they refer to non-Python software releases, version numbers
for this field are **not** required to conform to the format
-specified in PEP 386: 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.
@@ -413,26 +449,28 @@
Project-URL (multiple use)
-::::::::::::::::::::::::::
+--------------------------
A string containing a label and a browsable URL for the project, separated
by the last occurrence of comma and space ", ".
+The label consists of any permitted header text, including commas.
+
Example::
Bug, Issue Tracker, http://bitbucket.org/tarek/distribute/issues/
-The label is a free text.
-
Provides-Extra (multiple use)
-:::::::::::::::::::::::::::::
+-----------------------------
A string containing the name of an optional feature. Must be printable
ASCII, not containing whitespace, comma (,), or square brackets [].
May be used to make a dependency conditional on whether the optional
feature has been requested.
+See `Optional Features`_ for details on the use of this field.
+
Example::
Name: beaglevote
@@ -441,125 +479,189 @@
Requires-Dist: nose; extra == 'test'
Requires-Dist: sphinx; extra == 'doc'
-A second distribution requires an optional dependency by placing it
-inside square brackets and can request multiple features by separating
-them with a comma (,).
-
-The full set of requirements is the union of the `Requires-Dist` sets
-evaluated with `extra` set to `None` and then to the name of each
-requested feature.
-
-Example::
-
- Requires-Dist: beaglevote[pdf]
- -> requires beaglevote, reportlab
-
- Requires-Dist: beaglevote[test, doc]
- -> requires beaglevote, sphinx, nose
-
-Two feature names `test` and `doc` are reserved to mark dependencies that
-are needed for running automated tests and generating documentation,
-respectively.
-
-It is legal to specify `Provides-Extra` without referencing it in any
-`Requires-Dist`. It is an error to request a feature name that has
-not been declared with `Provides-Extra`.
-
Extension (multiple use)
-::::::::::::::::::::::::
+------------------------
-An ASCII string, not containing whitespace or the / character, that
-indicates the presence of extended metadata. Additional tags defined by
-an `Extension: Chili` must be of the form `Chili/Name`::
+An ASCII string, not containing whitespace or the ``/`` character, that
+indicates the presence of extended metadata. The additional fields
+defined by the extension are then prefixed with the name of the extension
+and the ``/`` character.
+
+For example::
Extension: Chili
Chili/Type: Poblano
Chili/Heat: Mild
-An implementation might iterate over all the declared `Extension:`
-fields to invoke the processors for those extensions. As the order of
-the fields is not used, the `Extension: Chili` field may appear before
-or after its declared tags `Chili/Type:` etc.
+To avoid name conflicts, it is recommended that distribution names be used
+to identify metadata extensions. This practice will also make it easier to
+find authoritative documentation for metadata extensions.
+As the order of the metadata headers is not constrained, the
+``Extension: Chili`` field may appear before or after the corresponding
+extension fields ``Chili/Type:`` etc.
-Version-Scheme (optional)
-:::::::::::::::::::::::::
+Values in extension fields must still respect the general formatting
+requirements for metadata headers.
-A string specifying the sorting method for this distribution's version
-numbers. Although straightforward version numbers tend to sort the same in
-each scheme, there is disagreement about how to sort patch releases and
-versions having alphanumeric components such as "1.0.0rc2" and "1.0.0pre3"::
+An ``Extension: Name`` entry with no corresponding extension fields is an
+error, as is an extension field with no corresponding ``Extension: Name``
+entry.
- Version-Scheme: pkg_resources
- Version-Scheme: pep386
-The two initially supported schemes are:
+Version Scheme
+==============
-* pkg_resources: sort versions compatibly with setuptools' pkg_resources module
-* pep386: sort according to the rules in pep386
+Version numbers must comply with the following scheme::
-The default is pep386.
+ 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.
+
+
+Suffixes and Ordering
+---------------------
+
+The following suffixes are the only ones allowed at the given level of the
+version hierarchy and they are ordered as listed.
+
+Within a numeric release (``1.0``, ``2.7.3``)::
+
+ .devN, aN, bN, cN, rcN, <no suffix>, .postN
+
+Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate
+(``1.0c1``, ``1.0rc1``)::
+
+ .devN, <no suffix>, .postN
+
+Within a post release (``1.0.post1``)::
+
+ devN, <no suffix>
+
+Note that ``devN`` and ``postN`` must always be preceded by a dot, even
+when used immediately following a numeric version (e.g. `1.0.dev456`,
+`1.0.post1`).
+
+Within a given suffix, ordering is by the value of the numeric component.
+
+Note that `rc` will always sort after `c` (regardless of the numeric
+component) although they are semantically equivalent. It is suggested
+that within a particular project you do not mix `c` and `rc`, especially
+within the same numeric version.
+
+
+Example Version Order
+---------------------
+
+ 1.0.dev456
+ 1.0a1
+ 1.0a2.dev456
+ 1.0a12.dev456
+ 1.0a12
+ 1.0b1.dev456
+ 1.0b2
+ 1.0b2.post345
+ 1.0c1.dev456
+ 1.0c1
+ 1.0
+ 1.0.post456.dev34
+ 1.0.post456
+ 1.1.dev123
+ ...
Version Specifiers
==================
-Version specifiers are a series of conditional operators and
-version numbers, separated by commas. Conditional operators
-must be one of "<", ">", "<=", ">=", "==" and "!=".
+A version specifier consists of a series of version clauses, separated by
+commas. Each version clause consists of an optional comparison operator
+followed by a version number. For example::
-Any number of conditional operators can be specified, e.g.
-the string ">1.0, !=1.3.4, <2.0" is a legal version declaration.
-The comma (",") is equivalent to the **and** operator.
+ 0.9, >= 1.0, != 1.3.4, < 2.0
-Each version number should be in the format used by the referenced
-distribution.
+Each version number must be in the standard format described in
+`Version Scheme`_.
-When a version is provided, it always includes all versions that
-starts with the same value. For example the "2.5" version of Python
-will include versions like "2.5.2" or "2.5.3". Pre and post releases
-in that case are excluded. So in our example, versions like "2.5a1" are
-not included when "2.5" is used. If the first version of the range is
-required, it has to be explicitly given. In our example, it will be
-"2.5.0".
+Comparison operators must be one of ``<``, ``>``, ``<=``, ``>=``, ``==``
+and ``!=``.
-Notice that some projects might omit the ".0" prefix for the first release
-of the "2.5.x" series:
+When no comparison operator is provided, it is equivalent to using the
+following pair of version clauses::
-- 2.5
-- 2.5.1
-- 2.5.2
-- etc.
+ >= V, < V+1
-In that case, "2.5.0" will have to be explicitly used to avoid any confusion
-between the "2.5" notation that represents the full range. It is a recommended
-practice to use schemes of the same length for a series to completely avoid
-this problem.
+where ``V+1`` is the "next version" after ``V``, as determined by
+incrementing the last numeric component in ``V`` (for example, if
+``V == 1.0a3``, then ``V+1 == 1.0a4``, while if ``V == 1.0``, then
+``V+1 == 1.1``).
+
+The comma (",") is equivalent to a logical **and** operator.
+
+Whitespace between a conditional operator and the following version number
+is optional, as is the whitespace around the commas.
+
+Pre-releases of any kind (indicated by the presence of ``dev``, ``a``,
+``b``, ``c`` or ``rc`` in the version number) are implicitly excluded
+from all version specifiers, *unless* a pre-release version is explicitly
+mentioned in one of the clauses. For example, this specifier implicitly
+excludes all pre-releases of later versions::
+
+ >= 1.0
+
+While these specifiers would include them:
+
+ >= 1.0a1
+ >= 1.0c1
+ >= 1.0, != 1.0b2
+ >= 1.0, < 2.0.dev123
+
+Dependency resolution tools should use the above rules by default, but may
+also allow users to request the following alternative behaviour:
+
+* accept already installed pre-releases for all version specifiers
+* retrieve and install pre-releases for all version specifiers
+
+Post releases and purely numeric releases receive no special treatment -
+they are always included unless explicitly excluded.
+
+Given the above rules, projects which include the ``.0`` suffix for the
+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
+refer specifically to that initial release.
Some Examples:
- ``Requires-Dist: zope.interface (3.1)``: any version that starts with 3.1,
- excluding post or pre-releases.
+ excluding pre-releases.
- ``Requires-Dist: zope.interface (==3.1)``: equivalent to ``Requires-Dist:
zope.interface (3.1)``.
- ``Requires-Dist: zope.interface (3.1.0)``: any version that starts with
- 3.1.0, excluding post or pre-releases. Since that particular project doesn't
+ 3.1.0, excluding pre-releases. Since that particular project doesn't
use more than 3 digits, it also means "only the 3.1.0 release".
- ``Requires-Python: 3``: Any Python 3 version, no matter wich one, excluding
- post or pre-releases.
+ pre-releases.
- ``Requires-Python: >=2.6,<3``: Any version of Python 2.6 or 2.7, including
- post releases of 2.6, pre and post releases of 2.7. It excludes pre releases
- of Python 3.
+ post releases (if they were used for Python). It excludes pre releases of
+ Python 3.
- ``Requires-Python: 2.6.2``: Equivalent to ">=2.6.2,<2.6.3". So this includes
only Python 2.6.2. Of course, if Python was numbered with 4 digits, it would
- have include all versions of the 2.6.2 series.
-- ``Requires-Python: 2.5.0``: Equivalent to ">=2.5.0,<2.5.1".
+ include all versions of the 2.6.2 series, excluding pre-releases.
+- ``Requires-Python: 2.5``: Equivalent to ">=2.5,<2.6".
- ``Requires-Dist: zope.interface (3.1,!=3.1.3)``: any version that starts with
- 3.1, excluding post or pre-releases of 3.1 *and* excluding any version that
+ 3.1, excluding pre-releases of 3.1 *and* excluding any version that
starts with "3.1.3". For this particular project, this means: "any version
of the 3.1 series but not 3.1.3". This is equivalent to:
">=3.1,!=3.1.3,<3.2".
+- ``Requires-Python: >=3.3a1``: Any version of Python 3.3+, including
+ pre-releases like 3.4a1.
+
Environment markers
===================
@@ -577,14 +679,14 @@
The micro-language behind this is a simple subset of Python: it compares
only strings, with the ``==`` and ``in`` operators (and their opposites),
-and with the ability to combine expressions. Parenthesis are supported
+and with the ability to combine expressions. Parentheses are supported
for grouping.
The pseudo-grammar is ::
EXPR [in|==|!=|not in] EXPR [or|and] ...
-where ``EXPR`` belongs to any of those:
+where ``EXPR`` belongs to any of these:
- python_version = '%s.%s' % (sys.version_info[0], sys.version_info[1])
- python_full_version = sys.version.split()[0]
@@ -608,36 +710,221 @@
- Provides-Dist
- Classifier
-(The `extra` variable is only meaningful for Requires-Dist.)
+
+Optional features
+=================
+
+Distributions may use the ``Provides-Extra`` field to declare additional
+features that they provide. Environment markers may then be used to indicate
+that particular dependencies (as specified in ``Requires-Dist`` or
+``Setup-Requires-Dist``) are needed only when a particular optional
+feature has been requested.
+
+Other distributions then require an optional feature by placing it
+inside square brackets after the distribution name when declaring the
+dependency. Multiple features can be requisted by separating them with a
+comma (,).
+
+The full set of dependency requirements is then the union of the
+sets created first evaluating the `Requires-Dist` (or
+`Setup-Requires-Dist`) fields with `extra` set to `None` and then to
+the name of each requested feature.
+
+Example::
+
+ Requires-Dist: beaglevote[pdf]
+ -> requires beaglevote, reportlab at run time
+
+ Setup-Requires-Dist: beaglevote[test, doc]
+ -> requires beaglevote, sphinx, nose at setup time
+
+It is legal to specify `Provides-Extra` without referencing it in any
+`Requires-Dist`. It is an error to request a feature name that has
+not been declared with `Provides-Extra`.
+
+The following feature names are implicitly defined for all distributions:
+
+- `test`: dependencies that are needed in order to run automated tests
+- `doc`: dependencies that are needed in order to generate documentation
+
+Listing these implicit features explicitly in a ``Provides-Extra`` field is
+permitted, but not required.
+
+
+Updating the Metadata Specification
+===================================
+
+The metadata specification may be updated with clarifications without
+requiring a new PEP or a change to the metadata version.
+
+Adding new features (other than through the extension mechanism), or
+changing the meaning of existing fields requires a new metadata version
+defined in a new PEP.
+
Summary of Differences From PEP 345
===================================
-* Metadata-Version is now 1.3.
+* Metadata-Version is now 1.3
-* Values are now expected to be UTF-8.
+* Most fields are now optional
-* A payload (containing the description) may appear after the headers.
+* Explicit permission for in-place clarifications without releasing a new
+ version of the specification
-* Added `extra` to environment markers.
+* Values are now expected to be UTF-8
-* Most fields are now optional.
+* Changed the version scheme (eliminating the dependency on PEP 386)
-* Removed `Obsoletes-Dist`
+* Changed interpretation of version specifiers
-* Changed fields:
+* Support for packaging, build and installation dependencies
- - Description
- - Project-URL
- - Requires-Dist
+ * the new ``Setup-Requires-Dist`` field
-* Added fields:
+* Optional feature mechanism
- - Extension
- - Provides-Extra
- - Setup-Requires-Dist
- - Obsoleted-By
- - Version-Scheme
+ * the new ``Provides-Extra`` field
+ * ``extra`` expression defined for environment markers.
+ * optional feature support in ``Requires-Dist`` and
+ ``Setup-Requires-Dist``
+
+* Metadata extension mechanism
+
+ * the new ``Extension`` field and extension specific fields
+
+* Updated obsolescence mechanism
+
+ * the new ``Obsoleted-By`` field
+ * the ``Obsoletes-Dist`` field has been removed
+
+* Simpler description format
+
+ * the ``Description`` field is now deprecated
+ * A payload (containing the description) may appear after the headers.
+
+* Other changed fields:
+
+ - ``Requires-Python`` (explicitly flagged as multiple use)
+ - ``Project-URL`` (commas permitted in labels)
+
+* Clarified fields:
+
+ - ``Provides-Dist``
+ - ``Keywords``
+
+The rationale for major changes is given in the following sections.
+
+Standard encoding and other format clarifications
+-------------------------------------------------
+
+Several aspects of the file format, including the expected file encoding,
+were underspecified in previous versions of the metadata standard. To
+simplify the process of developing interoperable tools, these details are
+now explicitly specified.
+
+
+Changing the version scheme
+---------------------------
+
+The key change in the version scheme in this PEP relative to that in
+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.
+
+Making this change should make it easier for affected existing projects to
+migrate to the latest version of the metadata standard.
+
+Furthermore, as the version scheme in use is dependent on the metadata
+version, it was deemed simpler to merge the scheme definition directly into
+this PEP rather than continuing to maintain it as a separate PEP. This will
+also allow all of the distutils-specific elements of PEP 386 to finally be
+formally rejected.
+
+
+Changing the interpretation of version specifiers
+-------------------------------------------------
+
+The previous interpretation of version specifiers made it very easy to
+accidentally download a pre-release version of a dependency. This in
+turn made it difficult for developers to publish pre-release versions
+of software to the Python Package Index, as such an action would lead
+to users inadvertently downloaded pre-release software.
+
+The previous interpretation also excluded post-releases from some version
+specifiers for no adequately justified reason.
+
+The updated interpretation is intended to make it difficult to accidentally
+accept a pre-release version as satisfying a dependency, while allowing
+pre-release versions to be explicitly requested when needed.
+
+
+Packaging, build and installation dependencies
+----------------------------------------------
+
+The new ``Setup-Requires-Dist`` field allows a distribution to indicate when
+a dependency is needed to package, build or install the distribution, rather
+than being needed to run the software after installation.
+
+This should allow distribution tools to effectively support a wider range of
+distribution requirements.
+
+
+Support for optional features of distributions
+----------------------------------------------
+
+The new ``Provides-Extra`` field allows distributions to declare optional
+features, and to use environment markers to reduce their dependencies
+when those features are not requested. Environment markers may also be
+used to require a later version of Python when particular features are
+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
+dependencies be present in order to merely install or use the software.
+
+
+Support for metadata extensions
+-------------------------------
+
+The new ``Extension`` field effectively allows sections of the metadata
+namespace to be delegated to other distributions, while preserving a
+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
+the chosen extension, and the new optional features mechanism, allowing
+support for particular extensions to be provided as optional features.
+
+
+Updated obsolescence mechanism
+------------------------------
+
+The marker to indicate when a project is obsolete and should be replaced
+has been moved to the obsolete project (the new ``Obsoleted-By`` field),
+replacing the previous marker on the replacement project (the removed
+``Obsoletes`` field).
+
+This should allow distribution tools to more easily warn users of
+obsolete projects and their suggested replacements.
+
+
+Simpler description format
+--------------------------
+
+Distribution descriptions are often quite long, sometimes including a
+short guide to using the module. Moving them into the file payload allows
+them to be formatted neatly as reStructuredText without needing to
+carefully avoid the introduction of a blank line that would terminate
+the header section.
+
References
==========
@@ -647,6 +934,9 @@
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
+justifications for needing such a standard can be found in PEP 386.
+
.. [1] reStructuredText markup:
http://docutils.sourceforge.net/
@@ -655,6 +945,7 @@
.. [2] PEP 301:
http://www.python.org/dev/peps/pep-0301/
+
Appendix
========
--
Repository URL: http://hg.python.org/peps
More information about the Python-checkins
mailing list