[Python-checkins] r75552 - peps/trunk/pep-0345.txt
tarek.ziade
python-checkins at python.org
Tue Oct 20 09:59:46 CEST 2009
Author: tarek.ziade
Date: Tue Oct 20 09:59:46 2009
New Revision: 75552
Log:
udpating 345 with Tres branch
Modified:
peps/trunk/pep-0345.txt
Modified: peps/trunk/pep-0345.txt
==============================================================================
--- peps/trunk/pep-0345.txt (original)
+++ peps/trunk/pep-0345.txt Tue Oct 20 09:59:46 2009
@@ -26,8 +26,10 @@
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 @@
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 @@
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-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: "C. Schultz" <cschultz at example.com>
-License
+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 <cschultz at 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 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" <cschultz at example.com>
+
+License (optional)
Text indicating the license covering the package where the license
is not a selection from the "License" Trove classifiers. See
- "Classifier" below.
+ "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.
- Example::
+ 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 @@
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 @@
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: 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 @@
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: 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: 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 @@
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 @@
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 @@
.. [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
More information about the Python-checkins
mailing list