diff --git a/pep-0345.txt b/pep-0345.txt index 8dc8cf1ba..5c57b7936 100644 --- a/pep-0345.txt +++ b/pep-0345.txt @@ -44,387 +44,462 @@ not required to appear in a valid PKG-INFO file; all other fields must be present. Metadata-Version - Version of the file format; "1.0", "1.1" and "1.2" are the - only legal values here. +:::::::::::::::: - Example:: +Version of the file format; "1.0", "1.1" and "1.2" are the +only legal values here. + +Example:: + + Metadata-Version: 1.2 - Metadata-Version: 1.2 Name - The name of the package. +:::: - Example:: +The name of the package. + +Example:: + + Name: BeagleVote - Name: BeagleVote Version - A string containing the package's version number. This - field must be in the format specified in `PEP 386`_. +::::::: - Example:: +A string containing the package's version number. This +field must be in the format specified in `PEP 386`_. + +Example:: + + Version: 1.0a2 - Version: 1.0a2 Platform (multiple use) - A comma-separated list of platform specifications, summarizing - the operating systems supported by the package which are not - listed in the "Operating System" Trove classifiers. See - "Classifier" below. +::::::::::::::::::::::: - Example:: +A comma-separated list of platform specifications, summarizing +the operating systems supported by the package which are not +listed in the "Operating System" Trove classifiers. See +"Classifier" below. + +Example:: + + Platform: ObscureUnix, RareDOS - Platform: ObscureUnix, RareDOS Supported-Platform (multiple use) - Binary distributions containing a PKG-INFO file will use the - Supported-Platform field in their metadata to specify the OS and - CPU for which the binary package was compiled. The semantics of - the Supported-Platform field are not specified in this PEP. +::::::::::::::::::::::::::::::::: - Example:: +Binary distributions containing a PKG-INFO file will use the +Supported-Platform field in their metadata to specify the OS and +CPU for which the binary package 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 - Supported-Platform: RedHat 7.2 - Supported-Platform: i386-win32-2791 Summary - A one-line summary of what the package does. +::::::: - Example:: +A one-line summary of what the package does. + +Example:: + + Summary: A module for collecting votes from beagles. - Summary: A module for collecting votes from beagles. Description (optional) - A longer description of the package 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. +A longer description of the package 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. - Example:: +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. + +Example:: + + Description: This module collects votes from beagles + in order to determine their electoral wishes. + Do *not* try to use this module with basset hounds; + it makes them grumpy. - Description: This module collects votes from beagles - in order to determine their electoral wishes. - Do *not* try to use this module with basset hounds; - it makes them grumpy. Keywords (optional) - A list of additional keywords to be used to assist searching - for the package in a larger catalog. +::::::::::::::::::: - Example:: +A list of additional keywords to be used to assist searching +for the package in a larger catalog. + +Example:: + + Keywords: dog puppy voting election - Keywords: dog puppy voting election Home-page (optional) - A string containing the URL for the package's home page. +:::::::::::::::::::: - Example:: +A string containing the URL for the package's home page. + +Example:: + + Home-page: http://www.example.com/~cschultz/bvote/ - Home-page: http://www.example.com/~cschultz/bvote/ 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".) +:::::::::::: + +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".) + Author (optional) - A string containing the author's name at a minimum; additional - contact information may be provided. +::::::::::::::::: - Example:: +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 - Author: C. Schultz, Universal Features Syndicate, - Los Angeles, CA 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 - 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 - additional metadata *about the author*, and optionally the - ability to associate several e-mail addresses with the same - person. Author-related metadata fields are not covered by this - PEP. +:::::::::::: - Example:: +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 +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 +additional metadata *about the author*, and optionally the +ability to associate several e-mail addresses with the same +person. Author-related metadata fields are not covered by this +PEP. + +Example:: + + Author-email: "C. Schultz" - Author-email: "C. Schultz" 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``. +A string containing the maintainer's name at a minimum; additional +contact information may be provided. - Example:: +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: 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``. +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. - Example:: +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" - 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:: +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. - License: This software may only be obtained by sending the - author a postcard, and then the user promises not - to redistribute it. +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 - 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]. +::::::::::::::::::::::::: - Examples:: +Each entry is a string giving a single classification value +for the package. Classifiers are described in PEP 301 [2]. - Classifier: Development Status :: 4 - Beta - Classifier: Environment :: Console (Text Based) +Examples:: -Requires (multiple use) - Each entry contains a string describing some other module or - package required by this package. + Classifier: Development Status :: 4 - Beta + Classifier: Environment :: Console (Text Based) - The format of a requirement string is identical to that of a - 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 - 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", +Requires (multiple use) (deprecated) +:::::::::::::::::::::::::::::::::::: - Any number of conditional operators can be specified, e.g. - the string ">1.0, !=1.3.4, <2.0" is a legal version declaration. +**This field is now deprecated in favor of "Requires-Dist"** - All of the following are possible requirement strings: "rfc822", - "zlib (>=1.1.4)", "zope". +Each entry contains a string describing some other module or +package required by this package. - There's no canonical list of what strings should be used; the - Python community is left to choose its own standards. +The format of a requirement string is identical to that of a +module or package name usable with the ``import`` statement, +optionally followed by a version declaration within parentheses. - Examples:: +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", - Requires: re - Requires: sys - Requires: zlib - Requires: xml.parsers.expat (>1.0) - Requires: psycopg +Any number of conditional operators can be specified, e.g. +the string ">1.0, !=1.3.4, <2.0" is a legal version declaration. - Note: this field is now deprecated in favor of ``Requires-Dist``. +All of the following are possible requirement strings: "rfc822", +"zlib (>=1.1.4)", "zope". -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 - strings should match the ones used in Requirements fields. A - version declaration may be supplied (without a comparison - operator); the package's version number will be implied if none - is specified. +There's no canonical list of what strings should be used; the +Python community is left to choose its own standards. - Examples:: +Examples:: - Provides: xml - Provides: xml.utils - Provides: xml.utils.iso8601 - Provides: xml.dom - Provides: xmltools (1.3) + Requires: re + Requires: sys + Requires: zlib + Requires: xml.parsers.expat (>1.0) + Requires: psycopg - 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 - should not be installed at the same time. Version declarations - can be supplied. +Provides (multiple use) (deprecated) +:::::::::::::::::::::::::::::::::::: - The most common use of this field will be in case a package name - changes, e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. - When you install Torqued Python, the Gorgon package should be - removed. +**This field is now deprecated in favor of "Provides-Dist"** - Example:: +Each entry contains a string describing a package or module that +will be provided by this package once it is installed. These +strings should match the ones used in Requirements fields. A +version declaration may be supplied (without a comparison +operator); the package's version number will be implied if none +is specified. - Obsoletes: Gorgon +Examples:: + + Provides: xml + Provides: xml.utils + Provides: xml.utils.iso8601 + Provides: xml.dom + Provides: xmltools (1.3) + + +Obsoletes (multiple use) (deprecated) +::::::::::::::::::::::::::::::::::::: + +**This field is now deprecated in favor of "Obsoletes-Dist"** + +Each entry contains a string describing a package or module +that this package renders obsolete, meaning that the two packages +should not be installed at the same time. Version declarations +can be supplied. + +The most common use of this field will be in case a package name +changes, e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. +When you install Torqued Python, the Gorgon package should be +removed. + +Example:: + + 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. +Each entry contains a string naming some other distutils +project required by this package. - The distutils project names should correspond to names as found - on the `Python Package Index`_. +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. - 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`_. - If no operator is provided with a version, the "==" operator - is used by default. +The distutils project names should correspond to names as found +on the `Python Package Index`_. - Any number of conditional operators can be specified, e.g. - the string ">1.0, !=1.3.4, <2.0" is a legal version declaration. +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`_. +If no operator is provided with a version, the "==" operator +is used by default. - Examples:: +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) - 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``. +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 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 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 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`_. +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. - Examples:: +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 - 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`_. +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. - 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. +Version declarations can be supplied. Version numbers must be in the +format specified in `PEP 386`_. - Examples:: +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) - 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 "!=". If no operator is provided with a version, - the "==" operator is used by default. +::::::::::::::: - Version numbers must be in the format specified in `PEP 386`_. +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 "!=". If no operator is provided with a version, +the "==" operator is used by default. - Any number of conditional operators can be specified, e.g. - the string ">1.0, !=1.3.4, <2.0" is a legal version declaration. +Version numbers must be in the format specified in `PEP 386`_. - Examples:: +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-Python: >2.1 + Requires-Python: >=2.3.4 + Requires-Python: 2.5, 2.6 - Requires-Python: >2.1 - Requires-Python: >=2.3.4 - Requires-Python: 2.5, 2.6 Requires-External (multiple use) - Each entry contains a string describing some dependency in the - 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 - parentheses. +Each entry contains a string describing some dependency in the +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. - A version declaration is a series of conditional operators and - version numbers, separated by commas. Conditional operators - must be one of "<", ">", "<=", ">=", "==", and "!=". If no - operator is provided with a version, the "==" operator is used by default. +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. +A version declaration is a series of conditional operators and +version numbers, separated by commas. Conditional operators +must be one of "<", ">", "<=", ">=", "==", and "!=". If no +operator is provided with a version, the "==" operator is used by default. - Any number of conditional operators can be specified, e.g. - the string ">1.0, !=1.3.4, <2.0" is a legal version declaration. +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. +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:: +Notice that there's is no particular rule on the strings to be used. - Requires-External: C - Requires-External: libpng (>=1.5) +Examples:: + + Requires-External: C + Requires-External: libpng (>=1.5) Copyright - Indicates the party or parties, and the year of copyright - covering the package. +::::::::: - Examples:: +Indicates the party or parties, and the year of copyright +covering the package. - Copyright: Guido van Rossum, 1991 - Copyright: Python Software Foundation, 2005 - Copyright: Public Domain +Examples:: + + Copyright: Guido van Rossum, 1991 + Copyright: Python Software Foundation, 2005 + Copyright: Public Domain -Project-URL (multiple-use) : - A string containing a browsable URL for the project and a label for it, - separated by a comma. +Project-URL (multiple-use) +:::::::::::::::::::::::::: - Example:: +A string containing a browsable URL for the project and a label for it, +separated by a comma. - Bug Tracker, http://bitbucket.org/tarek/distribute/issues/ +Example:: - The label is a free text limited to 32 signs. + Bug Tracker, http://bitbucket.org/tarek/distribute/issues/ + +The label is a free text limited to 32 signs. Version Specifiers