[Python-checkins] peps: specify Provides-Extra

[benjamin.peterson]

http://hg.python.org/peps/rev/4dc72bbf9ed2
changeset:   4483:4dc72bbf9ed2
user:        Daniel Holth <dholth at fastmail.fm>
date:        Wed Jul 04 07:30:08 2012 -0400
summary:
  specify Provides-Extra

files:
  pep-0345.txt |  36 +++++++++++++++++++++++++++++++++++-
  1 files changed, 35 insertions(+), 1 deletions(-)


diff --git a/pep-0345.txt b/pep-0345.txt
--- a/pep-0345.txt
+++ b/pep-0345.txt
@@ -26,7 +26,7 @@
 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
+"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".
 
@@ -395,6 +395,36 @@
 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::
+
+    Provides-Extra: pdf
+    Requires-Dist: reportlab; extra == 'pdf'
+
+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 requirements are evaluated for each requested
+feature and added to the set of requirements for the distribution.
+
+Example::
+
+    Requires-Dist: beaglevote[pdf]
+    Requires-Dist: libexample[test, doc]
+
+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:`.
+
+
 Version Specifiers
 ==================
 
@@ -433,6 +463,8 @@
 
 - ``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".
@@ -485,6 +517,7 @@
 - platform.machine = platform.machine()
 - platform.python_implementation = platform.python_implementation()
 - a free string, like ``'2.4'``, or ``'win32'``
+- extra = (name of requested feature)
 
 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.
@@ -518,6 +551,7 @@
   - Requires-External
   - Requires-Dist
   - Provides-Dist
+  - Provides-Extra
   - Obsoletes-Dist
   - Project-URL
 

-- 
Repository URL: http://hg.python.org/peps