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