http://hg.python.org/peps/rev/42ee0afd40ed changeset: 4502:42ee0afd40ed user: Nick Coghlan <ncoghlan@gmail.com> date: Fri Aug 31 23:53:29 2012 +1000 summary: Add first draft of 1.3 metadata spec (includes some info on metadata files that went missing in the 1.2 spec) files: pep-0426.txt | 643 +++++++++++++++++++++++++++++++++++++++ 1 files changed, 643 insertions(+), 0 deletions(-) diff --git a/pep-0426.txt b/pep-0426.txt new file mode 100644 --- /dev/null +++ b/pep-0426.txt @@ -0,0 +1,643 @@ +PEP: 426 +Title: Metadata for Python Software Packages 1.3 +Version: $Revision$ +Last-Modified: $Date$ +Author: Daniel Holth <dholth@fastmail.fm> +Discussions-To: Distutils SIG +Status: Draft +Type: Standards Track +Content-Type: text/x-rst +Created: 30 Aug 2012 + + +Abstract +======== + +This PEP describes a mechanism for adding metadata to Python distributions. +It includes specifics of the field names, and their semantics and +usage. + +This document specifies version 1.3 of the metadata format. +Version 1.0 is specified in PEP 241. +Version 1.1 is specified in PEP 314. +Version 1.2 is specified in PEP 345. + +Version 1.3 of the metadata format adds fields designed to make +third-party packaging of Python Software easier and defines a +formal extension mechanism. The fields are "Setup-Requires-Dist" +"Provides-Extra", and "Extension". This version also adds the `extra` +variable to the `environment markers` specification. + +Metadata Files +============== + +The syntax defined in this PEP is for use with Python distribution metadata +files. This file format is a single set of RFC-822 headers parseable by +the ``rfc822`` or ``email`` modules. The field names listed in the +`Fields`_ section are used as the header names. + +There are two standard locations for these metadata files: + +* the ``PKG-INFO`` file included in the base directory of Python + source distribution archives (as created by the distutils ``sdist`` + command) +* the ``dist-info/METADATA`` files in a Python installation database, as + described in PEP 376. + +Other tools involved in Python distribution may choose to record this +metadata in additional tool-specific locations (e.g. as part of a +binary distribution archive format). + +Encoding +======== + +Keys must be ASCII. Values are expected to be displayed as UTF-8, +but should otherwise be treated as opaque bytes. + +Fields +====== + +This section specifies the names and semantics of each of the +supported metadata fields. + +Fields marked with "(Multiple use)" may be specified multiple +times in a single metadata file. Other fields may only occur +once in a metadata file. Fields marked with "(optional)" are +not required to appear in a valid metadata file; all other +fields must be present. + +Metadata-Version +:::::::::::::::: + +Version of the file format; "1.3" is the only legal value. + +Example:: + + Metadata-Version: 1.3 + + +Name +:::: + +The name of the distribution. + +Example:: + + Name: BeagleVote + + +Version +::::::: + +A string containing the distribution's version number. This +field must be in the format specified in PEP 386. + +Example:: + + Version: 1.0a2 + + +Platform (multiple use) +::::::::::::::::::::::: + +A Platform specification describing an operating system supported by +the distribution which is not listed in the "Operating System" Trove classifiers. +See "Classifier" below. + +Examples:: + + Platform: ObscureUnix + Platform: RareDOS + + +Supported-Platform (multiple use) +::::::::::::::::::::::::::::::::: + +Binary distributions containing a metadata file will use the +Supported-Platform field in their metadata to specify the OS and +CPU for which the binary distribution was compiled. The semantics of +the Supported-Platform field are not specified in this PEP. + +Example:: + + Supported-Platform: RedHat 7.2 + Supported-Platform: i386-win32-2791 + + +Summary +::::::: + +A one-line summary of what the distribution does. + +Example:: + + Summary: A module for collecting votes from beagles. + + +Description (optional) +:::::::::::::::::::::: + +A longer description of the distribution that can run to several +paragraphs. Software that deals with metadata should not assume +any maximum size for this field, though people shouldn't include +their instruction manual as the description. + +The contents of this field can be written using reStructuredText +markup [1]_. For programs that work with the metadata, supporting +markup is optional; programs can also display the contents of the +field as-is. This means that authors should be conservative in +the markup they use. + +To support empty lines and lines with indentation with respect to +the RFC 822 format, any CRLF character has to be suffixed by 7 spaces +followed by a pipe ("|") char. As a result, the Description field is +encoded into a folded field that can be interpreted by RFC822 +parser [2]_. + +Example:: + + Description: This project provides powerful math functions + |For example, you can use `sum()` to sum numbers: + | + |Example:: + | + | >>> sum(1, 2) + | 3 + | + +This encoding implies that any occurences of a CRLF followed by 7 spaces +and a pipe char have to be replaced by a single CRLF when the field is unfolded +using a RFC822 reader. + + +Keywords (optional) +::::::::::::::::::: + +A list of additional keywords to be used to assist searching +for the distribution in a larger catalog. + +Example:: + + Keywords: dog puppy voting election + + +Home-page (optional) +:::::::::::::::::::: + +A string containing the URL for the distribution's home page. + +Example:: + + Home-page: http://www.example.com/~cschultz/bvote/ + + +Download-URL +:::::::::::: + +A string containing the URL from which this version of the distribution +can be downloaded. (This means that the URL can't be something like +".../BeagleVote-latest.tgz", but instead must be ".../BeagleVote-0.45.tgz".) + + +Author (optional) +::::::::::::::::: + +A string containing the author's name at a minimum; additional +contact information may be provided. + +Example:: + + Author: C. Schultz, Universal Features Syndicate, + Los Angeles, CA <cschultz@peanuts.example.com> + + +Author-email (optional) +::::::::::::::::::::::: + +A string containing the author's e-mail address. It can contain +a name and e-mail address in the legal forms for a RFC-822 +``From:`` header. + +Example:: + + Author-email: "C. Schultz" <cschultz@example.com> + + +Maintainer (optional) +::::::::::::::::::::: + +A string containing the maintainer's name at a minimum; additional +contact information may be provided. + +Note that this field is intended for use when a project is being +maintained by someone other than the original author: it should be +omitted if it is identical to ``Author``. + +Example:: + + Maintainer: C. Schultz, Universal Features Syndicate, + Los Angeles, CA <cschultz@peanuts.example.com> + + +Maintainer-email (optional) +::::::::::::::::::::::::::: + +A string containing the maintainer's e-mail address. It can contain +a name and e-mail address in the legal forms for a RFC-822 +``From:`` header. + +Note that this field is intended for use when a project is being +maintained by someone other than the original author: it should be +omitted if it is identical to ``Author-email``. + +Example:: + + Maintainer-email: "C. Schultz" <cschultz@example.com> + + +License (optional) +:::::::::::::::::: + +Text indicating the license covering the distribution where the license +is not a selection from the "License" Trove classifiers. See +"Classifier" below. This field may also be used to specify a +particular version of a licencse which is named via the ``Classifier`` +field, or to indicate a variation or exception to such a license. + +Examples:: + + License: This software may only be obtained by sending the + author a postcard, and then the user promises not + to redistribute it. + + License: GPL version 3, excluding DRM provisions + + +Classifier (multiple use) +::::::::::::::::::::::::: + +Each entry is a string giving a single classification value +for the distribution. Classifiers are described in PEP 301 [2]. + +Examples:: + + Classifier: Development Status :: 4 - Beta + Classifier: Environment :: Console (Text Based) + + +Requires-Dist (multiple use) +:::::::::::::::::::::::::::: + +Each entry contains a string naming some other distutils +project required by this distribution. + +The format of a requirement string is identical to that of a +distutils project name (e.g., as found in the ``Name:`` field. +optionally followed by a version declaration within parentheses. + +The distutils project names should correspond to names as found +on the `Python Package Index`_. + +Version declarations must follow the rules described in +`Version Specifiers`_ + +Examples:: + + Requires-Dist: pkginfo + Requires-Dist: PasteDeploy + 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) +:::::::::::::::::::::::::::: + +Each entry contains a string naming a Distutils project which +is contained within this distribution. This field *must* include +the project identified in the ``Name`` field, followed by the +version : Name (Version). + +A distribution may provide additional names, e.g. to indicate that +multiple projects have been bundled together. For instance, source +distributions of the ``ZODB`` project have historically included +the ``transaction`` project, which is now available as a separate +distribution. Installing such a source distribution satisfies +requirements for both ``ZODB`` and ``transaction``. + +A distribution may also provide a "virtual" project name, which does +not correspond to any separately-distributed project: such a name +might be used to indicate an abstract capability which could be supplied +by one of multiple projects. E.g., multiple projects might supply +RDBMS bindings for use by a given ORM: each project might declare +that it provides ``ORM-bindings``, allowing other projects to depend +only on having at most one of them installed. + +A version declaration may be supplied and must follow the rules described +in `Version Specifiers`_. The distribution's version number will be implied +if none is specified. + +Examples:: + + Provides-Dist: OtherProject + Provides-Dist: AnotherProject (3.4) + Provides-Dist: virtual_package + + +Obsoletes-Dist (multiple use) +::::::::::::::::::::::::::::: + +Each entry contains a string describing a distutils project's distribution +which this distribution renders obsolete, meaning that the two projects +should not be installed at the same time. + +Version declarations can be supplied. Version numbers must be in the +format specified in `Version Specifiers`_. + +The most common use of this field will be in case a project name +changes, e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. +When you install Torqued Python, the Gorgon distribution should be +removed. + +Examples:: + + Obsoletes-Dist: Gorgon + Obsoletes-Dist: OtherProject (<3.0) + + +Requires-Python +::::::::::::::: + +This field specifies the Python version(s) that the distribution is +guaranteed to be compatible with. + +Version numbers must be in the format specified in `Version Specifiers`_. + +Examples:: + + Requires-Python: 2.5 + Requires-Python: >2.1 + Requires-Python: >=2.3.4 + Requires-Python: >=2.5,<2.7 + + +Requires-External (multiple use) +:::::::::::::::::::::::::::::::: + +Each entry contains a string describing some dependency in the +system that the distribution is to be used. This field is intended to +serve as a hint to downstream project maintainers, and has no +semantics which are meaningful to the ``distutils`` distribution. + +The format of a requirement string is a name of an external +dependency, optionally followed by a version declaration within +parentheses. + +Because they refer to non-Python software releases, version numbers +for this field are **not** required to conform to the format +specified in PEP 386: they should correspond to the +version scheme used by the external dependency. + +Notice that there's is no particular rule on the strings to be used. + +Examples:: + + Requires-External: C + Requires-External: libpng (>=1.5) + + +Project-URL (multiple-use) +:::::::::::::::::::::::::: + +A string containing a browsable URL for the project and a label for it, +separated by a comma. + +Example:: + + Bug Tracker, http://bitbucket.org/tarek/distribute/issues/ + +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`. + + +Extension (multiple-use) +:::::::::::::::::::::::: + +An ASCII string, not containing whitespace or the - character, that +indicates the presence of extended metadata. Additional tags defined by +the extension should be of the form string-Name:: + + Extension: Chili + Chili-Type: Poblano + Chili-Heat: Mild + + +Version Specifiers +================== + +Version specifiers are a series of conditional operators and +version numbers, separated by commas. Conditional operators +must be one of "<", ">", "<=", ">=", "==" and "!=". + +Any number of conditional operators can be specified, e.g. +the string ">1.0, !=1.3.4, <2.0" is a legal version declaration. +The comma (",") is equivalent to the **and** operator. + +Each version number must be in the format specified in PEP 386. + +When a version is provided, it always includes all versions that +starts with the same value. For example the "2.5" version of Python +will include versions like "2.5.2" or "2.5.3". Pre and post releases +in that case are excluded. So in our example, versions like "2.5a1" are +not included when "2.5" is used. If the first version of the range is +required, it has to be explicitly given. In our example, it will be +"2.5.0". + +Notice that some projects might omit the ".0" prefix for the first release +of the "2.5.x" series: + +- 2.5 +- 2.5.1 +- 2.5.2 +- etc. + +In that case, "2.5.0" will have to be explicitly used to avoid any confusion +between the "2.5" notation that represents the full range. It is a recommended +practice to use schemes of the same length for a series to completely avoid +this problem. + +Some Examples: + +- ``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". +- ``Requires-Python: 3``: Any Python 3 version, no matter wich one, excluding + post or pre-releases. +- ``Requires-Python: >=2.6,<3``: Any version of Python 2.6 or 2.7, including + post releases of 2.6, pre and post releases of 2.7. It excludes pre releases + of Python 3. +- ``Requires-Python: 2.6.2``: Equivalent to ">=2.6.2,<2.6.3". So this includes + only Python 2.6.2. Of course, if Python was numbered with 4 digits, it would + have include all versions of the 2.6.2 series. +- ``Requires-Python: 2.5.0``: Equivalent to ">=2.5.0,<2.5.1". +- ``Requires-Dist: zope.interface (3.1,!=3.1.3)``: any version that starts with + 3.1, excluding post or pre-releases of 3.1 *and* excluding any version that + starts with "3.1.3". For this particular project, this means: "any version + of the 3.1 series but not 3.1.3". This is equivalent to: + ">=3.1,!=3.1.3,<3.2". + +Environment markers +=================== + +An **environment marker** is a marker that can be added at the end of a +field after a semi-colon (";"), to add a condition about the execution +environment. + +Here are some example of fields using such markers:: + + Requires-Dist: pywin32 (>1.0); sys.platform == 'win32' + Obsoletes-Dist: pywin31; sys.platform == 'win32' + Requires-Dist: foo (1,!=1.3); platform.machine == 'i386' + Requires-Dist: bar; python_version == '2.4' or python_version == '2.5' + Requires-External: libxslt; 'linux' in sys.platform + +The micro-language behind this is the simplest possible: it compares only +strings, with the ``==`` and ``in`` operators (and their opposites), and +with the ability to combine expressions. Parethesis are also supported for +grouping. + +The pseudo-grammar is :: + + EXPR [in|==|!=|not in] EXPR [or|and] ... + +where ``EXPR`` belongs to any of those: + +- python_version = '%s.%s' % (sys.version_info[0], sys.version_info[1]) +- python_full_version = sys.version.split()[0] +- os.name = os.name +- sys.platform = sys.platform +- platform.version = platform.version() +- 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. + +The fields that benefit from this marker are: + +- Requires-Python +- Requires-External +- Requires-Dist +- Setup-Requires-Dist +- Provides-Dist +- Obsoletes-Dist +- Classifier + +(The `extra` variable is only meaningful for Requires-Dist.) + +Summary of Differences From PEP 345 +=================================== + +* Values are now expected to be UTF-8 + +* Metadata-Version is now 1.3. + +* Added `extra` to environment markers. + +* Changed fields: + + - Requires-Dist + +* Added fields: + + - Setup-Requires-Dist + - Provides-Extra + - Extension + +References +========== + +This document specifies version 1.3 of the metadata format. +Version 1.0 is specified in PEP 241. +Version 1.1 is specified in PEP 314. +Version 1.2 is specified in PEP 345. + +.. [1] reStructuredText markup: + http://docutils.sourceforge.net/ + +.. _`Python Package Index`: http://pypi.python.org/pypi/ + +.. [2] RFC 822 Long Header Fields: + http://www.freesoft.org/CIE/RFC/822/7.htm + +Copyright +========= + +This document has been placed in the public domain. + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: -- Repository URL: http://hg.python.org/peps