CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 386 – Changing the version comparison module in Distutils | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0386/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 386 – Changing the version comparison module in Distutils | peps.python.org'> <meta property="og:description" content="Note: This PEP has been superseded by the version identification and dependency specification scheme defined in PEP 440."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0386/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="Note: This PEP has been superseded by the version identification and dependency specification scheme defined in PEP 440."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 386</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 386 – Changing the version comparison module in Distutils</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Tarek Ziadé <tarek at ziade.org></dd> <dt class="field-even">Status:</dt> <dd class="field-even"><abbr title="Replaced by another succeeding PEP">Superseded</abbr></dd> <dt class="field-odd">Type:</dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Topic:</dt> <dd class="field-even"><a class="reference external" href="../topic/packaging/">Packaging</a></dd> <dt class="field-odd">Created:</dt> <dd class="field-odd">04-Jun-2009</dd> <dt class="field-even">Superseded-By:</dt> <dd class="field-even"><a class="reference external" href="../pep-0440/">440</a></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#motivation">Motivation</a></li> <li><a class="reference internal" href="#requisites-and-current-status">Requisites and current status</a><ul> <li><a class="reference internal" href="#distutils">Distutils</a></li> <li><a class="reference internal" href="#setuptools">Setuptools</a></li> <li><a class="reference internal" href="#caveats-of-existing-systems">Caveats of existing systems</a></li> </ul> </li> <li><a class="reference internal" href="#the-new-versioning-algorithm">The new versioning algorithm</a><ul> <li><a class="reference internal" href="#normalizedversion">NormalizedVersion</a></li> <li><a class="reference internal" href="#suggest-normalized-version">suggest_normalized_version</a></li> </ul> </li> <li><a class="reference internal" href="#roadmap">Roadmap</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#acknowledgments">Acknowledgments</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> Note: This PEP has been superseded by the version identification and dependency specification scheme defined in <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a>. This PEP proposed a new version comparison schema system in Distutils. </section> <section id="motivation"> <h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2> In Python there are no real restrictions yet on how a project should manage its versions, and how they should be incremented. Distutils provides a <code class="docutils literal notranslate">version</code> distribution meta-data field but it is freeform and current users, such as PyPI usually consider the latest version pushed as the <code class="docutils literal notranslate">latest</code> one, regardless of the expected semantics. Distutils will soon extend its capabilities to allow distributions to express a dependency on other distributions through the <code class="docutils literal notranslate">Requires-Dist</code> metadata field (see <a class="pep reference internal" href="../pep-0345/" title="PEP 345 – Metadata for Python Software Packages 1.2">PEP 345</a>) and it will optionally allow use of that field to restrict the dependency to a set of compatible versions. Notice that this field is replacing <code class="docutils literal notranslate">Requires</code> that was expressing dependencies on modules and packages. The <code class="docutils literal notranslate">Requires-Dist</code> field will allow a distribution to define a dependency on another package and optionally restrict this dependency to a set of compatible versions, so one may write: <div class="highlight-default notranslate"><div class="highlight"><pre>Requires-Dist: zope.interface (>3.5.0) </pre></div> </div> This means that the distribution requires <code class="docutils literal notranslate">zope.interface</code> with a version greater than <code class="docutils literal notranslate">3.5.0</code>. This also means that Python projects will need to follow the same convention as the tool that will be used to install them, so they are able to compare versions. That is why this PEP proposes, for the sake of interoperability, a standard schema to express version information and its comparison semantics. Furthermore, this will make OS packagers’ work easier when repackaging standards compliant distributions, because as of now it can be difficult to decide how two distribution versions compare. </section> <section id="requisites-and-current-status"> <h2><a class="toc-backref" href="#requisites-and-current-status" role="doc-backlink">Requisites and current status</a></h2> It is not in the scope of this PEP to provide a universal versioning schema intended to support all or even most of existing versioning schemas. There will always be competing grammars, either mandated by distro or project policies or by historical reasons that we cannot expect to change. The proposed schema should be able to express the usual versioning semantics, so it’s possible to parse any alternative versioning schema and transform it into a compliant one. This is how OS packagers usually deal with the existing version schemas and is a preferable alternative than supporting an arbitrary set of versioning schemas. Conformance to usual practice and conventions, as well as a simplicity are a plus, to ease frictionless adoption and painless transition. Practicality beats purity, sometimes. Projects have very different versioning needs, but the following are widely considered important semantics: <ol class="arabic simple"> <li>it should be possible to express more than one versioning level (usually this is expressed as major and minor revision and, sometimes, also a micro revision).</li> <li>a significant number of projects need special meaning versions for “pre-releases” (such as “alpha”, “beta”, “rc”), and these have widely used aliases (“a” stands for “alpha”, “b” for “beta” and “c” for “rc”). And these pre-release versions make it impossible to use a simple alphanumerical ordering of the version string components. (Example: 3.1a1 < 3.1)</li> <li>some projects also need “post-releases” of regular versions, mainly for installer work which can’t be clearly expressed otherwise.</li> <li>development versions allow packagers of unreleased work to avoid version clash with later regular releases.</li> </ol> For people that want to go further and use a tool to manage their version numbers, the two major ones are: <ul class="simple"> <li>The current Distutils system <a class="footnote-reference brackets" href="#id10" id="id1">[1]</a></li> <li>Setuptools <a class="footnote-reference brackets" href="#id11" id="id2">[2]</a></li> </ul> <section id="distutils"> <h3><a class="toc-backref" href="#distutils" role="doc-backlink">Distutils</a></h3> Distutils currently provides a <code class="docutils literal notranslate">StrictVersion</code> and a <code class="docutils literal notranslate">LooseVersion</code> class that can be used to manage versions. The <code class="docutils literal notranslate">LooseVersion</code> class is quite lax. From Distutils doc: <div class="highlight-default notranslate"><div class="highlight"><pre>Version numbering for anarchists and software realists. Implements the standard interface for version number classes as described above. A version number consists of a series of numbers, separated by either periods or strings of letters. When comparing version numbers, the numeric components will be compared numerically, and the alphabetic components lexically. The following are all valid version numbers, in no particular order: 1.5.1 1.5.2b2 161 3.10a 8.02 3.4j 1996.07.12 3.2.pl0 3.1.1.6 2g6 11g 0.960923 2.2beta29 1.13++ 5.5.kw 2.0b1pl0 In fact, there is no such thing as an invalid version number under this scheme; the rules for comparison are simple and predictable, but may not always give the results you want (for some definition of "want"). </pre></div> </div> This class makes any version string valid, and provides an algorithm to sort them numerically then lexically. It means that anything can be used to version your project: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> from distutils.version import LooseVersion as V >>> v1 = V('FunkyVersion') >>> v2 = V('GroovieVersion') >>> v1 > v2 False </pre></div> </div> The problem with this is that while it allows expressing any nesting level it doesn’t allow giving special meaning to versions (pre and post-releases as well as development versions), as expressed in requisites 2, 3 and 4. The <code class="docutils literal notranslate">StrictVersion</code> class is more strict. From the doc: <div class="highlight-default notranslate"><div class="highlight"><pre>Version numbering for meticulous retentive and software idealists. Implements the standard interface for version number classes as described above. A version number consists of two or three dot-separated numeric components, with an optional "pre-release" tag on the end. The pre-release tag consists of the letter 'a' or 'b' followed by a number. If the numeric components of two version numbers are equal, then one with a pre-release tag will always be deemed earlier (lesser) than one without. The following are valid version numbers (shown in the order that would be obtained by sorting according to the supplied cmp function): 0.4 0.4.0 (these two are equivalent) 0.4.1 0.5a1 0.5b3 0.5 0.9.6 1.0 1.0.4a3 1.0.4b1 1.0.4 The following are examples of invalid version numbers: 1 2.7.2.2 1.3.a4 1.3pl1 1.3c4 </pre></div> </div> This class enforces a few rules, and makes a decent tool to work with version numbers: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> from distutils.version import StrictVersion as V >>> v2 = V('GroovieVersion') Traceback (most recent call last): ... ValueError: invalid version number 'GroovieVersion' >>> v2 = V('1.1') >>> v3 = V('1.3') >>> v2 < v3 True </pre></div> </div> It adds pre-release versions, and some structure, but lacks a few semantic elements to make it usable, such as development releases or post-release tags, as expressed in requisites 3 and 4. Also, note that Distutils version classes have been present for years but are not really used in the community. </section> <section id="setuptools"> <h3><a class="toc-backref" href="#setuptools" role="doc-backlink">Setuptools</a></h3> Setuptools provides another version comparison tool <a class="footnote-reference brackets" href="#setuptools-version" id="id3">[3]</a> which does not enforce any rules for the version, but tries to provide a better algorithm to convert the strings to sortable keys, with a <code class="docutils literal notranslate">parse_version</code> function. From the doc: <div class="highlight-default notranslate"><div class="highlight"><pre>Convert a version string to a chronologically-sortable key This is a rough cross between Distutils' StrictVersion and LooseVersion; if you give it versions that would work with StrictVersion, then it behaves the same; otherwise it acts like a slightly-smarter LooseVersion. It is *possible* to create pathological version coding schemes that will fool this parser, but they should be very rare in practice. The returned value will be a tuple of strings. Numeric portions of the version are padded to 8 digits so they will compare numerically, but without relying on how numbers compare relative to strings. Dots are dropped, but dashes are retained. Trailing zeros between alpha segments or dashes are suppressed, so that e.g. "2.4.0" is considered the same as "2.4". Alphanumeric parts are lower-cased. The algorithm assumes that strings like "-" and any alpha string that alphabetically follows "final" represents a "patch level". So, "2.4-1" is assumed to be a branch or patch of "2.4", and therefore "2.4.1" is considered newer than "2.4-1", which in turn is newer than "2.4". Strings like "a", "b", "c", "alpha", "beta", "candidate" and so on (that come before "final" alphabetically) are assumed to be pre-release versions, so that the version "2.4" is considered newer than "2.4a1". Finally, to handle miscellaneous cases, the strings "pre", "preview", and "rc" are treated as if they were "c", i.e. as though they were release candidates, and therefore are not as new as a version string that does not contain them, and "dev" is replaced with an '@' so that it sorts lower than any other pre-release tag. </pre></div> </div> In other words, <code class="docutils literal notranslate">parse_version</code> will return a tuple for each version string, that is compatible with <code class="docutils literal notranslate">StrictVersion</code> but also accept arbitrary version and deal with them so they can be compared: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> from pkg_resources import parse_version as V >>> V('1.2') ('00000001', '00000002', '*final') >>> V('1.2b2') ('00000001', '00000002', '*b', '00000002', '*final') >>> V('FunkyVersion') ('*funkyversion', '*final') </pre></div> </div> In this schema practicality takes priority over purity, but as a result it doesn’t enforce any policy and leads to very complex semantics due to the lack of a clear standard. It just tries to adapt to widely used conventions. </section> <section id="caveats-of-existing-systems"> <h3><a class="toc-backref" href="#caveats-of-existing-systems" role="doc-backlink">Caveats of existing systems</a></h3> The major problem with the described version comparison tools is that they are too permissive and, at the same time, aren’t capable of expressing some of the required semantics. Many of the versions on PyPI <a class="footnote-reference brackets" href="#pypi" id="id4">[4]</a> are obviously not useful versions, which makes it difficult for users to grok the versioning that a particular package was using and to provide tools on top of PyPI. Distutils classes are not really used in Python projects, but the Setuptools function is quite widespread because it’s used by tools like <code class="docutils literal notranslate">easy_install</code> <a class="footnote-reference brackets" href="#ezinstall" id="id5">[6]</a>, <code class="docutils literal notranslate">pip</code> <a class="footnote-reference brackets" href="#pip" id="id6">[5]</a> or <code class="docutils literal notranslate">zc.buildout</code> <a class="footnote-reference brackets" href="#zc-buildout" id="id7">[7]</a> to install dependencies of a given project. While Setuptools does provide a mechanism for comparing/sorting versions, it is much preferable if the versioning spec is such that a human can make a reasonable attempt at that sorting without having to run it against some code. Also there’s a problem with the use of dates at the “major” version number (e.g. a version string “20090421”) with RPMs: it means that any attempt to switch to a more typical “major.minor…” version scheme is problematic because it will always sort less than “20090421”. Last, the meaning of <code class="docutils literal notranslate">-</code> is specific to Setuptools, while it is avoided in some packaging systems like the one used by Debian or Ubuntu. </section> </section> <section id="the-new-versioning-algorithm"> <h2><a class="toc-backref" href="#the-new-versioning-algorithm" role="doc-backlink">The new versioning algorithm</a></h2> During Pycon, members of the Python, Ubuntu and Fedora community worked on a version standard that would be acceptable for everyone. It’s currently called <code class="docutils literal notranslate">verlib</code> and a prototype lives at <a class="footnote-reference brackets" href="#prototype" id="id8">[9]</a>. The pseudo-format supported is: <div class="highlight-default notranslate"><div class="highlight"><pre>N.N[.N]+[{a|b|c|rc}N[.N]+][.postN][.devN] </pre></div> </div> The real regular expression is: <div class="highlight-default notranslate"><div class="highlight"><pre>expr = r"""^ (?P<version>\d+\.\d+) # minimum 'N.N' (?P<extraversion>(?:\.\d+)*) # any number of extra '.N' segments (?: (?P<prerel>[abc]|rc) # 'a' = alpha, 'b' = beta # 'c' or 'rc' = release candidate (?P<prerelversion>\d+(?:\.\d+)*) )? (?P<postdev>(\.post(?P<post>\d+))?(\.dev(?P<dev>\d+))?)? $""" </pre></div> </div> Some examples probably make it clearer: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> from verlib import NormalizedVersion as V >>> (V('1.0a1') ... < V('1.0a2.dev456') ... < V('1.0a2') ... < V('1.0a2.1.dev456') ... < V('1.0a2.1') ... < V('1.0b1.dev456') ... < V('1.0b2') ... < V('1.0b2.post345') ... < V('1.0c1.dev456') ... < V('1.0c1') ... < V('1.0.dev456') ... < V('1.0') ... < V('1.0.post456.dev34') ... < V('1.0.post456')) True </pre></div> </div> The trailing <code class="docutils literal notranslate">.dev123</code> is for pre-releases. The <code class="docutils literal notranslate">.post123</code> is for post-releases – which apparently are used by a number of projects out there (e.g. Twisted <a class="footnote-reference brackets" href="#twisted" id="id9">[8]</a>). For example, after a <code class="docutils literal notranslate">1.2.0</code> release there might be a <code class="docutils literal notranslate">1.2.0-r678</code> release. We used <code class="docutils literal notranslate">post</code> instead of <code class="docutils literal notranslate">r</code> because the <code class="docutils literal notranslate">r</code> is ambiguous as to whether it indicates a pre- or post-release. <code class="docutils literal notranslate">.post456.dev34</code> indicates a dev marker for a post release, that sorts before a <code class="docutils literal notranslate">.post456</code> marker. This can be used to do development versions of post releases. Pre-releases can use <code class="docutils literal notranslate">a</code> for “alpha”, <code class="docutils literal notranslate">b</code> for “beta” and <code class="docutils literal notranslate">c</code> for “release candidate”. <code class="docutils literal notranslate">rc</code> is an alternative notation for “release candidate” that is added to make the version scheme compatible with Python’s own version scheme. <code class="docutils literal notranslate">rc</code> sorts after <code class="docutils literal notranslate">c</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> from verlib import NormalizedVersion as V >>> (V('1.0a1') ... < V('1.0a2') ... < V('1.0b3') ... < V('1.0c1') ... < V('1.0rc2') ... < V('1.0')) True </pre></div> </div> Note that <code class="docutils literal notranslate">c</code> is the preferred marker for third party projects. <code class="docutils literal notranslate">verlib</code> provides a <code class="docutils literal notranslate">NormalizedVersion</code> class and a <code class="docutils literal notranslate">suggest_normalized_version</code> function. <section id="normalizedversion"> <h3><a class="toc-backref" href="#normalizedversion" role="doc-backlink">NormalizedVersion</a></h3> The <code class="docutils literal notranslate">NormalizedVersion</code> class is used to hold a version and to compare it with others. It takes a string as an argument, that contains the representation of the version: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> from verlib import NormalizedVersion >>> version = NormalizedVersion('1.0') </pre></div> </div> The version can be represented as a string: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> str(version) '1.0' </pre></div> </div> Or compared with others: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> NormalizedVersion('1.0') > NormalizedVersion('0.9') True >>> NormalizedVersion('1.0') < NormalizedVersion('1.1') True </pre></div> </div> A class method called <code class="docutils literal notranslate">from_parts</code> is available if you want to create an instance by providing the parts that composes the version. Examples <div class="highlight-default notranslate"><div class="highlight"><pre>>>> version = NormalizedVersion.from_parts((1, 0)) >>> str(version) '1.0' >>> version = NormalizedVersion.from_parts((1, 0), ('c', 4)) >>> str(version) '1.0c4' >>> version = NormalizedVersion.from_parts((1, 0), ('c', 4), ('dev', 34)) >>> str(version) '1.0c4.dev34' </pre></div> </div> </section> <section id="suggest-normalized-version"> <h3><a class="toc-backref" href="#suggest-normalized-version" role="doc-backlink">suggest_normalized_version</a></h3> <code class="docutils literal notranslate">suggest_normalized_version</code> is a function that suggests a normalized version close to the given version string. If you have a version string that isn’t normalized (i.e. <code class="docutils literal notranslate">NormalizedVersion</code> doesn’t like it) then you might be able to get an equivalent (or close) normalized version from this function. This does a number of simple normalizations to the given string, based on an observation of versions currently in use on PyPI. Given a dump of those versions on January 6th 2010, the function has given those results out of the 8821 distributions PyPI had: <ul class="simple"> <li>7822 (88.67%) already match <code class="docutils literal notranslate">NormalizedVersion</code> without any change</li> <li>717 (8.13%) match when using this suggestion method</li> <li>282 (3.20%) don’t match at all.</li> </ul> The 3.20% of projects that are incompatible with <code class="docutils literal notranslate">NormalizedVersion</code> and cannot be transformed into a compatible form, are for most of them date-based version schemes, versions with custom markers, or dummy versions. Examples: <ul class="simple"> <li>working proof of concept</li> <li>1 (first draft)</li> <li>unreleased.unofficialdev</li> <li>0.1.alphadev</li> <li>2008-03-29_r219</li> <li>etc.</li> </ul> When a tool needs to work with versions, a strategy is to use <code class="docutils literal notranslate">suggest_normalized_version</code> on the versions string. If this function returns <code class="docutils literal notranslate">None</code>, it means that the provided version is not close enough to the standard scheme. If it returns a version that slightly differs from the original version, it’s a suggested normalized version. Last, if it returns the same string, it means that the version matches the scheme. Here’s an example of usage: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> from verlib import suggest_normalized_version, NormalizedVersion >>> import warnings >>> def validate_version(version): ... rversion = suggest_normalized_version(version) ... if rversion is None: ... raise ValueError('Cannot work with "%s"' % version) ... if rversion != version: ... warnings.warn('"%s" is not a normalized version.\n' ... 'It has been transformed into "%s" ' ... 'for interoperability.' % (version, rversion)) ... return NormalizedVersion(rversion) ... >>> validate_version('2.4-rc1') __main__:8: UserWarning: "2.4-rc1" is not a normalized version. It has been transformed into "2.4c1" for interoperability. NormalizedVersion('2.4c1') >>> validate_version('2.4c1') NormalizedVersion('2.4c1') >>> validate_version('foo') Traceback (most recent call last): File "<stdin>", line 1, in <module> File "<stdin>", line 4, in validate_version ValueError: Cannot work with "foo" </pre></div> </div> </section> </section> <section id="roadmap"> <h2><a class="toc-backref" href="#roadmap" role="doc-backlink">Roadmap</a></h2> Distutils will deprecate its existing versions class in favor of <code class="docutils literal notranslate">NormalizedVersion</code>. The <code class="docutils literal notranslate">verlib</code> module presented in this PEP will be renamed to <code class="docutils literal notranslate">version</code> and placed into the <code class="docutils literal notranslate">distutils</code> package. </section> <section id="references"> <h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="id10" role="doc-footnote"> <dt class="label" id="id10">[<a href="#id1">1</a>]</dt> <dd><a class="reference external" href="https://docs.python.org/3.11/distutils/">https://docs.python.org/3.11/distutils/</a></aside> <aside class="footnote brackets" id="id11" role="doc-footnote"> <dt class="label" id="id11">[<a href="#id2">2</a>]</dt> <dd><a class="reference external" href="https://peak.telecommunity.com/DevCenter/setuptools">https://peak.telecommunity.com/DevCenter/setuptools</a></aside> <aside class="footnote brackets" id="setuptools-version" role="doc-footnote"> <dt class="label" id="setuptools-version">[<a href="#id3">3</a>]</dt> <dd><a class="reference external" href="https://peak.telecommunity.com/DevCenter/setuptools#specifying-your-project-s-version">https://peak.telecommunity.com/DevCenter/setuptools#specifying-your-project-s-version</a></aside> <aside class="footnote brackets" id="pypi" role="doc-footnote"> <dt class="label" id="pypi">[<a href="#id4">4</a>]</dt> <dd><a class="reference external" href="https://pypi.org/">https://pypi.org/</a></aside> <aside class="footnote brackets" id="pip" role="doc-footnote"> <dt class="label" id="pip">[<a href="#id6">5</a>]</dt> <dd><a class="reference external" href="https://pypi.org/project/pip/">https://pypi.org/project/pip/</a></aside> <aside class="footnote brackets" id="ezinstall" role="doc-footnote"> <dt class="label" id="ezinstall">[<a href="#id5">6</a>]</dt> <dd><a class="reference external" href="https://peak.telecommunity.com/DevCenter/EasyInstall">https://peak.telecommunity.com/DevCenter/EasyInstall</a></aside> <aside class="footnote brackets" id="zc-buildout" role="doc-footnote"> <dt class="label" id="zc-buildout">[<a href="#id7">7</a>]</dt> <dd><a class="reference external" href="https://pypi.org/project/zc.buildout/">https://pypi.org/project/zc.buildout/</a></aside> <aside class="footnote brackets" id="twisted" role="doc-footnote"> <dt class="label" id="twisted">[<a href="#id9">8</a>]</dt> <dd><a class="reference external" href="https://twisted.org/">https://twisted.org/</a></aside> <aside class="footnote brackets" id="prototype" role="doc-footnote"> <dt class="label" id="prototype">[<a href="#id8">9</a>]</dt> <dd><a class="reference external" href="https://web.archive.org/web/20090726093825/http://bitbucket.org/tarek/distutilsversion/">https://web.archive.org/web/20090726093825/http://bitbucket.org/tarek/distutilsversion/</a></aside> </aside> </section> <section id="acknowledgments"> <h2><a class="toc-backref" href="#acknowledgments" role="doc-backlink">Acknowledgments</a></h2> Trent Mick, Matthias Klose, Phillip Eby, David Lyon, and many people at Pycon and Distutils-SIG. </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document has been placed in the public domain. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0386.rst">https://github.com/python/peps/blob/main/peps/pep-0386.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0386.rst">2024-12-15 20:57:19 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#motivation">Motivation</a></li> <li><a class="reference internal" href="#requisites-and-current-status">Requisites and current status</a><ul> <li><a class="reference internal" href="#distutils">Distutils</a></li> <li><a class="reference internal" href="#setuptools">Setuptools</a></li> <li><a class="reference internal" href="#caveats-of-existing-systems">Caveats of existing systems</a></li> </ul> </li> <li><a class="reference internal" href="#the-new-versioning-algorithm">The new versioning algorithm</a><ul> <li><a class="reference internal" href="#normalizedversion">NormalizedVersion</a></li> <li><a class="reference internal" href="#suggest-normalized-version">suggest_normalized_version</a></li> </ul> </li> <li><a class="reference internal" href="#roadmap">Roadmap</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#acknowledgments">Acknowledgments</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0386.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>