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 [1] 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 PEP-440 [4] is not actually
implemented in pip, but since PEP-440 is accepted, we use that format rather
than pip's current native format.

Any specification in the Python packaging ecosystem that needs to consume
lists of dependencies needs to build on an approved PEP for such, but
PEP-426 [3] 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.

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.

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
[6] 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 PEP-440 [4] rules. (Note:
URI is defined in std-66 [5]:

Python distribution names are currently defined in PEP-345 [2]. 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:

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:

requests[security]

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.

See PEP-440 [4] 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 PEP-345
[2] but should not be generated, only accepted.

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:

argparse;python_version<"2.7"

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 PEP-345 [2]. This PEP
fixes some issues that were observed in the design described in PEP-426
[3].

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 PEP-440
[4] version comparison rules when those are defined (that is when both
sides have a valid version specifier). If there is no defined PEP-440
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:

"dog" ~= "fred"
python_version ~= "surprise"

User supplied constants are always encoded as strings with either ' or
" 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 0 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 METADATA file, but
since the METADATA file is based on a draft version of PEP-426, 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.

Marker

Python equivalent

Sample values

os_name

os.name

posix, java

sys_platform

sys.platform

linux, linux2, darwin, java1.8.0_51 (note that "linux"
is from Python3 and "linux2" from Python2)

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, PEP-440 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, PEP-426 markers which have had some reasonable deployment,
particularly in wheels and pip, will handle version comparisons with
python_version "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 -
platform_release, platform_system, implementation_name, and
implementation_version 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, PEP-345 required brackets around version specifiers. In order to
accept PEP-345 dependency specifications, brackets are accepted, but they
should not be generated.

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.