PEP 440 updates based on Donald's pip integration work

pep-0440.txt

@@ -2,7 +2,8 @@ PEP: 440
 Title: Version Identification and Dependency Specification
 Version: $Revision$
 Last-Modified: $Date$
-Author: Nick Coghlan <ncoghlan@gmail.com>
+Author: Nick Coghlan <ncoghlan@gmail.com>,
+        Donald Stufft <donald@stufft.io>
 BDFL-Delegate: Nick Coghlan <ncoghlan@gmail.com>
 Discussions-To: Distutils SIG <distutils-sig@python.org>
 Status: Draft
@@ -21,7 +22,7 @@ This PEP describes a scheme for identifying versions of Python software
 distributions, and declaring dependencies on particular versions.
 
 This document addresses several limitations of the previous attempt at a
-standardised approach to versioning, as described in PEP 345 and PEP 386.
+standardized approach to versioning, as described in PEP 345 and PEP 386.
 
 .. note::
 
@@ -56,11 +57,6 @@ Version scheme
 Distributions are identified by a public version identifier which
 supports all defined version comparison operations
 
-Distributions may also define a source label, which is not used by
-automated tools. Source labels are useful when a project internal
-versioning scheme requires translation to create a compliant public
-version identifier.
-
 The version scheme is used both to describe the distribution version
 provided by a particular distribution archive, as well as to place
 constraints on the version of dependencies needed in order to build or
@@ -72,7 +68,7 @@ Public version identifiers
 
 Public version identifiers MUST comply with the following scheme::
 
-    [N:]N(.N)*[{a|b|c|rc}N][.postN][.devN]
+    [N!]N(.N)*[{a|b|c}N][.postN][.devN]
 
 Public version identifiers MUST NOT include leading or trailing whitespace.
 
@@ -84,9 +80,9 @@ or ambiguous versions are detected.
 
 Public version identifiers are separated into up to five segments:
 
-* Epoch segment: ``N:``
+* Epoch segment: ``N!``
 * Release segment: ``N(.N)*``
-* Pre-release segment: ``{a|b|c|rc}N``
+* Pre-release segment: ``{a|b|c}N``
 * Post-release segment: ``.postN``
 * Development release segment: ``.devN``
 
@@ -119,64 +115,64 @@ Local version identifiers
 
 Local version identifiers MUST comply with the following scheme::
 
-    <public version identifier>[-N[.N]+]
+    <public version identifier>[+<local version label>]
 
-Local version identifiers are used to denote fully API compatible patched
+They consist of a normal public version identifier (as defined in the
-versions of upstream projects. These are created by application developers
+previous section), along with an arbitrary "local version label", separated
-and system integrators when upgrading to a new upstream release would be too
+from the public version identifier by a plus. Local version labels have
-disruptive to the application or other integrated system (such as a Linux
+no specific semantics assigned, but some syntactic restrictions are imposed.
-distribution).
 
-Local version identifiers may be used anywhere a public version identifier
+Local version identifiers are used to denote fully API (and, if applicable,
-is expected.
+ABI) compatible patched versions of upstream projects. For example, these
+may be created by application developers and system integrators by applying
+specific backported bug fixes when upgrading to a new upstream release would
+be too disruptive to the application or other integrated system (such as a
+Linux distribution).
 
-Local version identifiers MUST NOT include leading or trailing whitespace.
+The inclusion of the local version label makes it possible to differentiate
-
+upstream releases from potentially altered rebuilds by downstream
-Numeric components in the integrator suffix are interpreted in the same way
+integrators. The use of a local version identifier does not affect the kind
-as the numeric components of the release segment.
+of a release but, when applied to a source distribution, does indicate that
-
-The additional segment after the hyphen is referred to as the "integrator
-suffix", and makes it possible to differentiate upstream releases from
-potentially altered rebuilds by downstream integrators. The inclusion of an
-integrator suffix does not affect the kind of a release, but indicates that
 it may not contain the exact same code as the corresponding upstream release.
 
-Public index servers SHOULD NOT allow the use of local version identifiers
+To ensure local version identifiers can be readily incorporated as part of
-in uploaded distributions. Local version identifiers are intended as a tool
+filenames and URLs, and to avoid formatting inconsistencies in hexadecimal
-for software integrators rather than publishers.
+hash representations, local version labels MUST be limited to the following
+set of permitted characters:
 
-Distributions using a local version identifier SHOULD provide the
+* ASCII letters (``[a-zA-Z]``)
-``python.integrator`` extension metadata (as defined in :pep:`459`).
-
-
-Source labels
--------------
-
-Source labels are text strings with minimal defined semantics.
-
-To ensure source labels can be readily incorporated as part of file names
-and URLs, and to avoid formatting inconsistences in hexadecimal hash
-representations they MUST be limited to the following set of permitted
-characters:
-
-* Lowercase ASCII letters (``[a-z]``)
 * ASCII digits (``[0-9]``)
-* underscores (``_``)
-* hyphens (``-``)
 * periods (``.``)
-* plus signs (``+``)
 
-Source labels MUST start and end with an ASCII letter or digit.
+Local version labels MUST start and end with an ASCII letter or digit.
 
-Source labels MUST be unique within each project and MUST NOT match any
+Comparison and ordering of local versions considers each segment of the local
-defined version for the project.
+version (divided by a ``.``) separately. If a segment consists entirely of
+ASCII digits then that section should be considered an integer for comparison
+purposes and if a segment contains any ASCII letters than that segment is
+compared lexicographically with case insensitivity. When comparing a numeric
+and lexicographic segment, the numeric section always compares as greater than
+the lexicographic segment. Additionally a local version with a great number of
+segments will always compare as greater than a local version with fewer
+segments, as long as the shorter local version's segments match the beginning
+of the longer local version's segments exactly.
+
+Local version identifiers may be used in most locations where a public
+version identifier is expected, with the exception of any version specifiers
+that explicitly rely on being able to unambiguously order candidate versions.
+
+Public index servers SHOULD NOT allow the use of local version identifiers
+for uploaded distributions.
+
+Source distributions using a local version identifier SHOULD provide the
+``python.integrator`` extension metadata (as defined in :pep:`459`).
 
 
 Final releases
 --------------
 
-A version identifier that consists solely of a release segment is
+A version identifier that consists solely of a release segment and optionally
-termed a "final release".
+an epoch identifier is termed a "final release".
 
 The release segment consists of one or more non-negative integer
 values, separated by dots::
@@ -190,7 +186,7 @@ them correctly.
 Comparison and ordering of release segments considers the numeric value
 of each component of the release segment in turn. When comparing release
 segments with different numbers of components, the shorter segment is
-padded out with additional zeroes as necessary.
+padded out with additional zeros as necessary.
 
 While any number of additional components after the first are permitted
 under this scheme, the most common variants are to use two components
@@ -222,13 +218,8 @@ part of the ``3.3`` release series.
    form to ``X.Y.0`` when comparing it to any release segment that includes
    three components.
 
-Date based release segments are also permitted, and are treated differently
+Date based release segments are also permitted. An example of a date based
-in some cases when used in version specifiers. Any version identifier where
+release scheme using the year and month of the release::
-the leading component in the release segment is greater than or equal to
-``1980`` is considered to be a date based release.
-
-An example of a date based release scheme using the year and month of the
-release::
 
     2012.04
     2012.07
@@ -249,7 +240,7 @@ indicated by including a pre-release segment in the version identifier::
 
     X.YaN  # Alpha release
     X.YbN  # Beta release
-    X.YcN  # Candidate release (alternative notation: X.YrcN)
+    X.YcN  # Candidate release
     X.Y    # Final release
 
 A version identifier that consists solely of a release segment and a
@@ -263,10 +254,8 @@ and then by the numerical component within that phase.
 Installation tools MAY accept both ``c`` and ``rc`` releases for a common
 release segment in order to handle some existing legacy distributions.
 
-Installation tools SHOULD interpret all ``rc`` versions as coming after all
+Installation tools SHOULD interpret ``rc`` versions as being equivalent to
-``c`` versions (that is, ``rc1`` indicates a later version than ``c2``).
+``c`` versions (that is, ``rc1`` indicates the same version as ``c1``).
-Installation tools MAY warn the user when such ambiguous versions are
-detected, or even reject them entirely.
 
 Build tools, publication tools and index servers SHOULD disallow the creation
 of both ``c`` and ``rc`` releases for a common release segment.
@@ -360,9 +349,9 @@ Version epochs
 --------------
 
 If included in a version identifier, the epoch appears before all other
-components, separated from the release segment by a colon::
+components, separated from the release segment by an exclamation mark::
 
-    E:X.Y  # Version identifier with epoch
+    E!X.Y  # Version identifier with epoch
 
 If no explicit epoch is given, the implicit epoch is ``0``.
 
@@ -386,9 +375,97 @@ from an earlier epoch::
 
     2013.10
     2014.04
-    1:1.0
+    1!1.0
-    1:1.1
+    1!1.1
-    1:2.0
+    1!2.0
+
+Normalization
+-------------
+
+In order to maintain better compatibility with existing versions there are a
+number of "alternative" syntaxes that MUST be taken into account when parsing
+versions. These syntaxes MUST be considered when parsing a version, however
+they should be "normalized" to the standard syntax defined above.
+
+
+Case sensitivity
+~~~~~~~~~~~~~~~~
+
+All ascii letters should be interpreted case insensitively within a version and
+the normal form is lowercase. This allows versions such as ``1.1RC1`` which
+would be normalized to ``1.1c1``.
+
+
+Integer Normalization
+~~~~~~~~~~~~~~~~~~~~~
+
+All integers are interpreted via the ``int()`` built in and normalize to the
+string form of the output. This means that an integer version of ``00`` would
+normalize to ``0`` while ``09000`` would normalize to ``9000``. This does not
+hold true for integers inside of an alphanumeric segment of a local version
+such as ``1.0+foo0100`` which is already in its normalized form.
+
+
+Pre-release separators
+~~~~~~~~~~~~~~~~~~~~~~
+
+Pre-releases should allow either a ``.`` or a ``-`` separator between the
+release segment and the pre-release segment. The normal form for this is
+without a separator. This allows versions such as ``1.1.a1`` or ``1.1-a1``
+which would be normalized to ``1.1a1``.
+
+
+Pre-release spelling
+~~~~~~~~~~~~~~~~~~~~
+
+Pre-releases allow the additional spellings of alpha, beta, and rc for a, b,
+and c respectively. This allows versions such as ``1.1alpha1``, ``1.1beta2``,
+or ``1.1rc3`` which normalize to ``1.1a1``, ``1.1b2``, and ``1.1c3``. In every
+case the additional spelling should be considered equivalent to their normal
+forms.
+
+
+Implicit pre-release number
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Pre releases allow omitting the numeral in which case it is implicitly assumed
+to be ``0``. The normal form for this is to include the ``0`` explicitly. This
+allows versions such as ``1.2a`` which is normalized to ``1.2a0``.
+
+
+Post release separators
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Post releases allow either a ``.`` or a ``-`` separator as well as omitting the
+separator all together. The normal form of this is with the ``.`` separator.
+This allows versions such as ``1.2-post2`` or ``1.2post2`` which normalize to
+``1.2.post2``.
+
+
+Implicit post release number
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Post releases allow omiting the numeral in which case it is implicitly assumed
+to be ``0``. The normal form for this is to include the ``0`` explicitly. This
+allows versions such as ``1.2.post`` which is normalized to ``1.2.post0``.
+
+
+Development release separators
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Development releases allow either a ``.`` or a ``-`` separator as well as
+omitting the separator all together. The normal form of this is with the ``.``
+separator. This allows versions such as ``1.2-dev2`` or ``1.2dev2`` which
+normalize to ``1.2.dev2``.
+
+
+Implicit development release number
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Development releases allow omiting the numeral in which case it is implicitly
+assumed to be ``0``. The normal form for this is to include the ``0``
+explicitly. This allows versions such as ``1.2.dev`` which is normalized to
+``1.2.dev0``.
 
 
 Examples of compliant version schemes
@@ -483,16 +560,17 @@ parsed as follows::
     tuple(map(int, release_segment.split(".")))
 
 All release segments involved in the comparison MUST be converted to a
-consistent length by padding shorter segments with zeroes as needed.
+consistent length by padding shorter segments with zeros as needed.
 
 Within a numeric release (``1.0``, ``2.7.3``), the following suffixes
 are permitted and MUST be ordered as shown::
 
-   .devN, aN, bN, cN, rcN, <no suffix>, .postN
+   .devN, aN, bN, cN/rcN, <no suffix>, .postN
 
-Note that `rc` will always sort after `c` (regardless of the numeric
+Note that `rc` is considered to be semantically equivalent to `c` and must be
-component) although they are semantically equivalent. Tools MAY
+sorted as if it were `c`. Tools MAY reject the case of having the same ``N``
-reject this case as ambiguous and remain in compliance with the PEP.
+for both a ``rc`` and a ``c`` in the same release segment 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 MUST be
@@ -526,60 +604,46 @@ The following example covers many of the possible combinations::
     1.0c1.dev456
     1.0c1
     1.0
+    1.0+abc.5
+    1.0+abc.7
+    1.0+5
     1.0.post456.dev34
     1.0.post456
     1.1.dev1
 
-The integrator suffix of local version identifiers that share a common
-public version identifier prefix MUST be sorted in the same order as
-Python's tuple sorting when the integrator suffix is parsed as follows
-(this is the same definition as is used for the release segment)::
-
-    tuple(map(int, integrator_suffix.split(".")))
-
-All integrator suffixes involved in the comparison MUST be converted to a
-consistent length by padding shorter segments with zeroes as needed.
-
-All local version identifiers (even the ``-0`` suffix) are sorted *after*
-the corresponding unqualified public version identifier.
-
 
 Version ordering across different metadata versions
 ---------------------------------------------------
 
-Metadata v1.0 (PEP 241) and metadata v1.1 (PEP 314) do not
+Metadata v1.0 (PEP 241) and metadata v1.1 (PEP 314) do not specify a standard
-specify a standard version identification or ordering scheme. This PEP does
+version identification or ordering scheme. However metadata v1.2 (PEP 345)
-not mandate any particular approach to handling such versions, but
+does specify a scheme which is defined in PEP 386.
-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
+Due to the nature of the simple installer API it is not possible for an
-to normalize non-compliant version identifiers to the standard scheme, and
+installer to be aware of which metadata version a particular distribution was
-ignore them if normalization fails. As any normalization scheme will be
+using. Additionally installers required the ability to create a reasonably
-implementation specific, this means that projects using non-compliant
+prioritized list that includes all, or as many as possible, versions of
-version identifiers may not be handled consistently across different
+a project to determine which versions it should install. These requirements
-tools, even when correctly publishing the earlier metadata versions.
+necessitate a standardization across one parsing mechanism to be used for all
+versions of a project.
 
-For distributions currently using non-compliant version identifiers, these
+Due to the above, this PEP MUST be used for all versions of metadata and
-filtering guidelines mean that it should be enough for the project to
+supersedes PEP 386 even for metadata v1.2. Tools SHOULD ignore any versions
-simply switch to the use of compliant version identifiers to ensure
+which cannot be parsed by the rules in this PEP, but MAY fall back to
-consistent handling by automated tools.
+implementation defined version parsing and ordering schemes if no versions
+complying with this PEP are available.
 
 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 source label can be used to
+this PEP. In such cases, the project specific version can be stored in the
-record the project specific version as an arbitrary label, while the
+metadata while the translated public version is published in the version field.
-translated public version is published in the version field.
 
 This allows automated distribution tools to provide consistently correct
 ordering of published releases, while still allowing developers to use
@@ -609,6 +673,8 @@ One possible mechanism to translate such semantic versioning based source
 labels to compatible public versions is to use the ``.devN`` suffix to
 specify the appropriate version order.
 
+Specific build information may also be included in local version labels.
+
 .. _Semantic versioning: http://semver.org/
 
 
@@ -621,8 +687,10 @@ 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 source label is
+uniquely identify such releases for publication, while the original DVCS based
-used to record the original DVCS based version label.
+label can be stored in the project metadata.
+
+Identifying hash information may also be included in local version labels.
 
 
 Olson database versioning
@@ -638,7 +706,7 @@ This can be translated to a compliant public version identifier as
 update within the year.
 
 As with other translated version identifiers, the corresponding Olson
-database version could be recorded in the source label field.
+database version could be recorded in the project metadata.
 
 
 Version specifiers
@@ -647,18 +715,16 @@ Version specifiers
 A version specifier consists of a series of version clauses, separated by
 commas. For example::
 
-   0.9, ~= 0.9, >= 1.0, != 1.3.4.*, < 2.0
+   ~= 0.9, >= 1.0, != 1.3.4.*, < 2.0
 
-The comparison operator (or lack thereof) determines the kind of version
+The comparison operator determines the kind of version clause:
-clause:
 
-* No operator: equivalent to ``>=`` for date based releases, and to ``~=``
-  otherwise
 * ``~=``: `Compatible release`_ clause
 * ``==``: `Version matching`_ clause
 * ``!=``: `Version exclusion`_ clause
 * ``<=``, ``>=``: `Inclusive ordered comparison`_ clause
 * ``<``, ``>``: `Exclusive ordered comparison`_ clause
+* ``===``: `Arbitrary equality`_ clause.
 
 The comma (",") is equivalent to a logical **and** operator: a candidate
 version must match all given version clauses in order to match the
@@ -673,6 +739,11 @@ ordering defined by the standard `Version scheme`_. Whether or not
 pre-releases are considered as candidate versions SHOULD be handled as
 described in `Handling of pre-releases`_.
 
+Except where specifically noted below, local version identifiers MUST NOT be
+permitted in version specifiers, and local version labels MUST be ignored
+entirely when checking if candidate versions match a given version
+specifier.
+
 
 Compatible release
 ------------------
@@ -683,17 +754,17 @@ and a version identifier. It matches any candidate version that is expected
 to be compatible with the specified version.
 
 The specified version identifier must be in the standard format described in
-`Version scheme`_.
+`Version scheme`_. Local version identifiers are NOT permitted in this
-
+version specifier.
-Automated tools SHOULD report an error when this operator is used in
-conjunction with a date based version identifier, as it assumes the use
-of semantic API versioning.
 
 For a given release identifier ``V.N``, the compatible release clause is
 approximately equivalent to the pair of comparison clauses::
 
     >= V.N, == V.*
 
+This operator MUST NOT be used with a single segment version number such as
+``~=1``.
+
 For example, the following groups of version clauses are equivalent::
 
     2.2
@@ -718,7 +789,7 @@ when determining the required prefix match::
 
 The padding rules for release segment comparisons means that the assumed
 degree of forward compatibility in a compatible release clause can be
-controlled by appending additional zeroes to the version specifier::
+controlled by appending additional zeros to the version specifier::
 
     2.2.0
     ~= 2.2.0
@@ -736,18 +807,14 @@ A version matching clause includes the version matching operator ``==``
 and a version identifier.
 
 The specified version identifier must be in the standard format described in
-`Version scheme`_, but a trailing ``.*`` is permitted as described below.
+`Version scheme`_, but a trailing ``.*`` is permitted on public version
-
+identifiers as described below.
-If the specified version identifier is a public version identifier (no
-integrator suffix), then the integrator suffix of any candidate versions
-MUST be ignored when matching versions.
 
 By default, the version matching operator is based on a strict equality
 comparison: the specified version must be exactly the same as the requested
 version. The *only* substitution performed is the zero padding of the
 release segment to ensure the release segments are compared with the same
-length (and similarly for the integrator suffix, if matching against a
+length.
-specified local version identifier).
 
 Whether or not strict version matching is appropriate depends on the specific
 use case for the version specifier. Automated tools SHOULD at least issue
@@ -758,8 +825,8 @@ Prefix matching may be requested instead of strict comparison, by appending
 a trailing ``.*`` to the version identifier in the version matching clause.
 This means that additional trailing segments will be ignored when
 determining whether or not a version identifier matches the clause. If the
-version includes only a release segment, than trailing components in the
+specified version includes only a release segment, than trailing components
-release segment are also ignored.
+(or the lack thereof) in the release segment are also ignored.
 
 For example, given the version ``1.1.post1``, the following clauses would
 match or not as shown::
@@ -768,6 +835,32 @@ match or not as shown::
     == 1.1.post1  # Equal, so 1.1.post1 matches clause
     == 1.1.*      # Same prefix, so 1.1.post1 matches clause
 
+For purposes of prefix matching, the pre-release segment is considered to
+have an implied preceding ``.``, so given the version ``1.1a1``, the
+following clauses would match or not as shown::
+
+    == 1.1        # Not equal, so 1.1a1 does not match clause
+    == 1.1a1      # Equal, so 1.1a1 matches clause
+    == 1.1.*      # Same prefix, so 1.1a1 matches clause
+
+An exact match is also considered a prefix match (this interpreation is
+implied by the usual zero padding rules for the release segment of version
+identifiers). Given the version ``1.1``, the following clauses would
+match or not as shown::
+
+    == 1.1        # Equal, so 1.1 matches clause
+    == 1.1.0      # Zero padding expands 1.1 to 1.1.0, so it matches clause
+    == 1.1.dev1   # Not equal (dev-release), so 1.1 does not match clause
+    == 1.1a1      # Not equal (pre-release), so 1.1 does not match clause
+    == 1.1.post1  # Not equal (post-release), so 1.1 does not match clause
+    == 1.1.*      # Same prefix, so 1.1 matches clause
+
+It is invalid to have a prefix match containing a development or local release
+such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the development release
+segment is always the final segment in the public version, and the local version
+is ignored for comparison purposes, so using either in a prefix match wouldn't
+make any sense.
+
 The use of ``==`` (without at least the wildcard suffix) when defining
 dependencies for published distributions is strongly discouraged as it
 greatly complicates the deployment of security fixes. The strict version
@@ -775,6 +868,16 @@ comparison operator is intended primarily for use when defining
 dependencies for repeatable *deployments of applications* while using
 a shared distribution index.
 
+If the specified version identifier is a public version identifier (no
+local version label), then the local version label of any candidate versions
+MUST be ignored when matching versions.
+
+If the specified version identifier is a local version identifier, then the
+local version labels of candidate versions MUST be considered when matching
+versions, with the public version identifier being matched as described
+above, and the local version label being checked for equivalence using a
+strict string equality comparison.
+
 
 Version exclusion
 -----------------
@@ -786,10 +889,6 @@ The allowed version identifiers and comparison semantics are the same as
 those of the `Version matching`_ operator, except that the sense of any
 match is inverted.
 
-If the specified version identifier is a public version identifier (no
-integrator suffix), then the integrator suffix of any candidate versions
-MUST be ignored when excluding versions.
-
 For example, given the version ``1.1.post1``, the following clauses would
 match or not as shown::
 
@@ -812,9 +911,7 @@ The inclusive ordered comparison operators are ``<=`` and ``>=``.
 As with version matching, the release segment is zero padded as necessary to
 ensure the release segments are compared with the same length.
 
-Local version identifiers are handled according to the combination of their
+Local version identifiers are NOT permitted in this version specifier.
-handling by the version matching operator and the consistent ordering
-defined by the standard version scheme.
 
 
 Exclusive ordered comparison
@@ -835,9 +932,31 @@ The exclusive ordered comparison ``< V`` MUST NOT match a pre-release of
 the given version, even if acceptance of pre-releases is enabled as
 described in the section below.
 
-Local version identifiers are handled according to the combination of their
+Local version identifiers are NOT permitted in this version specifier.
-handling by the version exclusion operator and the consistent ordering
+
-defined by the standard version scheme.
+
+Arbitrary equality
+------------------
+
+Arbitrary equality comparisons are simple string equality operations which do
+not take into account any of the semantic information such as zero padding or
+local versions. This operator also does not support prefix matching as the
+``==`` operator does.
+
+The primary use case for arbitrary equality is to allow for specifying a
+version which cannot otherwise be represented by this PEP. This operator is
+special and acts as an escape hatch to allow someone using a tool which
+implements this PEP to still install a legacy version which is otherwise
+incompatible with this PEP.
+
+An example would be ``===foobar`` which would match a version of ``foobar``.
+
+This operator may also be used to explicitly require an unpatched version
+of a project such as ``===1.0`` which would not match for a version
+``1.0+downstream1``.
+
+Use of this operator is heavily discouraged and tooling MAY display a warning
+when it is used.
 
 
 Handling of pre-releases
@@ -892,7 +1011,7 @@ Direct references
 
 Some automated tools may permit the use of a direct reference as an
 alternative to a normal version specifier. A direct reference consists of
-the word ``from`` and an explicit URL.
+the specifier ``@`` and an explicit URL.
 
 Whether or not direct references are appropriate depends on the specific
 use case for the version specifier. Automated tools SHOULD at least issue
@@ -910,11 +1029,11 @@ dependent.
 
 For example, a local source archive may be referenced directly::
 
-    pip (from file:///localbuilds/pip-1.3.1.zip)
+    pip @ file:///localbuilds/pip-1.3.1.zip
 
 Alternatively, a prebuilt archive may also be referenced::
 
-    pip (from file:///localbuilds/pip-1.3.1-py33-none-any.whl)
+    pip @ file:///localbuilds/pip-1.3.1-py33-none-any.whl
 
 All direct references that do not refer to a local file URL SHOULD specify
 a secure transport mechanism (such as ``https``) AND include an expected
@@ -958,9 +1077,9 @@ notation.
 
 Remote URL examples::
 
-    pip (from https://github.com/pypa/pip/archive/1.3.1.zip#sha1=da9234ee9982d4bbb3c72346a6de940a148ea686)
+    pip @ https://github.com/pypa/pip/archive/1.3.1.zip#sha1=da9234ee9982d4bbb3c72346a6de940a148ea686
-    pip (from git+https://github.com/pypa/pip.git@7921be1537eac1e97bc40179a57f0349c2aee67d)
+    pip @ git+https://github.com/pypa/pip.git@7921be1537eac1e97bc40179a57f0349c2aee67d
-    pip (from git+https://github.com/pypa/pip.git@1.3.1#7921be1537eac1e97bc40179a57f0349c2aee67d)
+    pip @ git+https://github.com/pypa/pip.git@1.3.1#7921be1537eac1e97bc40179a57f0349c2aee67d
 
 
 
@@ -986,9 +1105,10 @@ Summary of differences from \PEP 386
 * Added the "direct reference" concept as a standard notation for direct
   references to resources (rather than each tool needing to invent its own)
 
-* Added the "local version identifier" and "integrator suffix" concepts to
+* Added the "local version identifier" and "local version label" concepts to
   allow system integrators to indicate patched builds in a way that is
-  supported by the upstream tools
+  supported by the upstream tools, as well as to allow the incorporation of
+  build tags into the versioning of binary distributions.
 
 * Added the "compatible release" clause
 
@@ -1013,16 +1133,6 @@ Summary of differences from \PEP 386
 The rationale for major changes is given in the following sections.
 
 
-Adding source labels
---------------------
-
-The new source label support 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.
-
 
 Changing the version scheme
 ---------------------------
@@ -1055,17 +1165,12 @@ 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 look 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.
-
 `Appendix A` 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
+compares the behavior of the explicitly ordered version schemes defined in
-this PEP and PEP 386 with the de facto standard defined by the behaviour
+this PEP and PEP 386 with the de facto standard defined by the behavior
 of setuptools. These metrics are useful, as the intent of both PEPs is to
-follow existing setuptools behaviour as closely as is feasible, while
+follow existing setuptools behavior as closely as is feasible, while
 still throwing exceptions for unorderable versions (rather than trying
 to guess an appropriate order as setuptools does).
 
@@ -1077,7 +1182,7 @@ concerned developers and acted as an unnecessary barrier to adoption of
 the new metadata standard, even for projects that weren't directly affected.
 
 The data also shows that the pre-release sorting discrepancies are seen
-only when analysing *all* versions from PyPI, rather than when analysing
+only when analyzing *all* versions from PyPI, rather than when analyzing
 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,
@@ -1159,22 +1264,12 @@ accept a pre-release version as satisfying a dependency, while still
 allowing pre-release versions to be retrieved automatically when that's the
 only way to satisfy a dependency.
 
-The "some forward compatibility assumed" default version constraint is
+The "some forward compatibility assumed" version constraint is derived from the
-derived from the Ruby community's "pessimistic version constraint"
+Ruby community's "pessimistic version constraint" operator [2]_ to allow
-operator [2]_ to allow projects to take a cautious approach to forward
+projects to take a cautious approach to forward compatibility promises, while
-compatibility promises, while still easily setting a minimum required
+still easily setting a minimum required version for their dependencies. The
-version for their dependencies. It is made the default behaviour rather
+spelling of the compatible release clause (``~=``) is inspired by the Ruby
-than needing a separate operator in order to explicitly discourage
+(``~>``) and PHP (``~``) equivalents.
-overspecification of dependencies by library developers. The explicit
-comparison operators remain available to cope with dependencies with
-unreliable or non-existent backwards compatibility policies, as well
-as for legitimate use cases related to deployment of integrated applications.
-
-The optional explicit spelling of the compatible release clause (``~=``) is
-inspired by the Ruby (``~>``) and PHP (``~``) equivalents. It is defined
-in order to allow easier conversion to the legacy ``pkg_resources`` version
-specifier format (which omits the parentheses, but requires a comparison
-operator).
 
 Further improvements are also planned to the handling of parallel
 installation of multiple versions of the same library, but these will
@@ -1196,19 +1291,6 @@ OpenStack developers, as they use a date based versioning scheme and would
 like to be able to migrate to the new metadata standards without changing
 it.
 
-The approach now adopted in the PEP is to:
-
-* consider a leading release segment component greater than or equal to
-  ``1980`` to denote a "date based release"
-* using ``>=`` rather than ``~=`` as the default comparison operator for
-  version specifier clauses based on a date based release
-* recommend reporting an error if ``~=`` is used with a date based release
-
-This approach means that date based version identifiers should "just work"
-for ``pytz`` and any other projects with stable APIs, and at least be usable
-(through the use of appropriate version specifiers on the consumer side) for
-projects with less stable APIs.
-
 
 Adding version epochs
 ---------------------
@@ -1224,6 +1306,10 @@ In particular, supporting version epochs allows a project that was previously
 using date based versioning to switch to semantic versioning by specifying
 a new version epoch.
 
+The ``!`` character was chosen to delimit an epoch version rather than the
+``:`` character, which is commonly used in other systems, due to the fact that
+``:`` is not a valid character in a Windows directory name.
+
 
 Adding direct references
 ------------------------
@@ -1243,6 +1329,18 @@ external services have the effect of slowing down installation operations,
 as well as reducing PyPI's own apparent reliability.
 
 
+Adding arbitrary equality
+-------------------------
+
+Arbitrary equality is added as an "escape clause" to handle the case where
+someone needs to install a project which uses a non compliant version. Although
+this PEP is able to attain ~97% compatibility with the versions that are
+already on PyPI there are still ~3% of versions which cannot be parsed. This
+operator gives a simple and effective way to still depend on them without
+having to "guess" at the semantics of what they mean (which would be required
+if anything other than strict string based equality was supported).
+
+
 Adding local version identifiers
 --------------------------------
 
@@ -1253,31 +1351,37 @@ they need to bundled dependencies.
 
 Historically, this practice has been invisible to cross-platform language
 specific distribution tools - the reported "version" in the upstream
-metadata is the same as for the unmodified code. This inaccuracy then
+metadata is the same as for the unmodified code. This inaccuracy can then
-can then cause problems when attempting to work with a mixture of integrator
+cause problems when attempting to work with a mixture of integrator
 provided code and unmodified upstream code, or even just attempting to
 identify exactly which version of the software is installed.
 
-The introduction of local version identifiers and the "integrator suffix"
+The introduction of local version identifiers and "local version labels"
 into the versioning scheme, with the corresponding ``python.integrator``
 metadata extension allows this kind of activity to be represented
 accurately, which should improve interoperability between the upstream
 tools and various integrated platforms.
 
-The exact scheme chosen is largely modelled on the existing behaviour of
+The exact scheme chosen is largely modeled on the existing behavior of
 ``pkg_resources.parse_version`` and ``pkg_resources.parse_requirements``,
 with the main distinction being that where ``pkg_resources`` currently always
 takes the suffix into account when comparing versions for exact matches,
-the PEP requires that the integrator suffix of the candidate version be
+the PEP requires that the local version label of the candidate version be
-ignored when no integrator suffix is present in the version specifier clause.
+ignored when no local version label is present in the version specifier
-
+clause. Furthermore, the PEP does not attempt to impose any structure on
-The hyphen is chosen primarily for readability of local version identifiers.
+the local version labels (aside from limiting the set of permitted
-While the wheel format also uses hyphens as separators between components,
+characters and defining their ordering).
-the escaping rules defined in PEP 427 will convert the hyphen in a local
-version identifier to an underscore before using it in a wheel filename.
 
 This change is designed to ensure that an integrator provided version like
-``pip 1.5-1`` will still satisfy a version specifier like ``pip (== 1.1)``.
+``pip 1.5+1`` or ``pip 1.5+1.git.abc123de`` will still satisfy a version
+specifier like ``pip>=1.5``.
+
+The plus is chosen primarily for readability of local version identifiers.
+It was chosen instead of the hyphen to prevent
+``pkg_resources.parse_version`` from parsing it as a prerelease, which is
+important for enabling a successful migration to the new, more structured,
+versioning scheme. The plus was chosen instead of a tilde because of the
+significance of the tilde in Debian's version algorithm.
 
 
 References
@@ -1286,80 +1390,27 @@ References
 The initial attempt at a standardised version scheme, along with the
 justifications for needing such a standard can be found in PEP 386.
 
-.. [1] Version compatibility analysis script:
+.. [1] Reference Implementation of PEP 440 Versions and Specifiers
-   http://hg.python.org/peps/file/default/pep-0426/pepsort.py
+   https://github.com/pypa/packaging/pull/1
 
-.. [2] Pessimistic version constraint
+.. [2] Version compatibility analysis script:
+   https://github.com/pypa/packaging/blob/master/tasks/check.py
+
+.. [3] Pessimistic version constraint
    http://docs.rubygems.org/read/chapter/16
 
 
 Appendix A
 ==========
 
-Metadata v2.0 guidelines versus setuptools (note that this analysis was
+Metadata v2.0 guidelines versus setuptools::
-run when this PEP was still embedded as part of PEP 426)::
 
-    $ ./pepsort.py
+    $ invoke check.pep440
-    Comparing PEP 426 version sort to setuptools.
+    Total Version Compatibility:              231807/239450 (96.81%)
-
+    Total Sorting Compatibility (Unfiltered): 43095/45505 (94.70%)
-    Analysing release versions
+    Total Sorting Compatibility (Filtered):   45481/45505 (99.95%)
-      Compatible: 24477 / 28194 (86.82 %)
+    Projects with No Compatible Versions:     802/45505 (1.76%)
-      Compatible with translation: 247 / 28194 (0.88 %)
+    Projects with Differing Latest Version:   1163/45505 (2.56%)
-      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