1694 lines
59 KiB
Plaintext
1694 lines
59 KiB
Plaintext
PEP: 426
|
||
Title: Metadata for Python Software Packages 2.0
|
||
Version: $Revision$
|
||
Last-Modified: $Date$
|
||
Author: Daniel Holth <dholth@fastmail.fm>,
|
||
Donald Stufft <donald@stufft.io>,
|
||
Nick Coghlan <ncoghlan@gmail.com>
|
||
BDFL-Delegate: Nick Coghlan <ncoghlan@gmail.com>
|
||
Discussions-To: Distutils SIG
|
||
Status: Draft
|
||
Type: Standards Track
|
||
Content-Type: text/x-rst
|
||
Created: 30 Aug 2012
|
||
Post-History: 14 Nov 2012, 5 Feb 2013, 7 Feb 2013, 9 Feb 2013
|
||
|
||
|
||
Abstract
|
||
========
|
||
|
||
This PEP describes a mechanism for adding metadata to Python distributions.
|
||
It includes specifics of the field names, and their semantics and
|
||
usage.
|
||
|
||
This document specifies version 2.0 of the metadata format.
|
||
Version 1.0 is specified in PEP 241.
|
||
Version 1.1 is specified in PEP 314.
|
||
Version 1.2 is specified in PEP 345.
|
||
|
||
Version 2.0 of the metadata format adds fields designed to make
|
||
third-party packaging of Python Software easier and defines a formal
|
||
extension mechanism. It also adds support for optional features of
|
||
distributions and allows the description to be placed into a payload
|
||
section. Finally, this version addresses several issues with the
|
||
previous iteration of the standard version identification scheme.
|
||
|
||
|
||
Metadata files
|
||
==============
|
||
|
||
The syntax defined in this PEP is for use with Python distribution
|
||
metadata files. The file format is a simple UTF-8 encoded Key: value
|
||
format with case-insensitive keys and no maximum line length, optionally
|
||
followed by a blank line and a payload containing a description of the
|
||
distribution.
|
||
|
||
This format is parseable by the ``email`` module with an appropriate
|
||
``email.policy.Policy()`` (see `Appendix A`_). When ``metadata`` is a
|
||
Unicode string, ```email.parser.Parser().parsestr(metadata)`` is a
|
||
serviceable parser.
|
||
|
||
There are three standard locations for these metadata files:
|
||
|
||
* the ``PKG-INFO`` file included in the base directory of Python
|
||
source distribution archives (as created by the distutils ``sdist``
|
||
command)
|
||
* the ``{distribution}-{version}.dist-info/METADATA`` file in a ``wheel``
|
||
binary distribution archive (as described in PEP 425, or a later version
|
||
of that specification)
|
||
* the ``{distribution}-{version}.dist-info/METADATA`` files in a local
|
||
Python installation database (as described in PEP 376, or a later version
|
||
of that specification)
|
||
|
||
Other tools involved in Python distribution may also use this format.
|
||
|
||
|
||
Encoding
|
||
========
|
||
|
||
Metadata 2.0 files are UTF-8 with the restriction that keys must be
|
||
ASCII. Parser implementations should be aware that older versions of
|
||
the Metadata specification do not specify an encoding.
|
||
|
||
|
||
Metadata header fields
|
||
=======================
|
||
|
||
This section specifies the names and semantics of each of the
|
||
supported fields in the metadata header.
|
||
|
||
In a single Metadata 2.0 file, fields marked with "(optional)" may occur
|
||
0 or 1 times. Fields marked with "(multiple use)" may be specified
|
||
0, 1 or more times. Only "Metadata-Version", "Name", "Version", and
|
||
"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; "2.0" is the only legal value.
|
||
|
||
Automated tools consuming metadata should warn if ``Metadata-Version`` is
|
||
greater than the highest version they support, and must fail if
|
||
``Metadata-Version`` has a greater major version than the highest
|
||
version they support.
|
||
|
||
For broader compatibility, automated tools may choose to produce
|
||
distribution metadata using the lowest metadata version that includes
|
||
all of the needed fields.
|
||
|
||
Example::
|
||
|
||
Metadata-Version: 2.0
|
||
|
||
|
||
Name
|
||
----
|
||
|
||
The name of the distribution.
|
||
|
||
Example::
|
||
|
||
Name: BeagleVote
|
||
|
||
|
||
Version
|
||
-------
|
||
|
||
The distribution's public version identifier. Public versions are designed
|
||
for consumption by automated tools and are strictly ordered according
|
||
to a defined scheme. See `Version scheme`_ below.
|
||
|
||
Example::
|
||
|
||
Version: 1.0a2
|
||
|
||
|
||
Summary
|
||
-------
|
||
|
||
A one-line summary of what the distribution does.
|
||
|
||
Example::
|
||
|
||
Summary: A module for collecting votes from beagles.
|
||
|
||
|
||
Private-Version (optional)
|
||
--------------------------
|
||
|
||
An arbitrary private version label. Private version labels are intended
|
||
for internal use by a project, and cannot be used in version specifiers.
|
||
See `Compatibility with other version schemes`_ below.
|
||
|
||
Examples::
|
||
|
||
Private-Version: 1.0.0-alpha.1
|
||
Private-Version: 1.3.7+build.11.e0f985a
|
||
Private-Version: v1.8.1.301.ga0df26f
|
||
Private-Version: 2013.02.17.dev123
|
||
|
||
|
||
Description (optional, deprecated)
|
||
----------------------------------
|
||
|
||
Starting with Metadata 2.0, 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.
|
||
|
||
See `Describing the Distribution`_ for more information on the expected
|
||
contents of this field.
|
||
|
||
Since a line separator immediately followed by another line separator
|
||
indicates the end of the headers section, any line separators in a
|
||
``Description`` header field must be suffixed by whitespace to
|
||
indicate continuation.
|
||
|
||
It is an error to provide both a ``Description`` header and a metadata
|
||
payload.
|
||
|
||
|
||
Keywords (optional)
|
||
-------------------
|
||
|
||
A list of additional whitespace separated keywords to be used to assist
|
||
searching for the distribution in a larger catalog.
|
||
|
||
Example::
|
||
|
||
Keywords: dog puppy voting election
|
||
|
||
|
||
Home-page (optional)
|
||
--------------------
|
||
|
||
A string containing the URL for the distribution's home page.
|
||
|
||
Example::
|
||
|
||
Home-page: http://www.example.com/~cschultz/bvote/
|
||
|
||
|
||
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
|
||
".../BeagleVote-latest.tgz", but instead must be ".../BeagleVote-0.45.tgz".)
|
||
|
||
|
||
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/
|
||
|
||
|
||
Author (optional)
|
||
-----------------
|
||
|
||
A string containing the author's name at a minimum; additional
|
||
contact information may be provided.
|
||
|
||
Example::
|
||
|
||
Author: C. Schultz, Universal Features Syndicate,
|
||
Los Angeles, CA <cschultz@peanuts.example.com>
|
||
|
||
|
||
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``
|
||
format.
|
||
|
||
Example::
|
||
|
||
Author-email: "C. Schultz" <cschultz@example.com>
|
||
|
||
|
||
Maintainer (optional)
|
||
---------------------
|
||
|
||
A string containing the maintainer's name at a minimum; additional
|
||
contact information may be provided.
|
||
|
||
Note that this field is intended for use when a project is being
|
||
maintained by someone other than the original author: it should be
|
||
omitted if it is identical to ``Author``.
|
||
|
||
Example::
|
||
|
||
Maintainer: C. Schultz, Universal Features Syndicate,
|
||
Los Angeles, CA <cschultz@peanuts.example.com>
|
||
|
||
|
||
Maintainer-email (optional)
|
||
---------------------------
|
||
|
||
A string containing the maintainer's e-mail address. It has the same
|
||
format as ``Author-email``.
|
||
|
||
Note that this field is intended for use when a project is being
|
||
maintained by someone other than the original author: it should be
|
||
omitted if it is identical to ``Author-email``.
|
||
|
||
Example::
|
||
|
||
Maintainer-email: "C. Schultz" <cschultz@example.com>
|
||
|
||
|
||
License (optional)
|
||
------------------
|
||
|
||
Text indicating the license covering the distribution where the license
|
||
is not a selection from the "License" Trove classifiers. See
|
||
"Classifier" below. This field may also be used to specify a
|
||
particular version of a license which is named via the ``Classifier``
|
||
field, or to indicate a variation or exception to such a license.
|
||
|
||
Examples::
|
||
|
||
License: This software may only be obtained by sending the
|
||
author a postcard, and then the user promises not
|
||
to redistribute it.
|
||
|
||
License: GPL version 3, excluding DRM provisions
|
||
|
||
The full text of the license would normally be included in a separate
|
||
file.
|
||
|
||
|
||
Classifier (multiple use)
|
||
-------------------------
|
||
|
||
Each entry is a string giving a single classification value
|
||
for the distribution. Classifiers are described in PEP 301 [2].
|
||
|
||
`Environment markers`_ may be used with this field.
|
||
|
||
Examples::
|
||
|
||
Classifier: Development Status :: 4 - Beta
|
||
Classifier: Environment :: Console (Text Based)
|
||
|
||
|
||
Provides-Dist (multiple use)
|
||
----------------------------
|
||
|
||
Each entry contains a string naming a requirement that is satisfied by
|
||
installing this distribution. These strings must be of the form
|
||
``Name`` or ``Name (Version)``, following the formats of the corresponding
|
||
field definitions.
|
||
|
||
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) 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 ``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 identifier will be implied
|
||
if none is specified.
|
||
|
||
`Environment markers`_ may be used with this field.
|
||
|
||
Examples::
|
||
|
||
Provides-Dist: AnotherProject (3.4)
|
||
Provides-Dist: virtual_package
|
||
|
||
|
||
Provides-Extra (multiple use)
|
||
-----------------------------
|
||
|
||
A string containing the name of an optional feature or "extra" that may
|
||
only be available when additional dependencies have been installed. Must
|
||
be printable ASCII, not containing whitespace, comma (,), or square
|
||
brackets [].
|
||
|
||
See `Optional Features`_ for details on the use of this field.
|
||
|
||
Example::
|
||
|
||
Name: beaglevote
|
||
Provides-Extra: pdf
|
||
Requires-Dist: reportlab; extra == 'pdf'
|
||
Requires-Dist: nose; extra == 'test'
|
||
Requires-Dist: sphinx; extra == 'doc'
|
||
|
||
|
||
Obsoleted-By (optional)
|
||
-----------------------
|
||
|
||
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`_.
|
||
|
||
Possible uses for this field include handling project name changes and
|
||
project mergers.
|
||
|
||
Examples::
|
||
|
||
Name: BadName
|
||
Obsoleted-By: AcceptableName
|
||
|
||
Name: SeparateProject
|
||
Obsoleted-By: MergedProject (>=4.0.0)
|
||
|
||
|
||
Requires-Dist (multiple use)
|
||
----------------------------
|
||
|
||
Each entry contains a string naming some other distutils
|
||
project required by this distribution.
|
||
|
||
The format of a requirement string is identical to that of a distribution
|
||
name (e.g., as found in the ``Name:`` field) optionally followed by a
|
||
version declaration within parentheses.
|
||
|
||
The distribution names should correspond to names as found on the `Python
|
||
Package Index`_; often the same as, but distinct from, the module names
|
||
as accessed with ``import x``.
|
||
|
||
`Environment markers`_ may be used with this field.
|
||
|
||
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 in order to build,
|
||
package or install the distribution -- in distutils, a dependency imported
|
||
by ``setup.py`` itself. Commonly used to bring in extra compiler support
|
||
or a package needed to generate a manifest from version control.
|
||
|
||
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
|
||
*and* at run time, it should be listed under both ``Requires-Dist`` and
|
||
``Setup-Requires-Dist``.
|
||
|
||
|
||
Requires-Python (multiple use)
|
||
------------------------------
|
||
|
||
This field specifies the Python version(s) that the distribution is
|
||
guaranteed to be compatible with.
|
||
|
||
`Environment markers`_ may be used with this field.
|
||
|
||
Version declarations must be in the format specified in
|
||
`Version specifiers`_.
|
||
|
||
Examples::
|
||
|
||
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)
|
||
--------------------------------
|
||
|
||
Each entry contains a string describing some dependency in the
|
||
system that the distribution is to be used. This field is intended to
|
||
serve as a hint to downstream project maintainers, and has no
|
||
semantics which are meaningful to the ``distutils`` distribution.
|
||
|
||
The format of a requirement string is a name of an external
|
||
dependency, optionally followed by a version declaration within
|
||
parentheses.
|
||
|
||
`Environment markers`_ may be used with this field.
|
||
|
||
Because they refer to non-Python software releases, version identifiers
|
||
for this field are **not** required to conform to the format
|
||
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.
|
||
|
||
Examples::
|
||
|
||
Requires-External: C
|
||
Requires-External: libpng (>=1.5)
|
||
|
||
|
||
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`__ above.
|
||
|
||
__ `Classifier (multiple use)`_
|
||
|
||
Examples::
|
||
|
||
Platform: ObscureUnix
|
||
Platform: RareDOS
|
||
|
||
|
||
Supported-Platform (multiple use)
|
||
---------------------------------
|
||
|
||
Binary distributions containing a metadata file will use the
|
||
Supported-Platform field in their metadata to specify the OS and
|
||
CPU for which the binary distribution was compiled. The semantics of
|
||
the Supported-Platform field are not specified in this PEP.
|
||
|
||
Example::
|
||
|
||
Supported-Platform: RedHat 7.2
|
||
Supported-Platform: i386-win32-2791
|
||
|
||
|
||
Extension (multiple use)
|
||
------------------------
|
||
|
||
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
|
||
|
||
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.
|
||
|
||
Values in extension fields must still respect the general formatting
|
||
requirements for metadata headers.
|
||
|
||
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
|
||
===========================
|
||
|
||
The distribution metadata should include a longer description of the
|
||
distribution that may run to several paragraphs. Software that deals
|
||
with metadata should not assume any maximum size for the description.
|
||
|
||
The recommended location for the description is in the metadata payload,
|
||
separated from the header fields by at least one completely blank line
|
||
(that is, two successive line separators with no other characters
|
||
between them, not even whitespace).
|
||
|
||
Alternatively, the description may be provided in the `Description`__
|
||
metadata header field. Providing both a ``Description`` field and a
|
||
payload is an error.
|
||
|
||
__ `Description (optional, deprecated)`_
|
||
|
||
The distribution description can be written using reStructuredText
|
||
markup [1]_. For programs that work with the metadata, supporting
|
||
markup is optional; programs may also display the contents of the
|
||
field as plain text without any special formatting. This means that
|
||
authors should be conservative in the markup they use.
|
||
|
||
|
||
Version scheme
|
||
==============
|
||
|
||
Public version identifiers must comply with the following scheme::
|
||
|
||
N[.N]+[{a|b|c|rc}N][.postN][.devN]
|
||
|
||
Version identifiers which do not comply with this scheme are an error.
|
||
|
||
Version identifiers must not include leading or trailing whitespace.
|
||
|
||
Any given version will be a "release", "pre-release", "post-release" or
|
||
"developmental release" as defined in the following sections.
|
||
|
||
.. note::
|
||
|
||
Some hard to read version identifiers are permitted by this scheme
|
||
in order to better accommodate the wide range of versioning practices
|
||
across existing public and private Python projects.
|
||
|
||
Accordingly, some of the versioning practices which are technically
|
||
permitted by the PEP are strongly discouraged for new projects. Where
|
||
this is the case, the relevant details are noted in the following
|
||
sections.
|
||
|
||
|
||
Releases
|
||
--------
|
||
|
||
A release number is a version identifier that consists solely of one or
|
||
more non-negative integer values, separated by dots::
|
||
|
||
N[.N]+
|
||
|
||
Releases within a project must be numbered in a consistently increasing
|
||
fashion. Ordering considers the numeric value of each component
|
||
in turn, with "component does not exist" sorted ahead of all numeric
|
||
values.
|
||
|
||
Date based release numbers are explicitly excluded from compatibility with
|
||
this scheme, as they hinder automatic translation to other versioning
|
||
schemes, as well as preventing the adoption of semantic versioning without
|
||
changing the name of the project. Accordingly, a leading release component
|
||
greater than or equal to ``1980`` is an error.
|
||
|
||
While any number of additional components after the first are permitted
|
||
under this scheme, the most common variants are to use two components
|
||
("major.minor") or three components ("major.minor.micro").
|
||
|
||
For example::
|
||
|
||
0.9
|
||
0.9.1
|
||
0.9.2
|
||
...
|
||
0.9.10
|
||
0.9.11
|
||
1.0
|
||
1.0.1
|
||
1.1
|
||
2.0
|
||
2.0.1
|
||
|
||
A release series is any set of release numbers that start with a common
|
||
prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all
|
||
part of the ``3.3`` release series.
|
||
|
||
.. note::
|
||
|
||
Using both ``X.Y`` and ``X.Y.0`` as distinct release numbers within the
|
||
scope of a single release series is strongly discouraged, as it makes the
|
||
version ordering ambiguous for human readers. Automated tools should
|
||
either treat this case as an error, or else interpret an ``X.Y.0``
|
||
release as coming *after* the corresponding ``X.Y`` release.
|
||
|
||
The recommended practice is to always use release numbers of a consistent
|
||
length (that is, always include the trailing ``.0``). An acceptable
|
||
alternative is to consistently omit the trailing ``.0``. The example
|
||
above shows both styles, always including the ``.0`` at the second
|
||
level and consistently omitting it at the third level.
|
||
|
||
|
||
Pre-releases
|
||
------------
|
||
|
||
Some projects use an "alpha, beta, release candidate" pre-release cycle to
|
||
support testing by their users prior to a full release.
|
||
|
||
If used as part of a project's development cycle, these pre-releases are
|
||
indicated by a suffix appended directly to the last component of the
|
||
release number::
|
||
|
||
X.YaN # Alpha release
|
||
X.YbN # Beta release
|
||
X.YcN # Release candidate (alternative notation: X.YrcN)
|
||
X.Y # Full release
|
||
|
||
The pre-release suffix consists of an alphabetical identifier for the
|
||
pre-release phase, along with a non-negative integer value. Pre-releases for
|
||
a given release are ordered first by phase (alpha, beta, release candidate)
|
||
and then by the numerical component within that phase.
|
||
|
||
.. note::
|
||
|
||
Using both ``c`` and ``rc`` to identify release candidates within
|
||
the scope of a single release is strongly discouraged, as it makes the
|
||
version ordering ambiguous for human readers. Automated tools should
|
||
either treat this case as an error, or else interpret all ``rc`` versions
|
||
as coming after all ``c`` versions (that is, ``rc1`` indicates a later
|
||
version than ``c2``).
|
||
|
||
|
||
Post-releases
|
||
-------------
|
||
|
||
Some projects use post-releases to address minor errors in a release that
|
||
do not affect the distributed software (for example, correcting an error
|
||
in the release notes).
|
||
|
||
If used as part of a project's development cycle, these post-releases are
|
||
indicated by a suffix appended directly to the last component of the
|
||
release number::
|
||
|
||
X.Y.postN # Post-release
|
||
|
||
The post-release suffix consists of the string ``.post``, followed by a
|
||
non-negative integer value. Post-releases are ordered by their
|
||
numerical component, immediately following the corresponding release,
|
||
and ahead of any subsequent release.
|
||
|
||
.. note::
|
||
|
||
The use of post-releases to publish maintenance releases containing
|
||
actual bug fixes is strongly discouraged. In general, it is better
|
||
to use a longer release number and increment the final component
|
||
for each maintenance release.
|
||
|
||
Post-releases are also permitted for pre-releases::
|
||
|
||
X.YaN.postM # Post-release of an alpha release
|
||
X.YbN.postM # Post-release of a beta release
|
||
X.YcN.postM # Post-release of a release candidate
|
||
|
||
.. note::
|
||
|
||
Creating post-releases of pre-releases is strongly discouraged, as
|
||
it makes the version identifier difficult to parse for human readers.
|
||
In general, it is substantially clearer to simply create a new
|
||
pre-release by incrementing the numeric component.
|
||
|
||
|
||
Developmental releases
|
||
----------------------
|
||
|
||
Some projects make regular developmental releases, and system packagers
|
||
(especially for Linux distributions) may wish to create early releases
|
||
which do not conflict with later project releases.
|
||
|
||
If used as part of a project's development cycle, these developmental
|
||
releases are indicated by a suffix appended directly to the last
|
||
component of the release number::
|
||
|
||
X.Y.devN # Developmental release
|
||
|
||
The developmental release suffix consists of the string ``.dev``,
|
||
followed by a non-negative integer value. Developmental releases are ordered
|
||
by their numerical component, immediately before the corresponding release
|
||
(and before any pre-releases), and following any previous release.
|
||
|
||
Developmental releases are also permitted for pre-releases and
|
||
post-releases::
|
||
|
||
X.YaN.devM # Developmental release of an alpha release
|
||
X.YbN.devM # Developmental release of a beta release
|
||
X.YcN.devM # Developmental release of a release candidate
|
||
X.Y.postN.devM # Developmental release of a post-release
|
||
|
||
.. note::
|
||
|
||
Creating developmental releases of pre-releases is strongly
|
||
discouraged, as it makes the version identifier difficult to parse for
|
||
human readers. In general, it is substantially clearer to simply create
|
||
additional pre-releases by incrementing the numeric component.
|
||
|
||
Developmental releases of post-releases are also strongly discouraged,
|
||
but they may be appropriate for projects which use the post-release
|
||
notation for full maintenance releases which may include code changes.
|
||
|
||
|
||
Examples of compliant version schemes
|
||
-------------------------------------
|
||
|
||
The standard version scheme is designed to encompass a wide range of
|
||
identification practices across public and private Python projects. In
|
||
practice, a single project attempting to use the full flexibility offered
|
||
by the scheme would create a situation where human users had difficulty
|
||
figuring out the relative order of versions, even though the rules above
|
||
ensure all compliant tools will order them consistently.
|
||
|
||
The following examples illustrate a small selection of the different
|
||
approaches projects may choose to identify their releases, while still
|
||
ensuring that the "latest release" and the "latest stable release" can
|
||
be easily determined, both by human users and automated tools.
|
||
|
||
Simple "major.minor" versioning::
|
||
|
||
0.1
|
||
0.2
|
||
0.3
|
||
1.0
|
||
1.1
|
||
...
|
||
|
||
Simple "major.minor.micro" versioning::
|
||
|
||
1.1.0
|
||
1.1.1
|
||
1.1.2
|
||
1.2.0
|
||
...
|
||
|
||
"major.minor" versioning with alpha, beta and release candidate
|
||
pre-releases::
|
||
|
||
0.9
|
||
1.0a1
|
||
1.0a2
|
||
1.0b1
|
||
1.0c1
|
||
1.0
|
||
1.1a1
|
||
...
|
||
|
||
"major.minor" versioning with developmental releases, release candidates
|
||
and post-releases for minor corrections::
|
||
|
||
0.9
|
||
1.0.dev1
|
||
1.0.dev2
|
||
1.0.dev3
|
||
1.0.dev4
|
||
1.0rc1
|
||
1.0rc2
|
||
1.0
|
||
1.0.post1
|
||
1.1.dev1
|
||
...
|
||
|
||
|
||
Summary of permitted suffixes and relative ordering
|
||
---------------------------------------------------
|
||
|
||
.. note::
|
||
|
||
This section is intended primarily for authors of tools that
|
||
automatically process distribution metadata, rather than authors
|
||
of Python distributions deciding on a versioning scheme.
|
||
|
||
The numeric release component of version identifiers should be sorted in
|
||
the same order as Python's tuple sorting when the release number is
|
||
parsed as follows::
|
||
|
||
tuple(map(int, release_number.split(".")))
|
||
|
||
Within a numeric release (``1.0``, ``2.7.3``), the following suffixes
|
||
are permitted and are ordered as shown::
|
||
|
||
.devN, aN, bN, cN, rcN, <no suffix>, .postN
|
||
|
||
Note that `rc` will always sort after `c` (regardless of the numeric
|
||
component) although they are semantically equivalent. Tools are free to
|
||
reject this case as ambiguous and remain in compliance with the PEP.
|
||
|
||
Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate
|
||
(``1.0c1``, ``1.0rc1``), the following suffixes are permitted and are
|
||
ordered as shown::
|
||
|
||
.devN, <no suffix>, .postN
|
||
|
||
Within a post-release (``1.0.post1``), the following suffixes are permitted
|
||
and are ordered as shown::
|
||
|
||
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.
|
||
|
||
The following example covers many of the possible combinations::
|
||
|
||
1.0.dev456
|
||
1.0a1
|
||
1.0a2.dev456
|
||
1.0a12.dev456
|
||
1.0a12
|
||
1.0b1.dev456
|
||
1.0b2
|
||
1.0b2.post345.dev456
|
||
1.0b2.post345
|
||
1.0c1.dev456
|
||
1.0c1
|
||
1.0
|
||
1.0.post456.dev34
|
||
1.0.post456
|
||
1.1.dev1
|
||
|
||
|
||
Version ordering across different metadata versions
|
||
---------------------------------------------------
|
||
|
||
Metadata v1.0 (PEP 241) and metadata v1.1 (PEP 314) do not
|
||
specify a standard version identification or ordering scheme. This PEP does
|
||
not mandate any particular approach to handling such versions, but
|
||
acknowledges that the de facto standard for ordering them is
|
||
the scheme used by the ``pkg_resources`` component of ``setuptools``.
|
||
|
||
Software that automatically processes distribution metadata should attempt
|
||
to normalize non-compliant version identifiers to the standard scheme, and
|
||
ignore them if normalization fails. As any normalization scheme will be
|
||
implementation specific, this means that projects using non-compliant
|
||
version identifiers may not be handled consistently across different
|
||
tools, even when correctly publishing the earlier metadata versions.
|
||
|
||
For distributions currently using non-compliant version identifiers, these
|
||
filtering guidelines mean that it should be enough for the project to
|
||
simply switch to the use of compliant version identifiers to ensure
|
||
consistent handling by automated tools.
|
||
|
||
Distribution users may wish to explicitly remove non-compliant versions from
|
||
any private package indexes they control.
|
||
|
||
For metadata v1.2 (PEP 345), the version ordering described in this PEP
|
||
should be used in preference to the one defined in PEP 386.
|
||
|
||
|
||
Compatibility with other version schemes
|
||
----------------------------------------
|
||
|
||
Some projects may choose to use a version scheme which requires
|
||
translation in order to comply with the public version scheme defined in
|
||
this PEP. In such cases, the `Private-Version`__ field can be used to
|
||
record the project specific version as an arbitrary label, while the
|
||
translated public version is given in the `Version`_ field.
|
||
|
||
__ `Private-Version (optional)`_
|
||
|
||
This allows automated distribution tools to provide consistently correct
|
||
ordering of published releases, while still allowing developers to use
|
||
the internal versioning scheme they prefer for their projects.
|
||
|
||
|
||
Semantic versioning
|
||
~~~~~~~~~~~~~~~~~~~
|
||
|
||
`Semantic versioning`_ is a popular version identification scheme that is
|
||
more prescriptive than this PEP regarding the significance of different
|
||
elements of a release number. Even if a project chooses not to abide by
|
||
the details of semantic versioning, the scheme is worth understanding as
|
||
it covers many of the issues that can arise when depending on other
|
||
distributions, and when publishing a distribution that others rely on.
|
||
|
||
The "Major.Minor.Patch" (described in this PEP as "major.minor.micro")
|
||
aspects of semantic versioning (clauses 1-9 in the 2.0.0-rc-1 specification)
|
||
are fully compatible with the version scheme defined in this PEP, and abiding
|
||
by these aspects is encouraged.
|
||
|
||
Semantic versions containing a hyphen (pre-releases - clause 10) or a
|
||
plus sign (builds - clause 11) are *not* compatible with this PEP
|
||
and are not permitted in the public `Version`_ field.
|
||
|
||
One possible mechanism to translate such private semantic versions to
|
||
compatible public versions is to use the ``.devN`` suffix to specify the
|
||
appropriate version order.
|
||
|
||
.. _Semantic versioning: http://semver.org/
|
||
|
||
|
||
DVCS based version labels
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Many build tools integrate with distributed version control systems like
|
||
Git and Mercurial in order to add an identifying hash to the version
|
||
identifier. As hashes cannot be ordered reliably such versions are not
|
||
permitted in the public `Version`_ field.
|
||
|
||
As with semantic versioning, the public ``.devN`` suffix may be used to
|
||
uniquely identify such releases for publication, while the private
|
||
version field is used to record the original version label.
|
||
|
||
|
||
Date based versions
|
||
~~~~~~~~~~~~~~~~~~~
|
||
|
||
As with other incompatible version schemes, date based versions can be
|
||
stored in the ``Private-Version`` field. Translating them to a compliant
|
||
version is straightforward: the simplest approach is to subtract the year
|
||
of the first release from the major component in the release number.
|
||
|
||
|
||
Version specifiers
|
||
==================
|
||
|
||
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 identifier. For example::
|
||
|
||
0.9, >= 1.0, != 1.3.4, < 2.0
|
||
|
||
Each version identifier must be in the standard format described in
|
||
`Version scheme`_.
|
||
|
||
The comma (",") is equivalent to a logical **and** operator.
|
||
|
||
Comparison operators must be one of ``<``, ``>``, ``<=``, ``>=``, ``==``
|
||
or ``!=``.
|
||
|
||
The ``==`` and ``!=`` operators are strict - in order to match, the
|
||
version supplied must exactly match the specified version, with no
|
||
additional trailing suffix.
|
||
|
||
However, when no comparison operator is provided along with a version
|
||
identifier ``V``, it is equivalent to using the following pair of version
|
||
clauses::
|
||
|
||
>= V, < V+1
|
||
|
||
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``).
|
||
|
||
This approach makes it easy to depend on a particular release series
|
||
simply by naming it in a version specifier, without requiring any
|
||
additional annotation. For example, the following pairs of version
|
||
specifiers are equivalent::
|
||
|
||
2
|
||
>= 2, < 3
|
||
|
||
3.3
|
||
>= 3.3, < 3.4
|
||
|
||
Whitespace between a conditional operator and the following version
|
||
identifier is optional, as is the whitespace around the commas.
|
||
|
||
Pre-releases of any kind, including developmental releases, are implicitly
|
||
excluded from all version specifiers, *unless* a pre-release or developmental
|
||
developmental release is explicitly mentioned in one of the clauses. For
|
||
example, this specifier implicitly excludes all pre-releases and development
|
||
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
|
||
should also allow users to request the following alternative behaviours:
|
||
|
||
* accept already installed pre-releases for all version specifiers
|
||
* retrieve and install available pre-releases for all version specifiers
|
||
|
||
Dependency resolution tools may also allow the above behaviour to be
|
||
controlled on a per-distribution basis.
|
||
|
||
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 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 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, excluding pre-releases.
|
||
* ``Requires-Python: >=2.6,<3``: Any version of Python 2.6 or 2.7, including
|
||
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
|
||
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 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.
|
||
|
||
|
||
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
|
||
===================
|
||
|
||
An **environment marker** is a marker that can be added at the end of a
|
||
field after a semi-colon (";"), to add a condition about the execution
|
||
environment.
|
||
|
||
Here are some example of fields using such markers::
|
||
|
||
Requires-Dist: pywin32 (>1.0); sys.platform == 'win32'
|
||
Requires-Dist: foo (1,!=1.3); platform.machine == 'i386'
|
||
Requires-Dist: bar; python_version == '2.4' or python_version == '2.5'
|
||
Requires-External: libxslt; 'linux' in sys.platform
|
||
|
||
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. Parentheses are supported
|
||
for grouping.
|
||
|
||
The pseudo-grammar is ::
|
||
|
||
MARKER: EXPR [(and|or) EXPR]*
|
||
EXPR: ("(" MARKER ")") | (SUBEXPR [(in|==|!=|not in) SUBEXPR])
|
||
|
||
where ``SUBEXPR`` belongs to any of the following (the details after the
|
||
colon in each entry define the value represented by that subexpression):
|
||
|
||
* ``python_version``: '%s.%s' % (sys.version_info[0], sys.version_info[1])
|
||
* ``python_full_version``: sys.version.split()[0]
|
||
* ``os.name````: os.name
|
||
* ``sys.platform````: sys.platform
|
||
* ``platform.version``: platform.version()
|
||
* ``platform.machine``: platform.machine()
|
||
* ``platform.python_implementation``: = platform.python_implementation()
|
||
* ``extra``: (name of requested feature) or None
|
||
* ``'text'``: a free string, like ``'2.4'``, or ``'win32'``
|
||
|
||
Notice that ``in`` and ``not in`` are restricted to strings, meaning that it
|
||
is not possible to use other sequences like tuples or lists on the right
|
||
side.
|
||
|
||
The fields that benefit from this marker are:
|
||
|
||
* ``Requires-Python``
|
||
* ``Requires-External``
|
||
* ``Requires-Dist``
|
||
* ``Provides-Dist``
|
||
* ``Classifier``
|
||
|
||
|
||
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 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 within the brackets.
|
||
|
||
The full set of dependency requirements is then the union of the sets
|
||
created by first evaluating the `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 2.0, with semantics specified for handling
|
||
version changes
|
||
|
||
* Most fields are now optional
|
||
|
||
* Explicit permission for in-place clarifications without releasing a new
|
||
version of the specification
|
||
|
||
* General reformatting of the PEP to make it easier to read
|
||
|
||
* Values are now expected to be UTF-8
|
||
|
||
* Changed the version scheme
|
||
|
||
* added the new ``Private-Version`` field
|
||
* changed the top level sort position of the ``.devN`` suffix
|
||
* allowed single value version numbers
|
||
* explicit exclusion of leading or trailing whitespace
|
||
* explicit criterion for the exclusion of date based versions
|
||
* incorporated the version scheme directly into the PEP
|
||
|
||
* Changed interpretation of version specifiers
|
||
|
||
* implicitly exclude pre-releases unless explicitly requested
|
||
* treat post releases the same way as unqualified releases
|
||
|
||
* Discuss ordering and dependencies across metadata versions
|
||
|
||
* Clarify use of parentheses for grouping in environment marker
|
||
pseudo-grammar
|
||
|
||
* Support for packaging, build and installation dependencies
|
||
|
||
* the new ``Setup-Requires-Dist`` field
|
||
|
||
* Optional feature mechanism
|
||
|
||
* the new ``Provides-Extra`` field
|
||
* ``extra`` expression defined for environment markers
|
||
* optional feature support in ``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.
|
||
|
||
|
||
Metadata-Version semantics
|
||
--------------------------
|
||
|
||
The semantics of major and minor version increments are now specified,
|
||
and follow the same model as the format version semantics specified for
|
||
the wheel format in PEP 427: minor version increments must behave
|
||
reasonably when processed by a tool that only understand earlier metadata
|
||
versions with the same major version, while major version increments
|
||
may include changes that are not compatible with existing tools.
|
||
|
||
The major version number of the specification has been incremented
|
||
accordingly, as interpreting PEP 426 metadata in accordance with earlier
|
||
metadata specifications is unlikely to give the expected behaviour.
|
||
|
||
Whenever the major version number of the specification is incremented, it
|
||
is expected that deployment will take some time, as either metadata
|
||
consuming tools must be updated before other tools can safely start
|
||
producing the new format, or else the sdist and wheel formats, along with
|
||
the installation database definition, will need to be updated to support
|
||
provision of multiple versions of the metadata in parallel.
|
||
|
||
Existing tools won't abide by this guideline until they're updated to
|
||
support the new metadata standard, so the new semantics will first take
|
||
effect for a hypothetical 2.x -> 3.0 transition. For the 1.x -> 2.0
|
||
transition, it is recommended that tools continue to produce the
|
||
existing supplementary files (such as ``entry_points.txt``) in addition
|
||
to any equivalents specified using the new features of the standard
|
||
metadata format (including the formal extension mechanism).
|
||
|
||
|
||
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
|
||
make it easier to develop interoperable tools, these details are now
|
||
explicitly specified.
|
||
|
||
|
||
Changing the version scheme
|
||
---------------------------
|
||
|
||
The new ``Private-Version`` field is intended to make it clearer that the
|
||
constraints on public version identifiers are there primarily to aid in
|
||
the creation of reliable automated dependency analysis tools. Projects
|
||
are free to use whatever versioning scheme they like internally, so long
|
||
as they are able to translate it to something the dependency analysis tools
|
||
will understand.
|
||
|
||
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. 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.
|
||
|
||
Another change to the version scheme is to allow single number
|
||
versions, similar to those used by non-Python projects like Mozilla
|
||
Firefox, Google Chrome and the Fedora Linux distribution. This is actually
|
||
expected to be more useful for version specifiers (allowing things like
|
||
the simple ``Requires-Python: 3`` rather than the more convoluted
|
||
``Requires-Python: >= 3.0, < 4``), but it is easier to allow it for both
|
||
version specifiers and release numbers, rather than splitting the
|
||
two definitions.
|
||
|
||
The exclusion of leading and trailing whitespace was made explicit after
|
||
a couple of projects with version identifiers differing only in a
|
||
trailing ``\n`` character were found on PyPI.
|
||
|
||
The exclusion of major release numbers that looks like dates was implied
|
||
by the overall text of PEP 386, but not clear in the definition of the
|
||
version scheme. This exclusion has been made clear in the definition of
|
||
the release component.
|
||
|
||
Finally, 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.
|
||
|
||
`Appendix B` shows detailed results of an analysis of PyPI distribution
|
||
version information, as collected on 19th February, 2013. This analysis
|
||
compares the behaviour of the explicitly ordered version schemes defined in
|
||
this PEP and PEP 386 with the de facto standard defined by the behaviour
|
||
of setuptools. These metrics are useful, as the intent of both PEPs is to
|
||
follow existing setuptools behaviour as closely as is feasible, while
|
||
still throwing exceptions for unorderable versions (rather than trying
|
||
to guess an appropriate order as setuptools does).
|
||
|
||
Overall, the percentage of compatible distributions improves from 97.7%
|
||
with PEP 386 to 98.7% with this PEP. While the number of projects affected
|
||
in practice was small, some of the affected projects are in widespread use
|
||
(such as Pinax and selenium). The surprising ordering discrepancy also
|
||
concerned developers and acted as an unnecessary barrier to adoption of
|
||
the new metadata standard.
|
||
|
||
The data also shows that the pre-release sorting discrepancies are seen
|
||
only when analysing *all* versions from PyPI, rather than when analysing
|
||
public versions. This is largely due to the fact that PyPI normally reports
|
||
only the most recent version for each project (unless maintainers
|
||
explicitly configure their project to display additional versions). However,
|
||
installers that need to satisfy detailed version constraints often need
|
||
to look at all available versions, as they may need to retrieve an older
|
||
release.
|
||
|
||
Even this PEP doesn't completely eliminate the sorting differences relative
|
||
to setuptools:
|
||
|
||
* Sorts differently (after translations): 38 / 28194 (0.13 %)
|
||
* Sorts differently (no translations): 2 / 28194 (0.01 %)
|
||
|
||
The two remaining sort order discrepancies picked up by the analysis are due
|
||
to a pair of projects which have PyPI releases ending with a carriage
|
||
return, alongside releases with the same version number, only *without* the
|
||
trailing carriage return.
|
||
|
||
The sorting discrepancies after translation relate mainly to differences
|
||
in the handling of pre-releases where the standard mechanism is considered
|
||
to be an improvement. For example, the existing pkg_resources scheme will
|
||
sort "1.1beta1" *after* "1.1b2", whereas the suggested standard translation
|
||
for "1.1beta1" is "1.1b1", which sorts *before* "1.1b2". Similarly, the
|
||
pkg_resources scheme will sort "-dev-N" pre-releases differently from
|
||
"devN" pre-releases when they occur within the same release, while the
|
||
standard scheme will normalize both representations to ".devN" and sort
|
||
them by the numeric component.
|
||
|
||
|
||
A more opinionated description of the versioning scheme
|
||
-------------------------------------------------------
|
||
|
||
As in PEP 386, the primary focus is on codifying existing practices to make
|
||
them more amenable to automation, rather than demanding that existing
|
||
projects make non-trivial changes to their workflow. However, the
|
||
standard scheme allows significantly more flexibility than is needed
|
||
for the vast majority of simple Python packages (which often don't even
|
||
need maintenance releases - many users are happy with needing to upgrade to a
|
||
new feature release to get bug fixes).
|
||
|
||
For the benefit of novice developers, and for experienced developers
|
||
wishing to better understand the various use cases, the specification
|
||
now goes into much greater detail on the components of the defined
|
||
version scheme, including examples of how each component may be used
|
||
in practice.
|
||
|
||
The PEP also explicitly guides developers in the direction of
|
||
semantic versioning (without requiring it), and discourages the use of
|
||
several aspects of the full versioning scheme that have largely been
|
||
included in order to cover esoteric corner cases in the practices of
|
||
existing projects and in repackaging software for Linux distributions.
|
||
|
||
|
||
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 leaving the package set as
|
||
public would lead to users inadvertently downloading pre-release software,
|
||
while hiding it would defeat the purpose of publishing it for user
|
||
testing.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
|
||
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* know 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-Dist`` field).
|
||
|
||
This should allow distribution tools to more easily warn users of
|
||
obsolete projects and their suggested replacements.
|
||
|
||
The ``Obsoletes-Dist`` header is removed rather than deprecated as it
|
||
is not widely supported, and so removing it does not present any significant
|
||
barrier to tools and projects adopting the new metadata format.
|
||
|
||
|
||
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.
|
||
|
||
The ``Description`` header is deprecated rather than removed to support
|
||
easier conversion of existing tools and projects to the new metadata
|
||
format.
|
||
|
||
|
||
References
|
||
==========
|
||
|
||
This document specifies version 2.0 of the metadata format.
|
||
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
|
||
justifications for needing such a standard can be found in PEP 386.
|
||
|
||
.. [1] reStructuredText markup:
|
||
http://docutils.sourceforge.net/
|
||
|
||
.. _`Python Package Index`: http://pypi.python.org/pypi/
|
||
|
||
.. [2] PEP 301:
|
||
http://www.python.org/dev/peps/pep-0301/
|
||
|
||
.. [3] Version compatibility analysis script:
|
||
http://hg.python.org/peps/file/default/pep-0426/pepsort.py
|
||
|
||
Appendix A
|
||
==========
|
||
|
||
The script used for this analysis is available at [3]_.
|
||
|
||
Parsing and generating the Metadata 2.0 serialization format using
|
||
Python 3.3::
|
||
|
||
# Metadata 2.0 demo
|
||
from email.generator import Generator
|
||
from email import header
|
||
from email.parser import Parser
|
||
from email.policy import Compat32
|
||
from email.utils import _has_surrogates
|
||
|
||
class MetadataPolicy(Compat32):
|
||
max_line_length = 0
|
||
continuation_whitespace = '\t'
|
||
|
||
def _sanitize_header(self, name, value):
|
||
if not isinstance(value, str):
|
||
return value
|
||
if _has_surrogates(value):
|
||
raise NotImplementedError()
|
||
else:
|
||
return value
|
||
|
||
def _fold(self, name, value, sanitize):
|
||
body = ((self.linesep+self.continuation_whitespace)
|
||
.join(value.splitlines()))
|
||
return ''.join((name, ': ', body, self.linesep))
|
||
|
||
if __name__ == "__main__":
|
||
import sys
|
||
import textwrap
|
||
|
||
pkg_info = """\
|
||
Metadata-Version: 2.0
|
||
Name: package
|
||
Version: 0.1.0
|
||
Summary: A package.
|
||
Description: Description
|
||
===========
|
||
|
||
A description of the package.
|
||
|
||
"""
|
||
|
||
m = Parser(policy=MetadataPolicy()).parsestr(pkg_info)
|
||
|
||
m['License'] = 'GPL'
|
||
description = m['Description']
|
||
description_lines = description.splitlines()
|
||
m.set_payload(description_lines[0]
|
||
+ '\n'
|
||
+ textwrap.dedent('\n'.join(description_lines[1:]))
|
||
+ '\n')
|
||
del m['Description']
|
||
|
||
# Correct if sys.stdout.encoding == 'UTF-8':
|
||
Generator(sys.stdout, maxheaderlen=0).flatten(m)
|
||
|
||
Appendix B
|
||
==========
|
||
|
||
Metadata v2.0 guidelines versus setuptools::
|
||
|
||
$ ./pepsort.py
|
||
Comparing PEP 426 version sort to setuptools.
|
||
|
||
Analysing release versions
|
||
Compatible: 24477 / 28194 (86.82 %)
|
||
Compatible with translation: 247 / 28194 (0.88 %)
|
||
Compatible with filtering: 84 / 28194 (0.30 %)
|
||
No compatible versions: 420 / 28194 (1.49 %)
|
||
Sorts differently (after translations): 0 / 28194 (0.00 %)
|
||
Sorts differently (no translations): 0 / 28194 (0.00 %)
|
||
No applicable versions: 2966 / 28194 (10.52 %)
|
||
|
||
Analysing public versions
|
||
Compatible: 25600 / 28194 (90.80 %)
|
||
Compatible with translation: 1505 / 28194 (5.34 %)
|
||
Compatible with filtering: 13 / 28194 (0.05 %)
|
||
No compatible versions: 420 / 28194 (1.49 %)
|
||
Sorts differently (after translations): 0 / 28194 (0.00 %)
|
||
Sorts differently (no translations): 0 / 28194 (0.00 %)
|
||
No applicable versions: 656 / 28194 (2.33 %)
|
||
|
||
Analysing all versions
|
||
Compatible: 24239 / 28194 (85.97 %)
|
||
Compatible with translation: 2833 / 28194 (10.05 %)
|
||
Compatible with filtering: 513 / 28194 (1.82 %)
|
||
No compatible versions: 320 / 28194 (1.13 %)
|
||
Sorts differently (after translations): 38 / 28194 (0.13 %)
|
||
Sorts differently (no translations): 2 / 28194 (0.01 %)
|
||
No applicable versions: 249 / 28194 (0.88 %)
|
||
|
||
Metadata v1.2 guidelines versus setuptools::
|
||
|
||
$ ./pepsort.py 386
|
||
Comparing PEP 386 version sort to setuptools.
|
||
|
||
Analysing release versions
|
||
Compatible: 24244 / 28194 (85.99 %)
|
||
Compatible with translation: 247 / 28194 (0.88 %)
|
||
Compatible with filtering: 84 / 28194 (0.30 %)
|
||
No compatible versions: 648 / 28194 (2.30 %)
|
||
Sorts differently (after translations): 0 / 28194 (0.00 %)
|
||
Sorts differently (no translations): 0 / 28194 (0.00 %)
|
||
No applicable versions: 2971 / 28194 (10.54 %)
|
||
|
||
Analysing public versions
|
||
Compatible: 25371 / 28194 (89.99 %)
|
||
Compatible with translation: 1507 / 28194 (5.35 %)
|
||
Compatible with filtering: 12 / 28194 (0.04 %)
|
||
No compatible versions: 648 / 28194 (2.30 %)
|
||
Sorts differently (after translations): 0 / 28194 (0.00 %)
|
||
Sorts differently (no translations): 0 / 28194 (0.00 %)
|
||
No applicable versions: 656 / 28194 (2.33 %)
|
||
|
||
Analysing all versions
|
||
Compatible: 23969 / 28194 (85.01 %)
|
||
Compatible with translation: 2789 / 28194 (9.89 %)
|
||
Compatible with filtering: 530 / 28194 (1.88 %)
|
||
No compatible versions: 547 / 28194 (1.94 %)
|
||
Sorts differently (after translations): 96 / 28194 (0.34 %)
|
||
Sorts differently (no translations): 14 / 28194 (0.05 %)
|
||
No applicable versions: 249 / 28194 (0.88 %)
|
||
|
||
|
||
Copyright
|
||
=========
|
||
|
||
This document has been placed in the public domain.
|
||
|
||
|
||
..
|
||
Local Variables:
|
||
mode: indented-text
|
||
indent-tabs-mode: nil
|
||
sentence-end-double-space: t
|
||
fill-column: 70
|
||
End:
|