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 508 – Dependency specification for Python Software Packages | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0508/"> <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 508 – Dependency specification for Python Software Packages | peps.python.org'> <meta property="og:description" content="This PEP specifies the language used to describe dependencies for packages. It draws a border at the edge of describing a single dependency - the different sorts of dependencies and when they should be installed is a higher level problem. The intent is ..."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0508/"> <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="This PEP specifies the language used to describe dependencies for packages. It draws a border at the edge of describing a single dependency - the different sorts of dependencies and when they should be installed is a higher level problem. The intent is ..."> <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 508</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 508 – Dependency specification for Python Software Packages</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Robert Collins <rbtcollins at hp.com></dd> <dt class="field-even">BDFL-Delegate:</dt> <dd class="field-even">Donald Stufft <donald at stufft.io></dd> <dt class="field-odd">Discussions-To:</dt> <dd class="field-odd"><a class="reference external" href="https://mail.python.org/archives/list/distutils-sig@python.org/">Distutils-SIG list</a></dd> <dt class="field-even">Status:</dt> <dd class="field-even"><abbr title="Accepted and implementation complete, or no longer active">Final</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">11-Nov-2015</dd> <dt class="field-even">Post-History:</dt> <dd class="field-even">05-Nov-2015, 16-Nov-2015</dd> <dt class="field-odd">Resolution:</dt> <dd class="field-odd"><a class="reference external" href="https://mail.python.org/pipermail/distutils-sig/2015-November/027868.html">Distutils-SIG message</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="#specification">Specification</a><ul> <li><a class="reference internal" href="#examples">Examples</a></li> <li><a class="reference internal" href="#concepts">Concepts</a></li> <li><a class="reference internal" href="#grammar">Grammar</a></li> <li><a class="reference internal" href="#whitespace">Whitespace</a></li> <li><a class="reference internal" href="#names">Names</a></li> <li><a class="reference internal" href="#extras">Extras</a></li> <li><a class="reference internal" href="#versions">Versions</a></li> <li><a class="reference internal" href="#environment-markers">Environment Markers</a></li> </ul> </li> <li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#complete-grammar">Complete Grammar</a></li> <li><a class="reference internal" href="#summary-of-changes-to-pep-508">Summary of changes to PEP 508</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <div class="pep-banner canonical-pypa-spec sticky-banner admonition important"> Important This PEP is a historical document. The up-to-date, canonical spec, <a class="reference external" href="https://packaging.python.org/en/latest/specifications/dependency-specifiers/#dependency-specifiers" title="(in Python Packaging User Guide)">Dependency specifiers</a>, is maintained on the <a class="reference external" href="https://packaging.python.org/en/latest/specifications/">PyPA specs page</a>. × See the <a class="reference external" href="https://www.pypa.io/en/latest/specifications/#handling-fixes-and-other-minor-updates">PyPA specification update process</a> for how to propose changes. </div> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> This PEP specifies the language used to describe dependencies for packages. It draws a border at the edge of describing a single dependency - the different sorts of dependencies and when they should be installed is a higher level problem. The intent is to provide a building block for higher layer specifications. The job of a dependency is to enable tools like pip <a class="footnote-reference brackets" href="#pip" id="id1">[1]</a> to find the right package to install. Sometimes this is very loose - just specifying a name, and sometimes very specific - referring to a specific file to install. Sometimes dependencies are only relevant in one platform, or only some versions are acceptable, so the language permits describing all these cases. The language defined is a compact line based format which is already in widespread use in pip requirements files, though we do not specify the command line option handling that those files permit. There is one caveat - the URL reference form, specified in <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a> is not actually implemented in pip, but since <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a> is accepted, we use that format rather than pip’s current native format. </section> <section id="motivation"> <h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2> Any specification in the Python packaging ecosystem that needs to consume lists of dependencies needs to build on an approved PEP for such, but <a class="pep reference internal" href="../pep-0426/" title="PEP 426 – Metadata for Python Software Packages 2.0">PEP 426</a> is mostly aspirational - and there are already existing implementations of the dependency specification which we can instead adopt. The existing implementations are battle proven and user friendly, so adopting them is arguably much better than approving an aspirational, unconsumed, format. </section> <section id="specification"> <h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2> <section id="examples"> <h3><a class="toc-backref" href="#examples" role="doc-backlink">Examples</a></h3> All features of the language shown with a name based lookup: <div class="highlight-default notranslate"><div class="highlight"><pre>requests [security,tests] >= 2.8.1, == 2.8.* ; python_version < "2.7" </pre></div> </div> A minimal URL based lookup: <div class="highlight-default notranslate"><div class="highlight"><pre>pip @ https://github.com/pypa/pip/archive/1.3.1.zip#sha1=da9234ee9982d4bbb3c72346a6de940a148ea686 </pre></div> </div> </section> <section id="concepts"> <h3><a class="toc-backref" href="#concepts" role="doc-backlink">Concepts</a></h3> A dependency specification always specifies a distribution name. It may include extras, which expand the dependencies of the named distribution to enable optional features. The version installed can be controlled using version limits, or giving the URL to a specific artifact to install. Finally the dependency can be made conditional using environment markers. </section> <section id="grammar"> <h3><a class="toc-backref" href="#grammar" role="doc-backlink">Grammar</a></h3> We first cover the grammar briefly and then drill into the semantics of each section later. A distribution specification is written in ASCII text. We use a parsley <a class="footnote-reference brackets" href="#parsley" id="id2">[2]</a> grammar to provide a precise grammar. It is expected that the specification will be embedded into a larger system which offers framing such as comments, multiple line support via continuations, or other such features. The full grammar including annotations to build a useful parse tree is included at the end of the PEP. Versions may be specified according to the <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a> rules. (Note: URI is defined in <a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc3986.html">std-66</a>): <div class="highlight-default notranslate"><div class="highlight"><pre>version_cmp = wsp* '<' | '<=' | '!=' | '==' | '>=' | '>' | '~=' | '===' version = wsp* ( letterOrDigit | '-' | '_' | '.' | '*' | '+' | '!' )+ version_one = version_cmp version wsp* version_many = version_one (wsp* ',' version_one)* versionspec = ( '(' version_many ')' ) | version_many urlspec = '@' wsp* <URI_reference> </pre></div> </div> Environment markers allow making a specification only take effect in some environments: <div class="highlight-default notranslate"><div class="highlight"><pre>marker_op = version_cmp | (wsp* 'in') | (wsp* 'not' wsp+ 'in') python_str_c = (wsp | letter | digit | '(' | ')' | '.' | '{' | '}' | '-' | '_' | '*' | '#' | ':' | ';' | ',' | '/' | '?' | '[' | ']' | '!' | '~' | '`' | '@' | '$' | '%' | '^' | '&' | '=' | '+' | '|' | '<' | '>' ) dquote = '"' squote = '\\'' python_str = (squote (python_str_c | dquote)* squote | dquote (python_str_c | squote)* dquote) env_var = ('python_version' | 'python_full_version' | 'os_name' | 'sys_platform' | 'platform_release' | 'platform_system' | 'platform_version' | 'platform_machine' | 'platform_python_implementation' | 'implementation_name' | 'implementation_version' | 'extra' # ONLY when defined by a containing layer ) marker_var = wsp* (env_var | python_str) marker_expr = marker_var marker_op marker_var | wsp* '(' marker wsp* ')' marker_and = marker_expr wsp* 'and' marker_expr | marker_expr marker_or = marker_and wsp* 'or' marker_and | marker_and marker = marker_or quoted_marker = ';' wsp* marker </pre></div> </div> Optional components of a distribution may be specified using the extras field: <div class="highlight-default notranslate"><div class="highlight"><pre>identifier_end = letterOrDigit | (('-' | '_' | '.' )* letterOrDigit) identifier = letterOrDigit identifier_end* name = identifier extras_list = identifier (wsp* ',' wsp* identifier)* extras = '[' wsp* extras_list? wsp* ']' </pre></div> </div> Giving us a rule for name based requirements: <div class="highlight-default notranslate"><div class="highlight"><pre>name_req = name wsp* extras? wsp* versionspec? wsp* quoted_marker? </pre></div> </div> And a rule for direct reference specifications: <div class="highlight-default notranslate"><div class="highlight"><pre>url_req = name wsp* extras? wsp* urlspec wsp+ quoted_marker? </pre></div> </div> Leading to the unified rule that can specify a dependency.: <div class="highlight-default notranslate"><div class="highlight"><pre>specification = wsp* ( url_req | name_req ) wsp* </pre></div> </div> </section> <section id="whitespace"> <h3><a class="toc-backref" href="#whitespace" role="doc-backlink">Whitespace</a></h3> Non line-breaking whitespace is mostly optional with no semantic meaning. The sole exception is detecting the end of a URL requirement. </section> <section id="names"> <h3><a class="toc-backref" href="#names" role="doc-backlink">Names</a></h3> Python distribution names are currently defined in <a class="pep reference internal" href="../pep-0345/" title="PEP 345 – Metadata for Python Software Packages 1.2">PEP 345</a>. Names act as the primary identifier for distributions. They are present in all dependency specifications, and are sufficient to be a specification on their own. However, PyPI places strict restrictions on names - they must match a case insensitive regex or they won’t be accepted. Accordingly, in this PEP we limit the acceptable values for identifiers to that regex. A full redefinition of name may take place in a future metadata PEP. The regex (run with re.IGNORECASE) is: <div class="highlight-default notranslate"><div class="highlight"><pre>^([A-Z0-9]|[A-Z0-9][A-Z0-9._-]*[A-Z0-9])$ </pre></div> </div> </section> <section id="extras"> <h3><a class="toc-backref" href="#extras" role="doc-backlink">Extras</a></h3> An extra is an optional part of a distribution. Distributions can specify as many extras as they wish, and each extra results in the declaration of additional dependencies of the distribution when the extra is used in a dependency specification. For instance: <div class="highlight-default notranslate"><div class="highlight"><pre>requests[security] </pre></div> </div> Extras union in the dependencies they define with the dependencies of the distribution they are attached to. The example above would result in requests being installed, and requests own dependencies, and also any dependencies that are listed in the “security” extra of requests. If multiple extras are listed, all the dependencies are unioned together. </section> <section id="versions"> <h3><a class="toc-backref" href="#versions" role="doc-backlink">Versions</a></h3> See <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a> for more detail on both version numbers and version comparisons. Version specifications limit the versions of a distribution that can be used. They only apply to distributions looked up by name, rather than via a URL. Version comparison are also used in the markers feature. The optional brackets around a version are present for compatibility with <a class="pep reference internal" href="../pep-0345/" title="PEP 345 – Metadata for Python Software Packages 1.2">PEP 345</a> but should not be generated, only accepted. </section> <section id="environment-markers"> <h3><a class="toc-backref" href="#environment-markers" role="doc-backlink">Environment Markers</a></h3> Environment markers allow a dependency specification to provide a rule that describes when the dependency should be used. For instance, consider a package that needs argparse. In Python 2.7 argparse is always present. On older Python versions it has to be installed as a dependency. This can be expressed as so: <div class="highlight-default notranslate"><div class="highlight"><pre>argparse;python_version<"2.7" </pre></div> </div> A marker expression evaluates to either True or False. When it evaluates to False, the dependency specification should be ignored. The marker language is inspired by Python itself, chosen for the ability to safely evaluate it without running arbitrary code that could become a security vulnerability. Markers were first standardised in <a class="pep reference internal" href="../pep-0345/" title="PEP 345 – Metadata for Python Software Packages 1.2">PEP 345</a>. This PEP fixes some issues that were observed in the design described in <a class="pep reference internal" href="../pep-0426/" title="PEP 426 – Metadata for Python Software Packages 2.0">PEP 426</a>. Comparisons in marker expressions are typed by the comparison operator. The <marker_op> operators that are not in <version_cmp> perform the same as they do for strings in Python. The <version_cmp> operators use the <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a> version comparison rules when those are defined (that is when both sides have a valid version specifier). If there is no defined <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a> behaviour and the operator exists in Python, then the operator falls back to the Python behaviour. Otherwise an error should be raised. e.g. the following will result in errors: <div class="highlight-default notranslate"><div class="highlight"><pre>"dog" ~= "fred" python_version ~= "surprise" </pre></div> </div> User supplied constants are always encoded as strings with either <code class="docutils literal notranslate">'</code> or <code class="docutils literal notranslate">"</code> quote marks. Note that backslash escapes are not defined, but existing implementations do support them. They are not included in this specification because they add complexity and there is no observable need for them today. Similarly we do not define non-ASCII character support: all the runtime variables we are referencing are expected to be ASCII-only. The variables in the marker grammar such as “os_name” resolve to values looked up in the Python runtime. With the exception of “extra” all values are defined on all Python versions today - it is an error in the implementation of markers if a value is not defined. Unknown variables must raise an error rather than resulting in a comparison that evaluates to True or False. Variables whose value cannot be calculated on a given Python implementation should evaluate to <code class="docutils literal notranslate">0</code> for versions, and an empty string for all other variables. The “extra” variable is special. It is used by wheels to signal which specifications apply to a given extra in the wheel <code class="docutils literal notranslate">METADATA</code> file, but since the <code class="docutils literal notranslate">METADATA</code> file is based on a draft version of <a class="pep reference internal" href="../pep-0426/" title="PEP 426 – Metadata for Python Software Packages 2.0">PEP 426</a>, there is no current specification for this. Regardless, outside of a context where this special handling is taking place, the “extra” variable should result in an error like all other unknown variables. <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head">Marker</th> <th class="head">Python equivalent</th> <th class="head">Sample values</th> </tr> </thead> <tbody> <tr class="row-even"><td><code class="docutils literal notranslate">os_name</code></td> <td><code class="docutils literal notranslate">os.name</code></td> <td><code class="docutils literal notranslate">posix</code>, <code class="docutils literal notranslate">java</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">sys_platform</code></td> <td><code class="docutils literal notranslate">sys.platform</code></td> <td><code class="docutils literal notranslate">linux</code>, <code class="docutils literal notranslate">linux2</code>, <code class="docutils literal notranslate">darwin</code>, <code class="docutils literal notranslate">java1.8.0_51</code> (note that “linux” is from Python3 and “linux2” from Python2)</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">platform_machine</code></td> <td><code class="docutils literal notranslate">platform.machine()</code></td> <td><code class="docutils literal notranslate">x86_64</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">platform_python_implementation</code></td> <td><code class="docutils literal notranslate">platform.python_implementation()</code></td> <td><code class="docutils literal notranslate">CPython</code>, <code class="docutils literal notranslate">Jython</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">platform_release</code></td> <td><code class="docutils literal notranslate">platform.release()</code></td> <td><code class="docutils literal notranslate">3.14.1-x86_64-linode39</code>, <code class="docutils literal notranslate">14.5.0</code>, <code class="docutils literal notranslate">1.8.0_51</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">platform_system</code></td> <td><code class="docutils literal notranslate">platform.system()</code></td> <td><code class="docutils literal notranslate">Linux</code>, <code class="docutils literal notranslate">Windows</code>, <code class="docutils literal notranslate">Java</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">platform_version</code></td> <td><code class="docutils literal notranslate">platform.version()</code></td> <td><code class="docutils literal notranslate">#1 SMP Fri Apr 25 13:07:35 EDT 2014</code> <code class="docutils literal notranslate">Java HotSpot(TM) 64-Bit Server VM, 25.51-b03, Oracle Corporation</code> <code class="docutils literal notranslate">Darwin Kernel Version 14.5.0: Wed Jul 29 02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">python_version</code></td> <td><code class="docutils literal notranslate">'.'.join(platform.python_version_tuple()[:2])</code></td> <td><code class="docutils literal notranslate">3.4</code>, <code class="docutils literal notranslate">2.7</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">python_full_version</code></td> <td><code class="docutils literal notranslate">platform.python_version()</code></td> <td><code class="docutils literal notranslate">3.4.0</code>, <code class="docutils literal notranslate">3.5.0b1</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">implementation_name</code></td> <td><code class="docutils literal notranslate">sys.implementation.name</code></td> <td><code class="docutils literal notranslate">cpython</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">implementation_version</code></td> <td>see definition below</td> <td><code class="docutils literal notranslate">3.4.0</code>, <code class="docutils literal notranslate">3.5.0b1</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">extra</code></td> <td>An error except when defined by the context interpreting the specification.</td> <td><code class="docutils literal notranslate">test</code></td> </tr> </tbody> </table> The <code class="docutils literal notranslate">implementation_version</code> marker variable is derived from <code class="docutils literal notranslate">sys.implementation.version</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>def format_full_version(info): version = '{0.major}.{0.minor}.{0.micro}'.format(info) kind = info.releaselevel if kind != 'final': version += kind[0] + str(info.serial) return version if hasattr(sys, 'implementation'): implementation_version = format_full_version(sys.implementation.version) else: implementation_version = "0" </pre></div> </div> </section> </section> <section id="backwards-compatibility"> <h2><a class="toc-backref" href="#backwards-compatibility" role="doc-backlink">Backwards Compatibility</a></h2> Most of this PEP is already widely deployed and thus offers no compatibility concerns. There are however a few points where the PEP differs from the deployed base. Firstly, <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a> direct references haven’t actually been deployed in the wild, but they were designed to be compatibly added, and there are no known obstacles to adding them to pip or other tools that consume the existing dependency metadata in distributions - particularly since they won’t be permitted to be present in PyPI uploaded distributions anyway. Secondly, <a class="pep reference internal" href="../pep-0426/" title="PEP 426 – Metadata for Python Software Packages 2.0">PEP 426</a> markers which have had some reasonable deployment, particularly in wheels and pip, will handle version comparisons with <code class="docutils literal notranslate">python_full_version</code> “2.7.10” differently. Specifically in 426 “2.7.10” is less than “2.7.9”. This backward incompatibility is deliberate. We are also defining new operators - “~=” and “===”, and new variables - <code class="docutils literal notranslate">platform_release</code>, <code class="docutils literal notranslate">platform_system</code>, <code class="docutils literal notranslate">implementation_name</code>, and <code class="docutils literal notranslate">implementation_version</code> which are not present in older marker implementations. The variables will error on those implementations. Users of both features will need to make a judgement as to when support has become sufficiently widespread in the ecosystem that using them will not cause compatibility issues. Thirdly, <a class="pep reference internal" href="../pep-0345/" title="PEP 345 – Metadata for Python Software Packages 1.2">PEP 345</a> required brackets around version specifiers. In order to accept <a class="pep reference internal" href="../pep-0345/" title="PEP 345 – Metadata for Python Software Packages 1.2">PEP 345</a> dependency specifications, brackets are accepted, but they should not be generated. </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> In order to move forward with any new PEPs that depend on environment markers, we needed a specification that included them in their modern form. This PEP brings together all the currently unspecified components into a specified form. The requirement specifier was adopted from the EBNF in the setuptools pkg_resources documentation, since we wish to avoid depending on a de facto, vs PEP specified, standard. </section> <section id="complete-grammar"> <h2><a class="toc-backref" href="#complete-grammar" role="doc-backlink">Complete Grammar</a></h2> The complete parsley grammar: <div class="highlight-default notranslate"><div class="highlight"><pre>wsp = ' ' | '\t' version_cmp = wsp* <'<=' | '<' | '!=' | '==' | '>=' | '>' | '~=' | '==='> version = wsp* <( letterOrDigit | '-' | '_' | '.' | '*' | '+' | '!' )+> version_one = version_cmp:op version:v wsp* -> (op, v) version_many = version_one:v1 (wsp* ',' version_one)*:v2 -> [v1] + v2 versionspec = ('(' version_many:v ')' ->v) | version_many urlspec = '@' wsp* <URI_reference> marker_op = version_cmp | (wsp* 'in') | (wsp* 'not' wsp+ 'in') python_str_c = (wsp | letter | digit | '(' | ')' | '.' | '{' | '}' | '-' | '_' | '*' | '#' | ':' | ';' | ',' | '/' | '?' | '[' | ']' | '!' | '~' | '`' | '@' | '$' | '%' | '^' | '&' | '=' | '+' | '|' | '<' | '>' ) dquote = '"' squote = '\\'' python_str = (squote <(python_str_c | dquote)*>:s squote | dquote <(python_str_c | squote)*>:s dquote) -> s env_var = ('python_version' | 'python_full_version' | 'os_name' | 'sys_platform' | 'platform_release' | 'platform_system' | 'platform_version' | 'platform_machine' | 'platform_python_implementation' | 'implementation_name' | 'implementation_version' | 'extra' # ONLY when defined by a containing layer ):varname -> lookup(varname) marker_var = wsp* (env_var | python_str) marker_expr = marker_var:l marker_op:o marker_var:r -> (o, l, r) | wsp* '(' marker:m wsp* ')' -> m marker_and = marker_expr:l wsp* 'and' marker_expr:r -> ('and', l, r) | marker_expr:m -> m marker_or = marker_and:l wsp* 'or' marker_and:r -> ('or', l, r) | marker_and:m -> m marker = marker_or quoted_marker = ';' wsp* marker identifier_end = letterOrDigit | (('-' | '_' | '.' )* letterOrDigit) identifier = < letterOrDigit identifier_end* > name = identifier extras_list = identifier:i (wsp* ',' wsp* identifier)*:ids -> [i] + ids extras = '[' wsp* extras_list?:e wsp* ']' -> e name_req = (name:n wsp* extras?:e wsp* versionspec?:v wsp* quoted_marker?:m -> (n, e or [], v or [], m)) url_req = (name:n wsp* extras?:e wsp* urlspec:v (wsp+ | end) quoted_marker?:m -> (n, e or [], v, m)) specification = wsp* ( url_req | name_req ):s wsp* -> s # The result is a tuple - name, list-of-extras, # list-of-version-constraints-or-a-url, marker-ast or None URI_reference = <URI | relative_ref> URI = scheme ':' hier_part ('?' query )? ( '#' fragment)? hier_part = ('//' authority path_abempty) | path_absolute | path_rootless | path_empty absolute_URI = scheme ':' hier_part ( '?' query )? relative_ref = relative_part ( '?' query )? ( '#' fragment )? relative_part = '//' authority path_abempty | path_absolute | path_noscheme | path_empty scheme = letter ( letter | digit | '+' | '-' | '.')* authority = ( userinfo '@' )? host ( ':' port )? userinfo = ( unreserved | pct_encoded | sub_delims | ':')* host = IP_literal | IPv4address | reg_name port = digit* IP_literal = '[' ( IPv6address | IPvFuture) ']' IPvFuture = 'v' hexdig+ '.' ( unreserved | sub_delims | ':')+ IPv6address = ( ( h16 ':'){6} ls32 | '::' ( h16 ':'){5} ls32 | ( h16 )? '::' ( h16 ':'){4} ls32 | ( ( h16 ':')? h16 )? '::' ( h16 ':'){3} ls32 | ( ( h16 ':'){0,2} h16 )? '::' ( h16 ':'){2} ls32 | ( ( h16 ':'){0,3} h16 )? '::' h16 ':' ls32 | ( ( h16 ':'){0,4} h16 )? '::' ls32 | ( ( h16 ':'){0,5} h16 )? '::' h16 | ( ( h16 ':'){0,6} h16 )? '::' ) h16 = hexdig{1,4} ls32 = ( h16 ':' h16) | IPv4address IPv4address = dec_octet '.' dec_octet '.' dec_octet '.' dec_octet nz = ~'0' digit dec_octet = ( digit # 0-9 | nz digit # 10-99 | '1' digit{2} # 100-199 | '2' ('0' | '1' | '2' | '3' | '4') digit # 200-249 | '25' ('0' | '1' | '2' | '3' | '4' | '5') )# %250-255 reg_name = ( unreserved | pct_encoded | sub_delims)* path = ( path_abempty # begins with '/' or is empty | path_absolute # begins with '/' but not '//' | path_noscheme # begins with a non-colon segment | path_rootless # begins with a segment | path_empty ) # zero characters path_abempty = ( '/' segment)* path_absolute = '/' ( segment_nz ( '/' segment)* )? path_noscheme = segment_nz_nc ( '/' segment)* path_rootless = segment_nz ( '/' segment)* path_empty = pchar{0} segment = pchar* segment_nz = pchar+ segment_nz_nc = ( unreserved | pct_encoded | sub_delims | '@')+ # non-zero-length segment without any colon ':' pchar = unreserved | pct_encoded | sub_delims | ':' | '@' query = ( pchar | '/' | '?')* fragment = ( pchar | '/' | '?')* pct_encoded = '%' hexdig unreserved = letter | digit | '-' | '.' | '_' | '~' reserved = gen_delims | sub_delims gen_delims = ':' | '/' | '?' | '#' | '(' | ')?' | '@' sub_delims = '!' | '$' | '&' | '\\'' | '(' | ')' | '*' | '+' | ',' | ';' | '=' hexdig = digit | 'a' | 'A' | 'b' | 'B' | 'c' | 'C' | 'd' | 'D' | 'e' | 'E' | 'f' | 'F' </pre></div> </div> A test program - if the grammar is in a string <code class="docutils literal notranslate">grammar</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>import os import sys import platform from parsley import makeGrammar grammar = """ wsp ... """ tests = [ "A", "A.B-C_D", "aa", "name", "name<=1", "name>=3", "name>=3,<2", "name@http://foo.com", "name [fred,bar] @ http://foo.com ; python_version=='2.7'", "name[quux, strange];python_version<'2.7' and platform_version=='2'", "name; os_name=='a' or os_name=='b'", # Should parse as (a and b) or c "name; os_name=='a' and os_name=='b' or os_name=='c'", # Overriding precedence -> a and (b or c) "name; os_name=='a' and (os_name=='b' or os_name=='c')", # should parse as a or (b and c) "name; os_name=='a' or os_name=='b' and os_name=='c'", # Overriding precedence -> (a or b) and c "name; (os_name=='a' or os_name=='b') and os_name=='c'", ] def format_full_version(info): version = '{0.major}.{0.minor}.{0.micro}'.format(info) kind = info.releaselevel if kind != 'final': version += kind[0] + str(info.serial) return version if hasattr(sys, 'implementation'): implementation_version = format_full_version(sys.implementation.version) implementation_name = sys.implementation.name else: implementation_version = '0' implementation_name = '' bindings = { 'implementation_name': implementation_name, 'implementation_version': implementation_version, 'os_name': os.name, 'platform_machine': platform.machine(), 'platform_python_implementation': platform.python_implementation(), 'platform_release': platform.release(), 'platform_system': platform.system(), 'platform_version': platform.version(), 'python_full_version': platform.python_version(), 'python_version': '.'.join(platform.python_version_tuple()[:2]), 'sys_platform': sys.platform, } compiled = makeGrammar(grammar, {'lookup': bindings.__getitem__}) for test in tests: parsed = compiled(test).specification() print("%s -> %s" % (test, parsed)) </pre></div> </div> </section> <section id="summary-of-changes-to-pep-508"> <h2><a class="toc-backref" href="#summary-of-changes-to-pep-508" role="doc-backlink">Summary of changes to PEP 508</a></h2> The following changes were made to this PEP based on feedback after its initial implementation: <ul class="simple"> <li>The definition of <code class="docutils literal notranslate">python_version</code> was changed from <code class="docutils literal notranslate">platform.python_version()[:3]</code> to <code class="docutils literal notranslate">'.'.join(platform.python_version_tuple()[:2])</code>, to accommodate potential future versions of Python with 2-digit major and minor versions (e.g. 3.10). <a class="footnote-reference brackets" href="#future-versions" id="id3">[3]</a></li> </ul> </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="pip" role="doc-footnote"> <dt class="label" id="pip">[<a href="#id1">1</a>]</dt> <dd>pip, the recommended installer for Python packages (<a class="reference external" href="http://pip.readthedocs.org/en/stable/">http://pip.readthedocs.org/en/stable/</a>)</aside> <aside class="footnote brackets" id="parsley" role="doc-footnote"> <dt class="label" id="parsley">[<a href="#id2">2</a>]</dt> <dd>The parsley PEG library. (<a class="reference external" href="https://pypi.python.org/pypi/parsley/">https://pypi.python.org/pypi/parsley/</a>)</aside> <aside class="footnote brackets" id="future-versions" role="doc-footnote"> <dt class="label" id="future-versions">[<a href="#id3">3</a>]</dt> <dd>Future Python versions might be problematic with the definition of Environment Marker Variable <code class="docutils literal notranslate">python_version</code> (<a class="reference external" href="https://github.com/python/peps/issues/560">https://github.com/python/peps/issues/560</a>)</aside> </aside> </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-0508.rst">https://github.com/python/peps/blob/main/peps/pep-0508.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0508.rst">2025-02-20 11:58:35 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="#specification">Specification</a><ul> <li><a class="reference internal" href="#examples">Examples</a></li> <li><a class="reference internal" href="#concepts">Concepts</a></li> <li><a class="reference internal" href="#grammar">Grammar</a></li> <li><a class="reference internal" href="#whitespace">Whitespace</a></li> <li><a class="reference internal" href="#names">Names</a></li> <li><a class="reference internal" href="#extras">Extras</a></li> <li><a class="reference internal" href="#versions">Versions</a></li> <li><a class="reference internal" href="#environment-markers">Environment Markers</a></li> </ul> </li> <li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#complete-grammar">Complete Grammar</a></li> <li><a class="reference internal" href="#summary-of-changes-to-pep-508">Summary of changes to PEP 508</a></li> <li><a class="reference internal" href="#references">References</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-0508.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>