Here is the full diff vs the last push to github.
diff --git a/dependency-specification.rst b/dependency-specification.rst index 6f85b98..03f2a0d 100644 --- a/dependency-specification.rst +++ b/dependency-specification.rst @@ -52,10 +52,7 @@ Examples
All features of the language shown with a name based lookup::
requests [security,tests] >= 2.8.1, == 2.8.* ; python_version < "2.7.10"
A minimal URL based lookup::
@@ -77,29 +74,25 @@ 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 ABNF [#abnf]_ to -provide a precise grammar. Specifications may have comments starting with a
-Specifications may be spread across multiple lines if desired using
CSP = 1*(WSP / ("\" LF)) +provide a precise grammar. The grammar covers just the specification itself. +The expectation is 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.
Versions may be specified according to the PEP-440 [#pep440]_ rules. (Note: URI is defined in std-66 [#std66]_::
version-cmp = "<" / "<=" / "!=" / "==" / ">=" / ">" / "~=" / "===" version = 1( DIGIT / ALPHA / "-" / "_" / "." / "" )
versionspec = ("(" version-inner ")") / version-inner urlspec = "@" URI
Environment markers allow making a specification only take effect in some environments::
marker-op = version-cmp / "in" / "not in"
python-str = "'" (python-str-c / DQUOTE) "'" python-str =/ DQUOTE (python-str-c / "'") DQUOTE @@ -109,10 +102,12 @@ environments::
"-" / "_" / "*"
"platform_python_implementation" / "implementation_name" / "implementation_version" / "platform_dist_name" "platform_dist_version" / "platform_dist_id"
url-marker = ";" 1*WSP marker
Optional components of a distribution may be specified using the extras field:: @@ -123,31 +118,21 @@ field::
Giving us a rule for name based requirements::
name_req = name [CSP extras] [CSP versionspec] [CSP name-marker]
name_req = name [WSP extras] [WSP versionspec] [*WSP name-marker]
And a rule for direct reference specifications::
url_req = name [CSP extras] urlspec [CSP url-marker]
url_req = name [WSP extras] urlspec [WSP url-marker]
Leading to the unified rule that can specify a dependency::
specification = (name_req / location_req) [CSP comment]
specification = name_req / location_req
Non line-breaking whitespace is optional and has no semantic meaning.
-A line break indicates the end of a specification. Specifications can be
- -A specification can have a comment added to it by starting the comment with a -"#". After a "#" the rest of the line can contain any text whatsoever.
@@ -209,42 +194,45 @@ either side is not a valid version, then the comparsion falls back to the same behaviour as in for string in Python if the operator exists in Python. For those operators which are not defined in Python, the result should be False.
-The variables in the marker grammar such as "os_name" resolve to values looked
-up in the Python runtime. If a particular value is not available (such as
sys.implementation.name in versions of Python prior to 3.3, or
platform.dist() on non-Linux systems), the default value will be used.
+User supplied constants are always encoded as strings with either
" quote marks. Note that backslash escapes are not defined, but existing
+implementations do support them them. They are not included in this
+specification because none of the variables to which constants can be compared
+contain quote-requiring values.
+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 a SyntaxError rather than resulting in a
+comparison that evaluates to True or False.
+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
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 a
+SyntaxError like all other unknown variables.
* - Marker - Python equivalent - Sample values
#1 SMP Fri Apr 25 13:07:35 EDT 2014
@@ -252,51 +240,16 @@ up in the Python runtime. If a particular value
is not available (such as
Java HotSpot(TM) 64-Bit Server VM, 25.51-b03, Oracle Corporation
Darwin Kernel Version 14.5.0: Wed Jul 29 02:18:53 PDT 2015;
implementation_versionmarker variables -are derived from
python_full_versionwill typically correspond to
sys.implementation.versionin versions of Python prior to 3.3) the -corresponding marker variable returned by setuptools will be set to