Commits

Daniel Holth committed 537e83b Draft

add Provides-Extra, Setup-Requires-Dist

  • Participants
  • Parent commits a071af7

Comments (0)

Files changed (1)

 Version 1.1 is specified in PEP 314.
 
 Version 1.2 of the metadata format adds a number of optional fields
-designed to make third-party packaging of Python Software easier.
-These fields are "Requires-Python", "Requires-External", "Requires-Dist",
-"Provides-Dist", and "Obsoletes-Dist".  This version also changes the
-"Platform" field. Three new fields were also added: "Maintainer",
-"Maintainer-email" and "Project-URL".
+designed to make third-party packaging of Python Software easier.  These
+fields are "Requires-Python", "Requires-External", "Requires-Dist",
+"Setup-Requires-Dist", "Provides-Dist", "Provides-Extra", and
+"Obsoletes-Dist".  This version also changes the "Platform" field. Three
+new fields were also added: "Maintainer", "Maintainer-email" and
+"Project-URL".
 
 Last, this new version also adds `environment markers`.
 
     Requires-Dist: zope.interface (>3.5.0)
 
 
+Setup-Requires-Dist (multiple use)
+::::::::::::::::::::::::::::::::::
+
+Like Requires-Dist, but names dependencies needed while the
+distributions's distutils / packaging `setup.py` / `setup.cfg` is run.
+Commonly used to generate a manifest from version control.
+
+Examples::
+
+    Setup-Requires-Dist: custom_setup_command
+
+Dependencies mentioned in `Setup-Requires-Dist` may be installed exclusively
+for setup and are not guaranteed to be available at run time.
+
+
 Provides-Dist (multiple use)
 ::::::::::::::::::::::::::::
 
 The label is a free text limited to 32 signs.
 
 
+Provides-Extra (multiple use)
+:::::::::::::::::::::::::::::
+
+A string containing the name of an optional feature. Must be a valid Python
+identifier. May be used to make a dependency conditional on whether the
+optional feature has been requested.
+
+Example::
+
+    Name: beaglevote
+    Provides-Extra: pdf
+    Requires-Dist: reportlab; extra == 'pdf'
+    Requires-Dist: nose; extra == 'test'
+    Requires-Dist: sphinx; extra == 'doc'
+
+A second distribution requires an optional dependency by placing it
+inside square brackets and can request multiple features by separating
+them with a comma (,).
+
+The full set of requirements is the union of the `Requires-Dist` sets
+evaluated with `extra` set to `None` and then to the name of each
+requested feature.
+
+Example::
+
+    Requires-Dist: beaglevote[pdf]
+	-> requires beaglevote, reportlab
+
+    Requires-Dist: beaglevote[test, doc]
+	-> requires beaglevote, sphinx, nose
+
+Two feature names `test` and `doc` are reserved to mark dependencies that
+are needed for running automated tests and generating documentation,
+respectively.
+
+It is legal to specify `Provides-Extra` without referencing it in any
+`Requires-Dist`. It is an error to request a feature name that has
+not been declared with `Provides-Extra`.
+
+
 Version Specifiers
 ==================
 
 
 - ``Requires-Dist: zope.interface (3.1)``: any version that starts with 3.1,
   excluding post or pre-releases.
+- ``Requires-Dist: zope.interface (==3.1)``: equivalent to ``Requires-Dist:
+  zope.interface (3.1)``.
 - ``Requires-Dist: zope.interface (3.1.0)``: any version that starts with
   3.1.0, excluding post or pre-releases. Since that particular project doesn't
   use more than 3 digits, it also means "only the 3.1.0 release".
 - platform.machine = platform.machine()
 - platform.python_implementation = platform.python_implementation()
 - a free string, like ``'2.4'``, or ``'win32'``
+- extra = (name of requested feature) or None
 
 Notice that ``in`` is restricted to strings, meaning that it is not possible
 to use other sequences like tuples or lists on the right side.
 - Requires-Python
 - Requires-External
 - Requires-Dist
+- Setup-Requires-Dist
 - Provides-Dist
 - Obsoletes-Dist
 - Classifier
   - Requires-Python
   - Requires-External
   - Requires-Dist
+  - Setup-Requires-Dist
   - Provides-Dist
+  - Provides-Extra
   - Obsoletes-Dist
   - Project-URL