diff --git a/pep-0345.txt b/pep-0345.txt index a512c6167..b2f7687c3 100644 --- a/pep-0345.txt +++ b/pep-0345.txt @@ -26,8 +26,10 @@ 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" and "Requires-External". Also, the -"Metadata-Version" field is updated. +These fields are "Requires-Python", "Requires-External", "Requires-Dist", +"Provides-Dist", and "Obsoletes-Dist". This version also updates the +"Metadata-Version" field, and adds new fields, "Maintainer" and +Maintainer-email". Fields @@ -59,9 +61,7 @@ Name Version A string containing the package's version number. This - field should be parseable by one of the Version classes - (StrictVersion or LooseVersion) in the distutils.version - module. + field must be in the format specified in `PEP 386`_. Example:: @@ -132,7 +132,7 @@ Home-page (optional) Download-URL A string containing the URL from which this version of the package can be downloaded. (This means that the URL can't be something like - ".../package-latest.tgz", but instead must be "../package-0.45.tgz".) + ".../package-latest.tgz", but instead must be ".../package-0.45.tgz".) Author (optional) A string containing the author's name at a minimum; additional @@ -146,7 +146,7 @@ Author (optional) Author-email 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. It's not optional because cataloging systems + ``From:`` header. It's not optional because cataloging systems can use the e-mail portion of this field as a unique key representing the author. A catalog might provide authors the ability to store their GPG key, personal home page, and other @@ -159,17 +159,47 @@ Author-email Author-email: "C. Schultz" -License - Text indicating the license covering the package where the license - is not a selection from the "License" Trove classifiers. See - "Classifier" below. +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 package 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 + +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 package 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" + +License (optional) + Text indicating the license covering the package 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 package. Classifiers are described in PEP 301 [2]. @@ -184,7 +214,7 @@ Requires (multiple use) package required by this package. The format of a requirement string is identical to that of a - module or package name usable with the 'import' statement, + module or package name usable with the ``import`` statement, optionally followed by a version declaration within parentheses. A version declaration is a series of conditional operators and @@ -205,7 +235,7 @@ Requires (multiple use) There's no canonical list of what strings should be used; the Python community is left to choose its own standards. - Example:: + Examples:: Requires: re Requires: sys @@ -213,6 +243,8 @@ Requires (multiple use) Requires: xml.parsers.expat (>1.0) Requires: psycopg + Note: this field is now deprecated in favor of ``Requires-Dist``. + Provides (multiple use) Each entry contains a string describing a package or module that will be provided by this package once it is installed. These @@ -221,7 +253,7 @@ Provides (multiple use) operator); the package's version number will be implied if none is specified. - Example:: + Examples:: Provides: xml Provides: xml.utils @@ -229,6 +261,8 @@ Provides (multiple use) Provides: xml.dom Provides: xmltools (1.3) + Note: this field is now deprecated in favor of ``Provides-Dist``. + Obsoletes (multiple use) Each entry contains a string describing a package or module that this package renders obsolete, meaning that the two packages @@ -244,35 +278,105 @@ Obsoletes (multiple use) Obsoletes: Gorgon + Note: this field is now deprecated in favor of ``Obsoletes-Dist``. + +Requires-Dist (multiple use) + Each entry contains a string naming some other distutils + project required by this package. + + 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`_. + + A version declaration is a series of conditional operators and + version numbers, separated by commas. Conditional operators + must be one of "<", ">", "<=", ">=", "==", and "!=". Version + numbers must be in the format specified in `PEP 386`_. + + Any number of conditional operators can be specified, e.g. + the string ">1.0, !=1.3.4, <2.0" is a legal version declaration. + + Examples:: + + Requires-Dist: pkginfo + Requires-Dist: PasteDeploy + Requires-Dist: zope.interface (>3.5.0) + +Provides-Dist (multiple use) + Each entry contains a string naming a distutlis project which + is contained within this distribution. This field *must* include + the project identified in the ``Name`` field. + + 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 (without a comparison + operator); the distribution's version number will be implied if none + is specified. Version numbers must be in the format specified in + `PEP 386`_. + + Examples:: + + Provides-Dist: OtherPackage + Provides-Dist: AnotherPackage (3.4) + Provides-Dist: virtual_package + +Obsoletes-Dist (multiple use) + Each entry contains a string describing a distutils project which + this package renders obsolete, meaning that the two packages + should not be installed at the same time. + + Version declarations can be supplied. Version numbers must be in the + format specified in `PEP 386`_. + + 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: OtherPackage (<3.0) + Requires-Python This field specifies the Python version(s) that the package is guaranteed to be compatible with. The format of the field is a series of conditional operators and version numbers, separated by commas. Conditional operators must be one of "<", ">", "<=", - ">=", "==", and "!=". Version numbers must be in the format - accepted by the distutils.version.StrictVersion class: two or three - dot-separated numeric components, with an optional "pre-release" - tag on the end consisting of the letter 'a' or 'b' followed by a - number. Example version numbers are "1.0", "2.3a2" and "1.3.99". + ">=", "==", and "!=". + + Version numbers must be in the format specified in `PEP 386`_. Any number of conditional operators can be specified, e.g. the string ">1.0, !=1.3.4, <2.0" is a legal version declaration. - Example:: + Examples:: Requires-Python: >2.1 Requires-Python: >=2.3.4 - XXX This field doesn't take into account possible future - incompatibilities through deprecation. We could specify that the - ">" operator only work for up to two releases? This is based on - the typical deprecation plan that Python usually follows (warning - for two releases and then error). That is, >=2.3.4 works for - 2.3.4, 2.4 and 2.5. Requires-External (multiple use) Each entry contains a string describing some dependency in the - system that the package is to be used. + system that the package is to be used. This field is intended to + serve as a hint to downstream package maintainers, and has no + semantics which are meaningful to the ``distutils`` package. The format of a requirement string is a name of an external dependency, optionally followed by a version declaration within @@ -280,45 +384,50 @@ Requires-External (multiple use) A version declaration is a series of conditional operators and version numbers, separated by commas. Conditional operators - must be one of "<", ">", "<=", ">=", "==", and "!=". Version - numbers must be in the format accepted by the - distutils.version.StrictVersion class: two or three - dot-separated numeric components, with an optional "pre-release" - tag on the end consisting of the letter 'a' or 'b' followed by a - number. Example version numbers are "1.0", "2.3a2", "1.3.99", + must be one of "<", ">", "<=", ">=", "==", and "!=". 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. 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 canonical list of what strings are allowed is available - in the `Cheese Shop`_ database. New names may be added to the - database either through the web or using the command-line; - Python community is left to choose its own standards. + in the `Python Package Index`_ database: see + `External References Registry`_ below for a description of how + the allowed values are managed. Some dependencies are anticipated to be quite broad, eg. "C", indicating a C compiler is required. - Example:: + Examples:: Requires: C - Requires: libpng + Requires: libpng (>=1.5) Copyright Indicates the party or parties, and the year of copyright covering the package. - Example:: + Examples:: Copyright: Guido van Rossum, 1991 Copyright: Python Software Foundation, 2005 Copyright: Public Domain +Version Specifiers +================== + +The specification for distribution version specifiers has been moved to +`PEP 386`_. + External References Registry ============================ -Stores in the `Cheese Shop`_ database a list of (name, description, +Stores in the `Python Package Index`_ database a list of (name, description, URI) identifying an external reference that may be used as a value in a Requires-External field. @@ -330,11 +439,32 @@ through the web or using the command-line. The names in the registry will be created under a first-comes first-wins basis. Other packagers of Python software (eg. to deb, rpm, etc) should be -able to translate the requires-external field to names in their own +able to translate the `Requires-external` field to names in their own packaging system. XXX command-line interface needs work, obviously +Summary of Differences From PEP 314 +=================================== + +* Metadata-Version is now 1.2. + +* Added fields: + + - Maintainer + - Maintainer-email + - Requires-Python + - Requires-External + - Requires-Dist + - Provides-Dist + - Obsoletes-Dist + +* Deprecated fields: + + - Requires (in favor of Requires-Dist) + - Provides (in favor of Provides-Dist) + - Obsoletes (in favor of Obsoletes-Dist) + References ========== @@ -346,7 +476,10 @@ Version 1.1 is specified in PEP 314. .. [1] reStructuredText markup: http://docutils.sourceforge.net/ -.. _`Cheese Shop`: http://cheeseshop.python.org/ +.. _`Python Package Index`: http://pypi.python.org/pypi/ + +.. _`PEP 386`: http://svn.python.org/projects/peps/trunk/pep-0386.txt + Copyright