<div dir="ltr"><div>> Public index servers SHOULD NOT allow the use of local version identifiers for uploaded distributions.</div><div><br></div><div>I'm thinking this should just say "PyPI" and not "Public" broadly.</div>
<div>The point is for local versions not to confused with the one authoritative upstream version sequence, not that it couldn't be "public".</div><div>I can imagine locally versioned distributions needing to be distributed or available "publicly" (e.g. for a specific platform or system).</div>
<div>Considering the recommendation to use the "python.integrator" extension, which is generally about "downstream" modification and redistribution, it seems inconsistent to say that this redistribution couldn't be public.</div>
</div><div class="gmail_extra"><br><br><div class="gmail_quote">On Fri, Aug 8, 2014 at 2:53 PM, Donald Stufft <span dir="ltr"><<a href="mailto:donald@stufft.io" target="_blank">donald@stufft.io</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word"><div>I’m happy to announce the 6th, and hopefully final, draft of PEP 440. The</div><div>
updates to this PEP take into account feedback from several large projects and</div><div>users of various systems (such as Linux package tools) where this would be</div><div>expected to interface with. It also takes into account experience gained from</div>
<div>attempting to implement this PEP fully as a proof of concept within pip.</div><div><br></div><div>Significant updates to the PEP include:</div><div><br></div><div>* Switching the Epoch identifier from : to ! as : is not valid in a directory</div>
<div> name on Windows.</div><div>* Local version identifiers use + as a seperator in order to reduce ambigiuty</div><div> with existing versions on PyPI.</div><div>* Allow alpha numerics for local versions.</div><div>* Define a sorting algorithm for local versions.</div>
<div>* Moved the source label to PEP 426</div><div>* Normalization rules for parsing more versions following along the idea of</div><div> Postel's Law.</div><div>* Declare that PEP 440 supercedes PEP 386 for Metadata 1.2, and also should be</div>
<div> used for Metadata 1.0 and 1.1.</div><div>* Declare how invalid versions should be handled.</div><div>* Add the escape hatch "Arbitrary equality" operator === to allow depending on</div><div> versions which cannot be parsed by PEP 440.</div>
<div>* Make specifier syntax match what setuptools uses (foo==1.0 instead of foo (==1.0))</div><div>* Remove the default specifier.</div><div>* Use @ for direct references instead of "from".</div><div>* Create a reference implementation and Link To it.</div>
<div>* Lots more minor changes.</div><div><br></div><div>The outcome of these changes is that we were able to raise compatability with</div><div>all the versions registered with PyPI up to 98.12% and we sort 99.88% of</div>
<div>projects registered with PyPI the same as pkg_resources does when filtering</div><div>invalid versions from the list of versions. The fallout is that 498 projects,</div><div>or 1.06%, are no longer installable without using the ``===`` operator and 190</div>
<div>projects, or 0.4%, of projects have a different result for what the "latest"</div><div>version is.</div><div><br></div><div>Of the 498 projects a number of them are nonsensical versions like ``.`` or</div><div>
the repr of lazy objects and of the 190 projects projects it's about evenly</div><div>split between projects where pkg_resources supported something we didn't and</div><div>where PEP 440 just simply does a better job at parsing and sorting versions.</div>
<div><br></div><div>You can see the pip proof of concept and a large discussion about normalization</div><div>at <a href="https://github.com/pypa/pip/pull/1894" target="_blank">https://github.com/pypa/pip/pull/1894</a> and the reference implementation can</div>
<div>be found at <a href="https://github.com/pypa/packaging/pull/1" target="_blank">https://github.com/pypa/packaging/pull/1</a>. The Proof of Concept does</div><div>not allow using the new specifiers inside of an install_requires in a source</div>
<div>distribution because setuptools itself does not support it, but it does support</div><div>them on the command line and in requirements.txt files.</div><div><br></div><div>The online view of the PEP can be found at</div>
<div><a href="https://www.python.org/dev/peps/pep-0440/" target="_blank">https://www.python.org/dev/peps/pep-0440/</a> and the changes since the last posting</div><div>can be found at <a href="http://hg.python.org/peps/rev/59a0d31a1bc2" target="_blank">http://hg.python.org/peps/rev/59a0d31a1bc2</a> and</div>
<div><a href="http://hg.python.org/peps/rev/257822378672" target="_blank">http://hg.python.org/peps/rev/257822378672</a>.</div><div><br></div><div>Without further ado, the PEP itself:</div><div><br></div><div>Abstract</div>
<div>========</div><div><br></div><div>This PEP describes a scheme for identifying versions of Python software</div><div>distributions, and declaring dependencies on particular versions.</div><div><br></div><div>This document addresses several limitations of the previous attempt at a</div>
<div>standardized approach to versioning, as described in PEP 345 and PEP 386.</div><div><br></div><div><br></div><div>Definitions</div><div>===========</div><div><br></div><div>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",</div>
<div>"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this</div><div>document are to be interpreted as described in RFC 2119.</div><div><br></div><div>The following terms are to be interpreted as described in PEP 426:</div>
<div><br></div><div>* "Distributions"</div><div>* "Releases"</div><div>* "Build tools"</div><div>* "Index servers"</div><div>* "Publication tools"</div><div>* "Installation tools"</div>
<div>* "Automated tools"</div><div>* "Projects"</div><div><br></div><div><br></div><div>Version scheme</div><div>==============</div><div><br></div><div>Distributions are identified by a public version identifier which</div>
<div>supports all defined version comparison operations</div><div><br></div><div>The version scheme is used both to describe the distribution version</div><div>provided by a particular distribution archive, as well as to place</div>
<div>constraints on the version of dependencies needed in order to build or</div><div>run the software.</div><div><br></div><div><br></div><div>Public version identifiers</div><div>--------------------------</div><div><br>
</div><div>Public version identifiers MUST comply with the following scheme::</div><div><br></div><div> [N!]N(.N)*[{a|b|c}N][.postN][.devN]</div><div><br></div><div>Public version identifiers MUST NOT include leading or trailing whitespace.</div>
<div><br></div><div>Public version identifiers MUST be unique within a given distribution.</div><div><br></div><div>Installation tools SHOULD ignore any public versions which do not comply with</div><div>this scheme. Installation tools MAY warn the user when non-compliant</div>
<div>or ambiguous versions are detected.</div><div><br></div><div>Public version identifiers are separated into up to five segments:</div><div><br></div><div>* Epoch segment: ``N!``</div><div>* Release segment: ``N(.N)*``</div>
<div>* Pre-release segment: ``{a|b|c}N``</div><div>* Post-release segment: ``.postN``</div><div>* Development release segment: ``.devN``</div><div><br></div><div>Any given release will be a "final release", "pre-release", "post-release" or</div>
<div>"developmental release" as defined in the following sections.</div><div><br></div><div>All numeric components MUST be non-negative integers.</div><div><br></div><div>All numeric components MUST be interpreted and ordered according to their</div>
<div>numeric value, not as text strings.</div><div><br></div><div>All numeric components MAY be zero. Except as described below for the</div><div>release segment, a numeric component of zero has no special significance</div>
<div>aside from always being the lowest possible value in the version ordering.</div><div><br></div><div>.. note::</div><div><br></div><div> Some hard to read version identifiers are permitted by this scheme in</div><div>
order to better accommodate the wide range of versioning practices</div><div> across existing public and private Python projects.</div><div><br></div><div> Accordingly, some of the versioning practices which are technically</div>
<div> permitted by the PEP are strongly discouraged for new projects. Where</div><div> this is the case, the relevant details are noted in the following</div><div> sections.</div><div><br></div><div><br></div><div>Local version identifiers</div>
<div>-------------------------</div><div><br></div><div>Local version identifiers MUST comply with the following scheme::</div><div><br></div><div> <public version identifier>[+<local version label>]</div><div>
<br></div><div>They consist of a normal public version identifier (as defined in the</div><div>previous section), along with an arbitrary "local version label", separated</div><div>from the public version identifier by a plus. Local version labels have</div>
<div>no specific semantics assigned, but some syntactic restrictions are imposed.</div><div><br></div><div>Local version identifiers are used to denote fully API (and, if applicable,</div><div>ABI) compatible patched versions of upstream projects. For example, these</div>
<div>may be created by application developers and system integrators by applying</div><div>specific backported bug fixes when upgrading to a new upstream release would</div><div>be too disruptive to the application or other integrated system (such as a</div>
<div>Linux distribution).</div><div><br></div><div>The inclusion of the local version label makes it possible to differentiate</div><div>upstream releases from potentially altered rebuilds by downstream</div><div>integrators. The use of a local version identifier does not affect the kind</div>
<div>of a release but, when applied to a source distribution, does indicate that</div><div>it may not contain the exact same code as the corresponding upstream release.</div><div><br></div><div>To ensure local version identifiers can be readily incorporated as part of</div>
<div>filenames and URLs, and to avoid formatting inconsistencies in hexadecimal</div><div>hash representations, local version labels MUST be limited to the following</div><div>set of permitted characters:</div><div><br></div>
<div>* ASCII letters (``[a-zA-Z]``)</div><div>* ASCII digits (``[0-9]``)</div><div>* periods (``.``)</div><div><br></div><div>Local version labels MUST start and end with an ASCII letter or digit.</div><div><br></div><div>
Comparison and ordering of local versions considers each segment of the local</div><div>version (divided by a ``.``) separately. If a segment consists entirely of</div><div>ASCII digits then that section should be considered an integer for comparison</div>
<div>purposes and if a segment contains any ASCII letters than that segment is</div><div>compared lexicographically with case insensitivity. When comparing a numeric</div><div>and lexicographic segment, the numeric section always compares as greater than</div>
<div>the lexicographic segment. Additionally a local version with a great number of</div><div>segments will always compare as greater than a local version with fewer</div><div>segments, as long as the shorter local version's segments match the beginning</div>
<div>of the longer local version's segments exactly.</div><div><br></div><div>Local version identifiers may be used in most locations where a public</div><div>version identifier is expected, with the exception of any version specifiers</div>
<div>that explicitly rely on being able to unambiguously order candidate versions.</div><div><br></div><div>Public index servers SHOULD NOT allow the use of local version identifiers</div><div>for uploaded distributions.</div>
<div><br></div><div>Source distributions using a local version identifier SHOULD provide the</div><div>``python.integrator`` extension metadata (as defined in :pep:`459`).</div><div><br></div><div><br></div><div>Final releases</div>
<div>--------------</div><div><br></div><div>A version identifier that consists solely of a release segment and optionally</div><div>an epoch identifier is termed a "final release".</div><div><br></div><div>The release segment consists of one or more non-negative integer</div>
<div>values, separated by dots::</div><div><br></div><div> N[.N]+</div><div><br></div><div>Final releases within a project MUST be numbered in a consistently</div><div>increasing fashion, otherwise automated tools will not be able to upgrade</div>
<div>them correctly.</div><div><br></div><div>Comparison and ordering of release segments considers the numeric value</div><div>of each component of the release segment in turn. When comparing release</div><div>segments with different numbers of components, the shorter segment is</div>
<div>padded out with additional zeros as necessary.</div><div><br></div><div>While any number of additional components after the first are permitted</div><div>under this scheme, the most common variants are to use two components</div>
<div>("major.minor") or three components ("major.minor.micro").</div><div><br></div><div>For example::</div><div><br></div><div> 0.9</div><div> 0.9.1</div><div> 0.9.2</div><div> ...</div><div>
0.9.10</div><div> 0.9.11</div><div> 1.0</div><div> 1.0.1</div><div> 1.1</div><div> 2.0</div><div> 2.0.1</div><div> ...</div><div><br></div><div>A release series is any set of final release numbers that start with a</div>
<div>common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all</div><div>part of the ``3.3`` release series.</div><div><br></div><div>.. note::</div><div><br></div><div> ``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as</div>
<div> the release segment comparison rules implicit expand the two component</div><div> form to ``X.Y.0`` when comparing it to any release segment that includes</div><div> three components.</div><div><br></div><div>
Date based release segments are also permitted. An example of a date based</div><div>release scheme using the year and month of the release::</div><div><br></div><div> 2012.04</div><div> 2012.07</div><div> 2012.10</div>
<div> 2013.01</div><div> 2013.06</div><div> ...</div><div><br></div><div><br></div><div>Pre-releases</div><div>------------</div><div><br></div><div>Some projects use an "alpha, beta, release candidate" pre-release cycle to</div>
<div>support testing by their users prior to a final release.</div><div><br></div><div>If used as part of a project's development cycle, these pre-releases are</div><div>indicated by including a pre-release segment in the version identifier::</div>
<div><br></div><div> X.YaN # Alpha release</div><div> X.YbN # Beta release</div><div> X.YcN # Candidate release</div><div> X.Y # Final release</div><div><br></div><div>A version identifier that consists solely of a release segment and a</div>
<div>pre-release segment is termed a "pre-release".</div><div><br></div><div>The pre-release segment consists of an alphabetical identifier for the</div><div>pre-release phase, along with a non-negative integer value. Pre-releases for</div>
<div>a given release are ordered first by phase (alpha, beta, release candidate)</div><div>and then by the numerical component within that phase.</div><div><br></div><div>Installation tools MAY accept both ``c`` and ``rc`` releases for a common</div>
<div>release segment in order to handle some existing legacy distributions.</div><div><br></div><div>Installation tools SHOULD interpret ``rc`` versions as being equivalent to</div><div>``c`` versions (that is, ``rc1`` indicates the same version as ``c1``).</div>
<div><br></div><div>Build tools, publication tools and index servers SHOULD disallow the creation</div><div>of both ``c`` and ``rc`` releases for a common release segment.</div><div><br></div><div><br></div><div>Post-releases</div>
<div>-------------</div><div><br></div><div>Some projects use post-releases to address minor errors in a final release</div><div>that do not affect the distributed software (for example, correcting an error</div><div>in the release notes).</div>
<div><br></div><div>If used as part of a project's development cycle, these post-releases are</div><div>indicated by including a post-release segment in the version identifier::</div><div><br></div><div> X.Y.postN # Post-release</div>
<div><br></div><div>A version identifier that includes a post-release segment without a</div><div>developmental release segment is termed a "post-release".</div><div><br></div><div>The post-release segment consists of the string ``.post``, followed by a</div>
<div>non-negative integer value. Post-releases are ordered by their</div><div>numerical component, immediately following the corresponding release,</div><div>and ahead of any subsequent release.</div><div><br></div><div>.. note::</div>
<div><br></div><div> The use of post-releases to publish maintenance releases containing</div><div> actual bug fixes is strongly discouraged. In general, it is better</div><div> to use a longer release number and increment the final component</div>
<div> for each maintenance release.</div><div><br></div><div>Post-releases are also permitted for pre-releases::</div><div><br></div><div> X.YaN.postM # Post-release of an alpha release</div><div> X.YbN.postM # Post-release of a beta release</div>
<div> X.YcN.postM # Post-release of a release candidate</div><div><br></div><div>.. note::</div><div><br></div><div> Creating post-releases of pre-releases is strongly discouraged, as</div><div> it makes the version identifier difficult to parse for human readers.</div>
<div> In general, it is substantially clearer to simply create a new</div><div> pre-release by incrementing the numeric component.</div><div><br></div><div><br></div><div>Developmental releases</div><div>----------------------</div>
<div><br></div><div>Some projects make regular developmental releases, and system packagers</div><div>(especially for Linux distributions) may wish to create early releases</div><div>directly from source control which do not conflict with later project</div>
<div>releases.</div><div><br></div><div>If used as part of a project's development cycle, these developmental</div><div>releases are indicated by including a developmental release segment in the</div><div>version identifier::</div>
<div><br></div><div> X.Y.devN # Developmental release</div><div><br></div><div>A version identifier that includes a developmental release segment is</div><div>termed a "developmental release".</div><div><br>
</div><div>The developmental release segment consists of the string ``.dev``,</div><div>followed by a non-negative integer value. Developmental releases are ordered</div><div>by their numerical component, immediately before the corresponding release</div>
<div>(and before any pre-releases with the same release segment), and following</div><div>any previous release (including any post-releases).</div><div><br></div><div>Developmental releases are also permitted for pre-releases and</div>
<div>post-releases::</div><div><br></div><div> X.YaN.devM # Developmental release of an alpha release</div><div> X.YbN.devM # Developmental release of a beta release</div><div> X.YcN.devM # Developmental release of a release candidate</div>
<div> X.Y.postN.devM # Developmental release of a post-release</div><div><br></div><div>.. note::</div><div><br></div><div> Creating developmental releases of pre-releases is strongly</div><div> discouraged, as it makes the version identifier difficult to parse for</div>
<div> human readers. In general, it is substantially clearer to simply create</div><div> additional pre-releases by incrementing the numeric component.</div><div><br></div><div> Developmental releases of post-releases are also strongly discouraged,</div>
<div> but they may be appropriate for projects which use the post-release</div><div> notation for full maintenance releases which may include code changes.</div><div><br></div><div><br></div><div>Version epochs</div><div>
--------------</div><div><br></div><div>If included in a version identifier, the epoch appears before all other</div><div>components, separated from the release segment by an exclamation mark::</div><div><br></div><div> E!X.Y # Version identifier with epoch</div>
<div><br></div><div>If no explicit epoch is given, the implicit epoch is ``0``.</div><div><br></div><div>Most version identifiers will not include an epoch, as an explicit epoch is</div><div>only needed if a project *changes* the way it handles version numbering in</div>
<div>a way that means the normal version ordering rules will give the wrong</div><div>answer. For example, if a project is using date based versions like</div><div>``2014.04`` and would like to switch to semantic versions like ``1.0``, then</div>
<div>the new releases would be identified as *older* than the date based releases</div><div>when using the normal sorting scheme::</div><div><br></div><div> 1.0</div><div> 1.1</div><div> 2.0</div><div> 2013.10</div>
<div> 2014.04</div><div><br></div><div>However, by specifying an explicit epoch, the sort order can be changed</div><div>appropriately, as all versions from a later epoch are sorted after versions</div><div>from an earlier epoch::</div>
<div><br></div><div> 2013.10</div><div> 2014.04</div><div> 1!1.0</div><div> 1!1.1</div><div> 1!2.0</div><div><br></div><div>Normalization</div><div>-------------</div><div><br></div><div>In order to maintain better compatibility with existing versions there are a</div>
<div>number of "alternative" syntaxes that MUST be taken into account when parsing</div><div>versions. These syntaxes MUST be considered when parsing a version, however</div><div>they should be "normalized" to the standard syntax defined above.</div>
<div><br></div><div><br></div><div>Case sensitivity</div><div>~~~~~~~~~~~~~~~~</div><div><br></div><div>All ascii letters should be interpreted case insensitively within a version and</div><div>the normal form is lowercase. This allows versions such as ``1.1RC1`` which</div>
<div>would be normalized to ``1.1c1``.</div><div><br></div><div><br></div><div>Integer Normalization</div><div>~~~~~~~~~~~~~~~~~~~~~</div><div><br></div><div>All integers are interpreted via the ``int()`` built in and normalize to the</div>
<div>string form of the output. This means that an integer version of ``00`` would</div><div>normalize to ``0`` while ``09000`` would normalize to ``9000``. This does not</div><div>hold true for integers inside of an alphanumeric segment of a local version</div>
<div>such as ``1.0+foo0100`` which is already in its normalized form.</div><div><br></div><div><br></div><div>Pre-release separators</div><div>~~~~~~~~~~~~~~~~~~~~~~</div><div><br></div><div>Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the</div>
<div>release segment and the pre-release segment. The normal form for this is</div><div>without a separator. This allows versions such as ``1.1.a1`` or ``1.1-a1``</div><div>which would be normalized to ``1.1a1``. It should also allow a seperator to</div>
<div>be used between the pre-release signifier and the numeral. This allows versions</div><div>such as ``1.0a.1`` which would be normalized to ``1.0a1``.</div><div><br></div><div><br></div><div>Pre-release spelling</div><div>
~~~~~~~~~~~~~~~~~~~~</div><div><br></div><div>Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``rc``,</div><div>``pre``, and ``preview`` for ``a``, ``b``, ``c``, ``c``, and ``c`` respectively.</div><div>
This allows versions such as ``1.1alpha1``, ``1.1beta2``, or ``1.1rc3`` which</div><div>normalize to ``1.1a1``, ``1.1b2``, and ``1.1c3``. In every case the additional</div><div>spelling should be considered equivalent to their normal forms.</div>
<div><br></div><div><br></div><div>Implicit pre-release number</div><div>~~~~~~~~~~~~~~~~~~~~~~~~~~~</div><div><br></div><div>Pre releases allow omitting the numeral in which case it is implicitly assumed</div><div>to be ``0``. The normal form for this is to include the ``0`` explicitly. This</div>
<div>allows versions such as ``1.2a`` which is normalized to ``1.2a0``.</div><div><br></div><div><br></div><div>Post release separators</div><div>~~~~~~~~~~~~~~~~~~~~~~~</div><div><br></div><div>Post releases allow a ``.``,``-``, or ``_`` separator as well as omitting the</div>
<div>separator all together. The normal form of this is with the ``.`` separator.</div><div>This allows versions such as ``1.2-post2`` or ``1.2post2`` which normalize to</div><div>``1.2.post2``. Like the pre-release seperator this also allows an optional</div>
<div>separator between the post release signifier and the numeral. This allows</div><div>versions like ``1.2.post-2`` which would normalize to ``1.2.post2``.</div><div><br></div><div><br></div><div>Post release spelling</div>
<div>~~~~~~~~~~~~~~~~~~~~~</div><div><br></div><div>Post-releases allow the additional spellings of ``rev`` and ``r``. This allows</div><div>versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As with the</div>
<div>pre-releases the additional spellings should be considered equivalent to their</div><div>normal forms.</div><div><br></div><div><br></div><div>Implicit post release number</div><div>~~~~~~~~~~~~~~~~~~~~~~~~~~~~</div>
<div><br></div><div>Post releases allow omiting the numeral in which case it is implicitly assumed</div><div>to be ``0``. The normal form for this is to include the ``0`` explicitly. This</div><div>allows versions such as ``1.2.post`` which is normalized to ``1.2.post0``.</div>
<div><br></div><div><br></div><div>Implicit post releases</div><div>~~~~~~~~~~~~~~~~~~~~~~</div><div><br></div><div>Post releases allow omitting the ``post`` signifier all together. When using</div><div>this form the separator MUST be ``-`` and no other form is allowed. This allows</div>
<div>versions such as ``1.0-1`` to be normalized to ``1.0.post1``. This particular</div><div>normalization MUST NOT be used in conjunction with the implicit post release</div><div>number rule. In other words ``1.0-`` is *not* a valid version and it does *not*</div>
<div>normalize to ``1.0.post0``.</div><div><br></div><div><br></div><div>Development release separators</div><div>~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~</div><div><br></div><div>Development releases allow a ``.``, ``-``, or a ``_`` separator as well as</div>
<div>omitting the separator all together. The normal form of this is with the ``.``</div><div>separator. This allows versions such as ``1.2-dev2`` or ``1.2dev2`` which</div><div>normalize to ``1.2.dev2``.</div><div><br></div>
<div><br></div><div>Implicit development release number</div><div>~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~</div><div><br></div><div>Development releases allow omiting the numeral in which case it is implicitly</div><div>assumed to be ``0``. The normal form for this is to include the ``0``</div>
<div>explicitly. This allows versions such as ``1.2.dev`` which is normalized to</div><div>``1.2.dev0``.</div><div><br></div><div><br></div><div>Local version segments</div><div>~~~~~~~~~~~~~~~~~~~~~~</div><div><br></div>
<div>With a local version, in addition to the use of ``.`` as a separator of</div><div>segments, the use of ``-`` and ``_`` is also acceptable. The normal form is</div><div>using the ``.`` character. This allows versions such as ``1.0+ubuntu-1`` to be</div>
<div>normalized to ``1.0+ubuntu.1``.</div><div><br></div><div><br></div><div>Preceding v character</div><div>~~~~~~~~~~~~~~~~~~~~~</div><div><br></div><div>In order to support the common version notation of ``v1.0`` versions may be</div>
<div>preceded by a single literal ``v`` character. This character MUST be ignored</div><div>for all purposes and should be omitted from all normalized forms of the</div><div>version. The same version with and without the ``v`` is considered equivalent.</div>
<div><br></div><div><br></div><div>Leading and Trailing Whitespace</div><div>~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~</div><div><br></div><div>Leading and trailing whitespace must be silently ignored and removed from all</div><div>
normalized forms of a version. This includes ``" "``, ``\t``, ``\n``, ``\r``,</div><div>``\f``, and ``\v``. This allows accidental whitespace to be handled sensibly,</div><div>such as a version like ``1.0\n`` which normalizes to ``1.0``.</div>
<div><br></div><div><br></div><div>Examples of compliant version schemes</div><div>-------------------------------------</div><div><br></div><div>The standard version scheme is designed to encompass a wide range of</div><div>
identification practices across public and private Python projects. In</div><div>practice, a single project attempting to use the full flexibility offered</div><div>by the scheme would create a situation where human users had difficulty</div>
<div>figuring out the relative order of versions, even though the rules above</div><div>ensure all compliant tools will order them consistently.</div><div><br></div><div>The following examples illustrate a small selection of the different</div>
<div>approaches projects may choose to identify their releases, while still</div><div>ensuring that the "latest release" and the "latest stable release" can</div><div>be easily determined, both by human users and automated tools.</div>
<div><br></div><div>Simple "major.minor" versioning::</div><div><br></div><div> 0.1</div><div> 0.2</div><div> 0.3</div><div> 1.0</div><div> 1.1</div><div> ...</div><div><br></div><div>Simple "major.minor.micro" versioning::</div>
<div><br></div><div> 1.1.0</div><div> 1.1.1</div><div> 1.1.2</div><div> 1.2.0</div><div> ...</div><div><br></div><div>"major.minor" versioning with alpha, beta and candidate</div><div>pre-releases::</div>
<div><br></div><div> 0.9</div><div> 1.0a1</div><div> 1.0a2</div><div> 1.0b1</div><div> 1.0c1</div><div> 1.0</div><div> 1.1a1</div><div> ...</div><div><br></div><div>"major.minor" versioning with developmental releases, release candidates</div>
<div>and post-releases for minor corrections::</div><div><br></div><div> 0.9</div><div> 1.0.dev1</div><div> 1.0.dev2</div><div> 1.0.dev3</div><div> 1.0.dev4</div><div> 1.0rc1</div><div> 1.0rc2</div><div>
1.0</div><div> 1.0.post1</div><div> 1.1.dev1</div><div> ...</div><div><br></div><div>Date based releases, using an incrementing serial within each year, skipping</div><div>zero::</div><div><br></div><div> 2012.1</div>
<div> 2012.2</div><div> 2012.3</div><div> ...</div><div> 2012.15</div><div> 2013.1</div><div> 2013.2</div><div> ...</div><div><br></div><div><br></div><div>Summary of permitted suffixes and relative ordering</div>
<div>---------------------------------------------------</div><div><br></div><div>.. note::</div><div><br></div><div> This section is intended primarily for authors of tools that</div><div> automatically process distribution metadata, rather than developers</div>
<div> of Python distributions deciding on a versioning scheme.</div><div><br></div><div>The epoch segment of version identifiers MUST be sorted according to the</div><div>numeric value of the given epoch. If no epoch segment is present, the</div>
<div>implicit numeric value is ``0``.</div><div><br></div><div>The release segment of version identifiers MUST be sorted in</div><div>the same order as Python's tuple sorting when the release segment is</div><div>parsed as follows::</div>
<div><br></div><div> tuple(map(int, release_segment.split(".")))</div><div><br></div><div>All release segments involved in the comparison MUST be converted to a</div><div>consistent length by padding shorter segments with zeros as needed.</div>
<div><br></div><div>Within a numeric release (``1.0``, ``2.7.3``), the following suffixes</div><div>are permitted and MUST be ordered as shown::</div><div><br></div><div> .devN, aN, bN, cN/rcN, <no suffix>, .postN</div>
<div><br></div><div>Note that `rc` is considered to be semantically equivalent to `c` and must be</div><div>sorted as if it were `c`. Tools MAY reject the case of having the same ``N``</div><div>for both a ``rc`` and a ``c`` in the same release segment as ambiguous and</div>
<div>remain in compliance with the PEP.</div><div><br></div><div>Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate</div><div>(``1.0c1``, ``1.0rc1``), the following suffixes are permitted and MUST be</div>
<div>ordered as shown::</div><div><br></div><div> .devN, <no suffix>, .postN</div><div><br></div><div>Within a post-release (``1.0.post1``), the following suffixes are permitted</div><div>and MUST be ordered as shown::</div>
<div><br></div><div> .devN, <no suffix></div><div><br></div><div>Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even</div><div>when used immediately following a numeric version (e.g. ``1.0.dev456``,</div>
<div>``1.0.post1``).</div><div><br></div><div>Within a pre-release, post-release or development release segment with a</div><div>shared prefix, ordering MUST be by the value of the numeric component.</div><div><br></div><div>
The following example covers many of the possible combinations::</div><div><br></div><div> 1.0.dev456</div><div> 1.0a1</div><div> 1.0a2.dev456</div><div> 1.0a12.dev456</div><div> 1.0a12</div><div> 1.0b1.dev456</div>
<div> 1.0b2</div><div> 1.0b2.post345.dev456</div><div> 1.0b2.post345</div><div> 1.0c1.dev456</div><div> 1.0c1</div><div> 1.0</div><div> 1.0+abc.5</div><div> 1.0+abc.7</div><div> 1.0+5</div><div>
1.0.post456.dev34</div><div> 1.0.post456</div><div> 1.1.dev1</div><div><br></div><div><br></div><div>Version ordering across different metadata versions</div><div>---------------------------------------------------</div>
<div><br></div><div>Metadata v1.0 (PEP 241) and metadata v1.1 (PEP 314) do not specify a standard</div><div>version identification or ordering scheme. However metadata v1.2 (PEP 345)</div><div>does specify a scheme which is defined in PEP 386.</div>
<div><br></div><div>Due to the nature of the simple installer API it is not possible for an</div><div>installer to be aware of which metadata version a particular distribution was</div><div>using. Additionally installers required the ability to create a reasonably</div>
<div>prioritized list that includes all, or as many as possible, versions of</div><div>a project to determine which versions it should install. These requirements</div><div>necessitate a standardization across one parsing mechanism to be used for all</div>
<div>versions of a project.</div><div><br></div><div>Due to the above, this PEP MUST be used for all versions of metadata and</div><div>supersedes PEP 386 even for metadata v1.2. Tools SHOULD ignore any versions</div><div>
which cannot be parsed by the rules in this PEP, but MAY fall back to</div><div>implementation defined version parsing and ordering schemes if no versions</div><div>complying with this PEP are available.</div><div><br></div>
<div>Distribution users may wish to explicitly remove non-compliant versions from</div><div>any private package indexes they control.</div><div><br></div><div><br></div><div>Compatibility with other version schemes</div><div>
----------------------------------------</div><div><br></div><div>Some projects may choose to use a version scheme which requires</div><div>translation in order to comply with the public version scheme defined in</div><div>
this PEP. In such cases, the project specific version can be stored in the</div><div>metadata while the translated public version is published in the version field.</div><div><br></div><div>This allows automated distribution tools to provide consistently correct</div>
<div>ordering of published releases, while still allowing developers to use</div><div>the internal versioning scheme they prefer for their projects.</div><div><br></div><div><br></div><div>Semantic versioning</div><div>~~~~~~~~~~~~~~~~~~~</div>
<div><br></div><div>`Semantic versioning`_ is a popular version identification scheme that is</div><div>more prescriptive than this PEP regarding the significance of different</div><div>elements of a release number. Even if a project chooses not to abide by</div>
<div>the details of semantic versioning, the scheme is worth understanding as</div><div>it covers many of the issues that can arise when depending on other</div><div>distributions, and when publishing a distribution that others rely on.</div>
<div><br></div><div>The "Major.Minor.Patch" (described in this PEP as "major.minor.micro")</div><div>aspects of semantic versioning (clauses 1-9 in the 2.0.0-rc-1 specification)</div><div>are fully compatible with the version scheme defined in this PEP, and abiding</div>
<div>by these aspects is encouraged.</div><div><br></div><div>Semantic versions containing a hyphen (pre-releases - clause 10) or a</div><div>plus sign (builds - clause 11) are *not* compatible with this PEP</div><div>and are not permitted in the public version field.</div>
<div><br></div><div>One possible mechanism to translate such semantic versioning based source</div><div>labels to compatible public versions is to use the ``.devN`` suffix to</div><div>specify the appropriate version order.</div>
<div><br></div><div>Specific build information may also be included in local version labels.</div><div><br></div><div>.. _Semantic versioning: <a href="http://semver.org/" target="_blank">http://semver.org/</a></div><div>
<br></div><div><br></div><div>DVCS based version labels</div><div>~~~~~~~~~~~~~~~~~~~~~~~~~</div><div><br></div><div>Many build tools integrate with distributed version control systems like</div><div>Git and Mercurial in order to add an identifying hash to the version</div>
<div>identifier. As hashes cannot be ordered reliably such versions are not</div><div>permitted in the public version field.</div><div><br></div><div>As with semantic versioning, the public ``.devN`` suffix may be used to</div>
<div>uniquely identify such releases for publication, while the original DVCS based</div><div>label can be stored in the project metadata.</div><div><br></div><div>Identifying hash information may also be included in local version labels.</div>
<div><br></div><div><br></div><div>Olson database versioning</div><div>~~~~~~~~~~~~~~~~~~~~~~~~~</div><div><br></div><div>The ``pytz`` project inherits its versioning scheme from the corresponding</div><div>Olson timezone database versioning scheme: the year followed by a lowercase</div>
<div>character indicating the version of the database within that year.</div><div><br></div><div>This can be translated to a compliant public version identifier as</div><div>``<year>.<serial>``, where the serial starts at zero or one (for the</div>
<div>'<year>a' release) and is incremented with each subsequent database</div><div>update within the year.</div><div><br></div><div>As with other translated version identifiers, the corresponding Olson</div>
<div>database version could be recorded in the project metadata.</div><div><br></div><div><br></div><div>Version specifiers</div><div>==================</div><div><br></div><div>A version specifier consists of a series of version clauses, separated by</div>
<div>commas. For example::</div><div><br></div><div> ~= 0.9, >= 1.0, != 1.3.4.*, < 2.0</div><div><br></div><div>The comparison operator determines the kind of version clause:</div><div><br></div><div>* ``~=``: `Compatible release`_ clause</div>
<div>* ``==``: `Version matching`_ clause</div><div>* ``!=``: `Version exclusion`_ clause</div><div>* ``<=``, ``>=``: `Inclusive ordered comparison`_ clause</div><div>* ``<``, ``>``: `Exclusive ordered comparison`_ clause</div>
<div>* ``===``: `Arbitrary equality`_ clause.</div><div><br></div><div>The comma (",") is equivalent to a logical **and** operator: a candidate</div><div>version must match all given version clauses in order to match the</div>
<div>specifier as a whole.</div><div><br></div><div>Whitespace between a conditional operator and the following version</div><div>identifier is optional, as is the whitespace around the commas.</div><div><br></div><div>When multiple candidate versions match a version specifier, the preferred</div>
<div>version SHOULD be the latest version as determined by the consistent</div><div>ordering defined by the standard `Version scheme`_. Whether or not</div><div>pre-releases are considered as candidate versions SHOULD be handled as</div>
<div>described in `Handling of pre-releases`_.</div><div><br></div><div>Except where specifically noted below, local version identifiers MUST NOT be</div><div>permitted in version specifiers, and local version labels MUST be ignored</div>
<div>entirely when checking if candidate versions match a given version</div><div>specifier.</div><div><br></div><div><br></div><div>Compatible release</div><div>------------------</div><div><br></div><div>A compatible release clause consists of either a version identifier without</div>
<div>any comparison operator or else the compatible release operator ``~=``</div><div>and a version identifier. It matches any candidate version that is expected</div><div>to be compatible with the specified version.</div>
<div><br></div><div>The specified version identifier must be in the standard format described in</div><div>`Version scheme`_. Local version identifiers are NOT permitted in this</div><div>version specifier.</div><div><br>
</div><div>For a given release identifier ``V.N``, the compatible release clause is</div><div>approximately equivalent to the pair of comparison clauses::</div><div><br></div><div> >= V.N, == V.*</div><div><br></div>
<div>This operator MUST NOT be used with a single segment version number such as</div><div>``~=1``.</div><div><br></div><div>For example, the following groups of version clauses are equivalent::</div><div><br></div><div> 2.2</div>
<div> ~= 2.2</div><div> >= 2.2, == 2.*</div><div><br></div><div> 1.4.5</div><div> ~= 1.4.5</div><div> >= 1.4.5, == 1.4.*</div><div><br></div><div>If a pre-release, post-release or developmental release is named in a</div>
<div>compatible release clause as ``V.N.suffix``, then the suffix is ignored</div><div>when determining the required prefix match::</div><div><br></div><div> 2.2.post3</div><div> ~= 2.2.post3</div><div> >= 2.2.post3, == 2.*</div>
<div><br></div><div> 1.4.5a4</div><div> ~= 1.4.5a4</div><div> >= 1.4.5a4, == 1.4.*</div><div><br></div><div>The padding rules for release segment comparisons means that the assumed</div><div>degree of forward compatibility in a compatible release clause can be</div>
<div>controlled by appending additional zeros to the version specifier::</div><div><br></div><div> 2.2.0</div><div> ~= 2.2.0</div><div> >= 2.2.0, == 2.2.*</div><div><br></div><div> 1.4.5.0</div><div> ~= 1.4.5.0</div>
<div> >= 1.4.5.0, == 1.4.5.*</div><div><br></div><div><br></div><div>Version matching</div><div>----------------</div><div><br></div><div>A version matching clause includes the version matching operator ``==``</div>
<div>and a version identifier.</div><div><br></div><div>The specified version identifier must be in the standard format described in</div><div>`Version scheme`_, but a trailing ``.*`` is permitted on public version</div><div>
identifiers as described below.</div><div><br></div><div>By default, the version matching operator is based on a strict equality</div><div>comparison: the specified version must be exactly the same as the requested</div><div>
version. The *only* substitution performed is the zero padding of the</div><div>release segment to ensure the release segments are compared with the same</div><div>length.</div><div><br></div><div>Whether or not strict version matching is appropriate depends on the specific</div>
<div>use case for the version specifier. Automated tools SHOULD at least issue</div><div>warnings and MAY reject them entirely when strict version matches are used</div><div>inappropriately.</div><div><br></div><div>Prefix matching may be requested instead of strict comparison, by appending</div>
<div>a trailing ``.*`` to the version identifier in the version matching clause.</div><div>This means that additional trailing segments will be ignored when</div><div>determining whether or not a version identifier matches the clause. If the</div>
<div>specified version includes only a release segment, than trailing components</div><div>(or the lack thereof) in the release segment are also ignored.</div><div><br></div><div>For example, given the version ``1.1.post1``, the following clauses would</div>
<div>match or not as shown::</div><div><br></div><div> == 1.1 # Not equal, so 1.1.post1 does not match clause</div><div> == 1.1.post1 # Equal, so 1.1.post1 matches clause</div><div> == 1.1.* # Same prefix, so 1.1.post1 matches clause</div>
<div><br></div><div>For purposes of prefix matching, the pre-release segment is considered to</div><div>have an implied preceding ``.``, so given the version ``1.1a1``, the</div><div>following clauses would match or not as shown::</div>
<div><br></div><div> == 1.1 # Not equal, so 1.1a1 does not match clause</div><div> == 1.1a1 # Equal, so 1.1a1 matches clause</div><div> == 1.1.* # Same prefix, so 1.1a1 matches clause</div><div><br>
</div><div>An exact match is also considered a prefix match (this interpreation is</div><div>implied by the usual zero padding rules for the release segment of version</div><div>identifiers). Given the version ``1.1``, the following clauses would</div>
<div>match or not as shown::</div><div><br></div><div> == 1.1 # Equal, so 1.1 matches clause</div><div> == 1.1.0 # Zero padding expands 1.1 to 1.1.0, so it matches clause</div><div> == 1.1.dev1 # Not equal (dev-release), so 1.1 does not match clause</div>
<div> == 1.1a1 # Not equal (pre-release), so 1.1 does not match clause</div><div> == 1.1.post1 # Not equal (post-release), so 1.1 does not match clause</div><div> == 1.1.* # Same prefix, so 1.1 matches clause</div>
<div><br></div><div>It is invalid to have a prefix match containing a development or local release</div><div>such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the development release</div><div>segment is always the final segment in the public version, and the local version</div>
<div>is ignored for comparison purposes, so using either in a prefix match wouldn't</div><div>make any sense.</div><div><br></div><div>The use of ``==`` (without at least the wildcard suffix) when defining</div><div>dependencies for published distributions is strongly discouraged as it</div>
<div>greatly complicates the deployment of security fixes. The strict version</div><div>comparison operator is intended primarily for use when defining</div><div>dependencies for repeatable *deployments of applications* while using</div>
<div>a shared distribution index.</div><div><br></div><div>If the specified version identifier is a public version identifier (no</div><div>local version label), then the local version label of any candidate versions</div>
<div>MUST be ignored when matching versions.</div><div><br></div><div>If the specified version identifier is a local version identifier, then the</div><div>local version labels of candidate versions MUST be considered when matching</div>
<div>versions, with the public version identifier being matched as described</div><div>above, and the local version label being checked for equivalence using a</div><div>strict string equality comparison.</div><div><br></div>
<div><br></div><div>Version exclusion</div><div>-----------------</div><div><br></div><div>A version exclusion clause includes the version exclusion operator ``!=``</div><div>and a version identifier.</div><div><br></div>
<div>The allowed version identifiers and comparison semantics are the same as</div><div>those of the `Version matching`_ operator, except that the sense of any</div><div>match is inverted.</div><div><br></div><div>For example, given the version ``1.1.post1``, the following clauses would</div>
<div>match or not as shown::</div><div><br></div><div> != 1.1 # Not equal, so 1.1.post1 matches clause</div><div> != 1.1.post1 # Equal, so 1.1.post1 does not match clause</div><div> != 1.1.* # Same prefix, so 1.1.post1 does not match clause</div>
<div><br></div><div><br></div><div>Inclusive ordered comparison</div><div>----------------------------</div><div><br></div><div>An inclusive ordered comparison clause includes a comparison operator and a</div><div>version identifier, and will match any version where the comparison is correct</div>
<div>based on the relative position of the candidate version and the specified</div><div>version given the consistent ordering defined by the standard</div><div>`Version scheme`_.</div><div><br></div><div>The inclusive ordered comparison operators are ``<=`` and ``>=``.</div>
<div><br></div><div>As with version matching, the release segment is zero padded as necessary to</div><div>ensure the release segments are compared with the same length.</div><div><br></div><div>Local version identifiers are NOT permitted in this version specifier.</div>
<div><br></div><div><br></div><div>Exclusive ordered comparison</div><div>----------------------------</div><div><br></div><div>Exclusive ordered comparisons are similar to inclusive ordered comparisons,</div><div>except that the comparison operators are ``<`` and ``>`` and the clause</div>
<div>MUST be effectively interpreted as implying the prefix based version</div><div>exclusion clause ``!= V.*``.</div><div><br></div><div>The exclusive ordered comparison ``> V`` MUST NOT match a post-release</div><div>
or maintenance release of the given version. Maintenance releases can be</div><div>permitted by using the clause ``> V.0``, while both post releases and</div><div>maintenance releases can be permitted by using the inclusive ordered</div>
<div>comparison ``>= V.post1``.</div><div><br></div><div>The exclusive ordered comparison ``< V`` MUST NOT match a pre-release of</div><div>the given version, even if acceptance of pre-releases is enabled as</div><div>
described in the section below.</div><div><br></div><div>Local version identifiers are NOT permitted in this version specifier.</div><div><br></div><div><br></div><div>Arbitrary equality</div><div>------------------</div>
<div><br></div><div>Arbitrary equality comparisons are simple string equality operations which do</div><div>not take into account any of the semantic information such as zero padding or</div><div>local versions. This operator also does not support prefix matching as the</div>
<div>``==`` operator does.</div><div><br></div><div>The primary use case for arbitrary equality is to allow for specifying a</div><div>version which cannot otherwise be represented by this PEP. This operator is</div><div>
special and acts as an escape hatch to allow someone using a tool which</div><div>implements this PEP to still install a legacy version which is otherwise</div><div>incompatible with this PEP.</div><div><br></div><div>An example would be ``===foobar`` which would match a version of ``foobar``.</div>
<div><br></div><div>This operator may also be used to explicitly require an unpatched version</div><div>of a project such as ``===1.0`` which would not match for a version</div><div>``1.0+downstream1``.</div><div><br></div>
<div>Use of this operator is heavily discouraged and tooling MAY display a warning</div><div>when it is used.</div><div><br></div><div><br></div><div>Handling of pre-releases</div><div>------------------------</div><div><br>
</div><div>Pre-releases of any kind, including developmental releases, are implicitly</div><div>excluded from all version specifiers, *unless* they are already present</div><div>on the system, explicitly requested by the user, or if the only available</div>
<div>version that satisfies the version specifier is a pre-release.</div><div><br></div><div>By default, dependency resolution tools SHOULD:</div><div><br></div><div>* accept already installed pre-releases for all version specifiers</div>
<div>* accept remotely available pre-releases for version specifiers where</div><div> there is no final or post release that satisfies the version specifier</div><div>* exclude all other pre-releases from consideration</div>
<div><br></div><div>Dependency resolution tools MAY issue a warning if a pre-release is needed</div><div>to satisfy a version specifier.</div><div><br></div><div>Dependency resolution tools SHOULD also allow users to request the</div>
<div>following alternative behaviours:</div><div><br></div><div>* accepting pre-releases for all version specifiers</div><div>* excluding pre-releases for all version specifiers (reporting an error or</div><div> warning if a pre-release is already installed locally, or if a</div>
<div> pre-release is the only way to satisfy a particular specifier)</div><div><br></div><div>Dependency resolution tools MAY also allow the above behaviour to be</div><div>controlled on a per-distribution basis.</div><div>
<br></div><div>Post-releases and final releases receive no special treatment in version</div><div>specifiers - they are always included unless explicitly excluded.</div><div><br></div><div><br></div><div>Examples</div><div>
--------</div><div><br></div><div>* ``3.1``: version 3.1 or later, but not version 4.0 or later.</div><div>* ``3.1.2``: version 3.1.2 or later, but not version 3.2.0 or later.</div><div>* ``3.1a1``: version 3.1a1 or later, but not version 4.0 or later.</div>
<div>* ``== 3.1``: specifically version 3.1 (or 3.1.0), excludes all pre-releases,</div><div> post releases, developmental releases and any 3.1.x maintenance releases.</div><div>* ``== 3.1.*``: any version that starts with 3.1. Equivalent to the</div>
<div> ``3.1.0`` compatible release clause.</div><div>* ``3.1.0, != 3.1.3``: version 3.1.0 or later, but not version 3.1.3 and</div><div> not version 3.2.0 or later.</div><div><br></div><div><br></div><div>Direct references</div>
<div>=================</div><div><br></div><div>Some automated tools may permit the use of a direct reference as an</div><div>alternative to a normal version specifier. A direct reference consists of</div><div>the specifier ``@`` and an explicit URL.</div>
<div><br></div><div>Whether or not direct references are appropriate depends on the specific</div><div>use case for the version specifier. Automated tools SHOULD at least issue</div><div>warnings and MAY reject them entirely when direct references are used</div>
<div>inappropriately.</div><div><br></div><div>Public index servers SHOULD NOT allow the use of direct references in</div><div>uploaded distributions. Direct references are intended as a tool for</div><div>software integrators rather than publishers.</div>
<div><br></div><div>Depending on the use case, some appropriate targets for a direct URL</div><div>reference may be a valid ``source_url`` entry (see PEP 426), an sdist, or</div><div>a wheel binary archive. The exact URLs and targets supported will be tool</div>
<div>dependent.</div><div><br></div><div>For example, a local source archive may be referenced directly::</div><div><br></div><div> pip @ <a>file:///localbuilds/pip-1.3.1.zip</a></div><div><br></div><div>Alternatively, a prebuilt archive may also be referenced::</div>
<div><br></div><div> pip @ <a>file:///localbuilds/pip-1.3.1-py33-none-any.whl</a></div><div><br></div><div>All direct references that do not refer to a local file URL SHOULD specify</div><div>a secure transport mechanism (such as ``https``) AND include an expected</div>
<div>hash value in the URL for verification purposes. If a direct reference is</div><div>specified without any hash information, with hash information that the</div><div>tool doesn't understand, or with a selected hash algorithm that the tool</div>
<div>considers too weak to trust, automated tools SHOULD at least emit a warning</div><div>and MAY refuse to rely on the URL. If such a direct reference also uses an</div><div>insecure transport, automated tools SHOULD NOT rely on the URL.</div>
<div><br></div><div>It is RECOMMENDED that only hashes which are unconditionally provided by</div><div>the latest version of the standard library's ``hashlib`` module be used</div><div>for source archive hashes. At time of writing, that list consists of</div>
<div>``'md5'``, ``'sha1'``, ``'sha224'``, ``'sha256'``, ``'sha384'``, and</div><div>``'sha512'``.</div><div><br></div><div>For source archive and wheel references, an expected hash value may be</div>
<div>specified by including a ``<hash-algorithm>=<expected-hash>`` entry as</div><div>part of the URL fragment.</div><div><br></div><div>For version control references, the ``VCS+protocol`` scheme SHOULD be</div>
<div>used to identify both the version control system and the secure transport,</div><div>and a version control system with hash based commit identifiers SHOULD be</div><div>used. Automated tools MAY omit warnings about missing hashes for version</div>
<div>control systems that do not provide hash based commit identifiers.</div><div><br></div><div>To handle version control systems that do not support including commit or</div><div>tag references directly in the URL, that information may be appended to the</div>
<div>end of the URL using the ``@<commit-hash>`` or the ``@<tag>#<commit-hash>``</div><div>notation.</div><div><br></div><div>.. note::</div><div><br></div><div> This isn't *quite* the same as the existing VCS reference notation</div>
<div> supported by pip. Firstly, the distribution name is moved in front rather</div><div> than embedded as part of the URL. Secondly, the commit hash is included</div><div> even when retrieving based on a tag, in order to meet the requirement</div>
<div> above that *every* link should include a hash to make things harder to</div><div> forge (creating a malicious repo with a particular tag is easy, creating</div><div> one with a specific *hash*, less so).</div>
<div><br></div><div>Remote URL examples::</div><div><br></div><div> pip @ <a href="https://github.com/pypa/pip/archive/1.3.1.zip#sha1=da9234ee9982d4bbb3c72346a6de940a148ea686" target="_blank">https://github.com/pypa/pip/archive/1.3.1.zip#sha1=da9234ee9982d4bbb3c72346a6de940a148ea686</a></div>
<div> pip @ <a>git+https://github.com/pypa/pip.git@7921be1537eac1e97bc40179a57f0349c2aee67d</a></div><div> pip @ <a>git+https://github.com/pypa/pip.git@1.3.1#7921be1537eac1e97bc40179a57f0349c2aee67d</a></div><div><br>
</div><div><br></div><div><br></div><div>Updating the versioning specification</div><div>=====================================</div><div><br></div><div>The versioning specification may be updated with clarifications without</div>
<div>requiring a new PEP or a change to the metadata version.</div><div><br></div><div>Actually changing the version comparison semantics still requires a new</div><div>versioning scheme and metadata version defined in new PEPs.</div>
<div><br></div><div><br></div><div>Summary of differences from \PEP 386</div><div>====================================</div><div><br></div><div>* Moved the description of version specifiers into the versioning PEP</div><div>
<br></div><div>* Added the "direct reference" concept as a standard notation for direct</div><div> references to resources (rather than each tool needing to invent its own)</div><div><br></div><div>* Added the "local version identifier" and "local version label" concepts to</div>
<div> allow system integrators to indicate patched builds in a way that is</div><div> supported by the upstream tools, as well as to allow the incorporation of</div><div> build tags into the versioning of binary distributions.</div>
<div><br></div><div>* Added the "compatible release" clause</div><div><br></div><div>* Added the trailing wildcard syntax for prefix based version matching</div><div> and exclusion</div><div><br></div><div>* Changed the top level sort position of the ``.devN`` suffix</div>
<div><br></div><div>* Allowed single value version numbers</div><div><br></div><div>* Explicit exclusion of leading or trailing whitespace</div><div><br></div><div>* Explicit support for date based versions</div><div><br>
</div><div>* Explicit normalisation rules to improve compatibility with</div><div> existing version metadata on PyPI where it doesn't introduce</div><div> ambiguity</div><div><br></div><div>* Implicitly exclude pre-releases unless they're already present or</div>
<div> needed to satisfy a dependency</div><div><br></div><div>* Treat post releases the same way as unqualified releases</div><div><br></div><div>* Discuss ordering and dependencies across metadata versions</div><div><br>
</div><div>The rationale for major changes is given in the following sections.</div><div><br></div><div><br></div><div>Changing the version scheme</div><div>---------------------------</div><div><br></div><div>One key change in the version scheme in this PEP relative to that in</div>
<div>PEP 386 is to sort top level developmental releases like ``X.Y.devN`` ahead</div><div>of alpha releases like ``X.Ya1``. This is a far more logical sort order, as</div><div>projects already using both development releases and alphas/betas/release</div>
<div>candidates do not want their developmental releases sorted in</div><div>between their release candidates and their final releases. There is no</div><div>rationale for using ``dev`` releases in that position rather than</div>
<div>merely creating additional release candidates.</div><div><br></div><div>The updated sort order also means the sorting of ``dev`` versions is now</div><div>consistent between the metadata standard and the pre-existing behaviour</div>
<div>of ``pkg_resources`` (and hence the behaviour of current installation</div><div>tools).</div><div><br></div><div>Making this change should make it easier for affected existing projects to</div><div>migrate to the latest version of the metadata standard.</div>
<div><br></div><div>Another change to the version scheme is to allow single number</div><div>versions, similar to those used by non-Python projects like Mozilla</div><div>Firefox, Google Chrome and the Fedora Linux distribution. This is actually</div>
<div>expected to be more useful for version specifiers, but it is easier to</div><div>allow it for both version specifiers and release numbers, rather than</div><div>splitting the two definitions.</div><div><br></div><div>
The exclusion of leading and trailing whitespace was made explicit after</div><div>a couple of projects with version identifiers differing only in a</div><div>trailing ``\n`` character were found on PyPI.</div><div><br></div>
<div>Various other normalisation rules were also added as described in the</div><div>separate section on version normalisation below.</div><div><br></div><div>`Appendix A` shows detailed results of an analysis of PyPI distribution</div>
<div>version information, as collected on 8th August, 2014. This analysis</div><div>compares the behavior of the explicitly ordered version scheme defined in</div><div>this PEP with the de facto standard defined by the behavior of setuptools.</div>
<div>These metrics are useful, as the intent of this PEP is to follow existing</div><div>setuptools behavior as closely as is feasible, while still throwing</div><div>exceptions for unorderable versions (rather than trying to guess an</div>
<div>appropriate order as setuptools does).</div><div><br></div><div><br></div><div>A more opinionated description of the versioning scheme</div><div>-------------------------------------------------------</div><div><br></div>
<div>As in PEP 386, the primary focus is on codifying existing practices to make</div><div>them more amenable to automation, rather than demanding that existing</div><div>projects make non-trivial changes to their workflow. However, the</div>
<div>standard scheme allows significantly more flexibility than is needed</div><div>for the vast majority of simple Python packages (which often don't even</div><div>need maintenance releases - many users are happy with needing to upgrade to a</div>
<div>new feature release to get bug fixes).</div><div><br></div><div>For the benefit of novice developers, and for experienced developers</div><div>wishing to better understand the various use cases, the specification</div>
<div>now goes into much greater detail on the components of the defined</div><div>version scheme, including examples of how each component may be used</div><div>in practice.</div><div><br></div><div>The PEP also explicitly guides developers in the direction of</div>
<div>semantic versioning (without requiring it), and discourages the use of</div><div>several aspects of the full versioning scheme that have largely been</div><div>included in order to cover esoteric corner cases in the practices of</div>
<div>existing projects and in repackaging software for Linux distributions.</div><div><br></div><div><br></div><div>Describing version specifiers alongside the versioning scheme</div><div>-------------------------------------------------------------</div>
<div><br></div><div>The main reason to even have a standardised version scheme in the first place</div><div>is to make it easier to do reliable automated dependency analysis. It makes</div><div>more sense to describe the primary use case for version identifiers alongside</div>
<div>their definition.</div><div><br></div><div><br></div><div>Changing the interpretation of version specifiers</div><div>-------------------------------------------------</div><div><br></div><div>The previous interpretation of version specifiers made it very easy to</div>
<div>accidentally download a pre-release version of a dependency. This in</div><div>turn made it difficult for developers to publish pre-release versions</div><div>of software to the Python Package Index, as even marking the package as</div>
<div>hidden wasn't enough to keep automated tools from downloading it, and also</div><div>made it harder for users to obtain the test release manually through the</div><div>main PyPI web interface.</div><div><br></div>
<div>The previous interpretation also excluded post-releases from some version</div><div>specifiers for no adequately justified reason.</div><div><br></div><div>The updated interpretation is intended to make it difficult to accidentally</div>
<div>accept a pre-release version as satisfying a dependency, while still</div><div>allowing pre-release versions to be retrieved automatically when that's the</div><div>only way to satisfy a dependency.</div><div><br>
</div><div>The "some forward compatibility assumed" version constraint is derived from the</div><div>Ruby community's "pessimistic version constraint" operator [2]_ to allow</div><div>projects to take a cautious approach to forward compatibility promises, while</div>
<div>still easily setting a minimum required version for their dependencies. The</div><div>spelling of the compatible release clause (``~=``) is inspired by the Ruby</div><div>(``~>``) and PHP (``~``) equivalents.</div>
<div><br></div><div>Further improvements are also planned to the handling of parallel</div><div>installation of multiple versions of the same library, but these will</div><div>depend on updates to the installation database definition along with</div>
<div>improved tools for dynamic path manipulation.</div><div><br></div><div>The trailing wildcard syntax to request prefix based version matching was</div><div>added to make it possible to sensibly define both compatible release clauses</div>
<div>and the desired pre- and post-release handling semantics for ``<`` and ``>``</div><div>ordered comparison clauses.</div><div><br></div><div><br></div><div>Support for date based version identifiers</div><div>------------------------------------------</div>
<div><br></div><div>Excluding date based versions caused significant problems in migrating</div><div>``pytz`` to the new metadata standards. It also caused concerns for the</div><div>OpenStack developers, as they use a date based versioning scheme and would</div>
<div>like to be able to migrate to the new metadata standards without changing</div><div>it.</div><div><br></div><div><br></div><div>Adding version epochs</div><div>---------------------</div><div><br></div><div>Version epochs are added for the same reason they are part of other</div>
<div>versioning schemes, such as those of the Fedora and Debian Linux</div><div>distributions: to allow projects to gracefully change their approach to</div><div>numbering releases, without having a new release appear to have a lower</div>
<div>version number than previous releases and without having to change the name</div><div>of the project.</div><div><br></div><div>In particular, supporting version epochs allows a project that was previously</div><div>using date based versioning to switch to semantic versioning by specifying</div>
<div>a new version epoch.</div><div><br></div><div>The ``!`` character was chosen to delimit an epoch version rather than the</div><div>``:`` character, which is commonly used in other systems, due to the fact that</div><div>
``:`` is not a valid character in a Windows directory name.</div><div><br></div><div><br></div><div>Adding direct references</div><div>------------------------</div><div><br></div><div>Direct references are added as an "escape clause" to handle messy real</div>
<div>world situations that don't map neatly to the standard distribution model.</div><div>This includes dependencies on unpublished software for internal use, as well</div><div>as handling the more complex compatibility issues that may arise when</div>
<div>wrapping third party libraries as C extensions (this is of especial concern</div><div>to the scientific community).</div><div><br></div><div>Index servers are deliberately given a lot of freedom to disallow direct</div>
<div>references, since they're intended primarily as a tool for integrators</div><div>rather than publishers. PyPI in particular is currently going through the</div><div>process of *eliminating* dependencies on external references, as unreliable</div>
<div>external services have the effect of slowing down installation operations,</div><div>as well as reducing PyPI's own apparent reliability.</div><div><br></div><div><br></div><div>Adding arbitrary equality</div><div>
-------------------------</div><div><br></div><div>Arbitrary equality is added as an "escape clause" to handle the case where</div><div>someone needs to install a project which uses a non compliant version. Although</div>
<div>this PEP is able to attain ~97% compatibility with the versions that are</div><div>already on PyPI there are still ~3% of versions which cannot be parsed. This</div><div>operator gives a simple and effective way to still depend on them without</div>
<div>having to "guess" at the semantics of what they mean (which would be required</div><div>if anything other than strict string based equality was supported).</div><div><br></div><div><br></div><div>Adding local version identifiers</div>
<div>--------------------------------</div><div><br></div><div>It's a fact of life that downstream integrators often need to backport</div><div>upstream bug fixes to older versions. It's one of the services that gets</div>
<div>Linux distro vendors paid, and application developers may also apply patches</div><div>they need to bundled dependencies.</div><div><br></div><div>Historically, this practice has been invisible to cross-platform language</div>
<div>specific distribution tools - the reported "version" in the upstream</div><div>metadata is the same as for the unmodified code. This inaccuracy can then</div><div>cause problems when attempting to work with a mixture of integrator</div>
<div>provided code and unmodified upstream code, or even just attempting to</div><div>identify exactly which version of the software is installed.</div><div><br></div><div>The introduction of local version identifiers and "local version labels"</div>
<div>into the versioning scheme, with the corresponding ``python.integrator``</div><div>metadata extension allows this kind of activity to be represented</div><div>accurately, which should improve interoperability between the upstream</div>
<div>tools and various integrated platforms.</div><div><br></div><div>The exact scheme chosen is largely modeled on the existing behavior of</div><div>``pkg_resources.parse_version`` and ``pkg_resources.parse_requirements``,</div>
<div>with the main distinction being that where ``pkg_resources`` currently always</div><div>takes the suffix into account when comparing versions for exact matches,</div><div>the PEP requires that the local version label of the candidate version be</div>
<div>ignored when no local version label is present in the version specifier</div><div>clause. Furthermore, the PEP does not attempt to impose any structure on</div><div>the local version labels (aside from limiting the set of permitted</div>
<div>characters and defining their ordering).</div><div><br></div><div>This change is designed to ensure that an integrator provided version like</div><div>``pip 1.5+1`` or ``pip 1.5+1.git.abc123de`` will still satisfy a version</div>
<div>specifier like ``pip>=1.5``.</div><div><br></div><div>The plus is chosen primarily for readability of local version identifiers.</div><div>It was chosen instead of the hyphen to prevent</div><div>``pkg_resources.parse_version`` from parsing it as a prerelease, which is</div>
<div>important for enabling a successful migration to the new, more structured,</div><div>versioning scheme. The plus was chosen instead of a tilde because of the</div><div>significance of the tilde in Debian's version ordering algorithm.</div>
<div><br></div><div><br></div><div>Providing explicit version normalization rules</div><div>----------------------------------------------</div><div><br></div><div>Historically, the de facto standard for parsing versions in Python has been the</div>
<div>``pkg_resources.parse_version`` command from the setuptools project. This does</div><div>not attempt to reject *any* version and instead tries to make something</div><div>meaningful, with varying levels of success, out of whatever it is given. It has</div>
<div>a few simple rules but otherwise it more or less relies largely on string</div><div>comparison.</div><div><br></div><div>The normalization rules provided in this PEP exist primarily to either increase</div><div>the compatability with ``pkg_resources.parse_version``, particularly in</div>
<div>documented use cases such as ``rev``, ``r``, ``pre``, etc or to do something</div><div>more reasonable with versions that already exist on PyPI.</div><div><br></div><div>All possible normalization rules were weighed against whether or not they were</div>
<div>*likely* to cause any ambiguity (e.g. while someone might devise a scheme where</div><div>``v1.0`` and ``1.0`` are considered distinct releases, the likelihood of anyone</div><div>actually doing that, much less on any scale that is noticeable, is fairly low).</div>
<div>They were also weighed against how ``pkg_resources.parse_version`` treated a</div><div>particular version string, especially with regards to how it was sorted. Finally</div><div>each rule was weighed against the kinds of additional versions it allowed, how</div>
<div>"ugly" those versions looked, how hard there were to parse (both mentally and</div><div>mechanically) and how much additional compatibility it would bring.</div><div><br></div><div>The breadth of possible normalizations were kept to things that could easily</div>
<div>be implemented as part of the parsing of the version and not pre-parsing</div><div>transformations applied to the versions. This was done to limit the side</div><div>effects of each transformation as simple search and replace style transforms</div>
<div>increase the likelihood of ambiguous or "junk" versions.</div><div><br></div><div>For an extended discussion on the various types of normalizations that were</div><div>considered, please see the proof of concept for PEP 440 within pip [4]_.</div>
<div><br></div><div><br></div><div>References</div><div>==========</div><div><br></div><div>The initial attempt at a standardised version scheme, along with the</div><div>justifications for needing such a standard can be found in PEP 386.</div>
<div><br></div><div>.. [1] Reference Implementation of PEP 440 Versions and Specifiers</div><div> <a href="https://github.com/pypa/packaging/pull/1" target="_blank">https://github.com/pypa/packaging/pull/1</a></div><div>
<br></div><div>.. [2] Version compatibility analysis script:</div><div> <a href="https://github.com/pypa/packaging/blob/master/tasks/check.py" target="_blank">https://github.com/pypa/packaging/blob/master/tasks/check.py</a></div>
<div><br></div><div>.. [3] Pessimistic version constraint</div><div> <a href="http://docs.rubygems.org/read/chapter/16" target="_blank">http://docs.rubygems.org/read/chapter/16</a></div><div><br></div><div>.. [4] Proof of Concept: PEP 440 within pip</div>
<div> <a href="https://github.com/pypa/pip/pull/1894" target="_blank">https://github.com/pypa/pip/pull/1894</a></div><div><br></div><div><br></div><div>Appendix A</div><div>==========</div><div><br></div><div>Metadata v2.0 guidelines versus setuptools::</div>
<div><br></div><div> $ invoke check.pep440</div><div> Total Version Compatibility: 245806/250521 (98.12%)</div><div> Total Sorting Compatibility (Unfiltered): 45441/47114 (96.45%)</div><div> Total Sorting Compatibility (Filtered): 47057/47114 (99.88%)</div>
<div> Projects with No Compatible Versions: 498/47114 (1.06%)</div><div> Projects with Differing Latest Version: 688/47114 (1.46%)</div><div><br></div><div><br><div>
<div style="color:rgb(0,0,0);letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;word-wrap:break-word"><div style="color:rgb(0,0,0);letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;word-wrap:break-word">
<div>---</div><div>Donald Stufft</div><div>PGP: 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA</div></div></div>
</div>
<br></div></div><br>_______________________________________________<br>
Distutils-SIG maillist - <a href="mailto:Distutils-SIG@python.org">Distutils-SIG@python.org</a><br>
<a href="https://mail.python.org/mailman/listinfo/distutils-sig" target="_blank">https://mail.python.org/mailman/listinfo/distutils-sig</a><br>
<br></blockquote></div><br></div>