[Python-checkins] r77005 - peps/trunk/pep-0345.txt
tarek.ziade
python-checkins at python.org
Wed Dec 23 01:10:25 CET 2009
Author: tarek.ziade
Date: Wed Dec 23 01:10:25 2009
New Revision: 77005
Log:
improving the PEP readability
Modified:
peps/trunk/pep-0345.txt
Modified: peps/trunk/pep-0345.txt
==============================================================================
--- peps/trunk/pep-0345.txt (original)
+++ peps/trunk/pep-0345.txt Wed Dec 23 01:10:25 2009
@@ -44,387 +44,462 @@
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.
+::::
+
+The name of the package.
- Example::
+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`_.
+:::::::
+
+A string containing the package's version number. This
+field must be in the format specified in `PEP 386`_.
- Example::
+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.
+:::::::::::::::::::::::
+
+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::
+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.
+:::::::::::::::::::::::::::::::::
+
+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::
+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.
+:::::::
+
+A one-line summary of what the package does.
+
+Example::
- 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.
-
- 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.
+::::::::::::::::::::::
+
+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.
+
+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.
+
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.
+::::::::::::::::::::
+
+A string containing the URL for the package's home page.
+
+Example::
- 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.
+:::::::::::::::::
+
+A string containing the author's name at a minimum; additional
+contact information may be provided.
- Example::
+Example::
+
+ Author: C. Schultz, Universal Features Syndicate,
+ Los Angeles, CA <cschultz at peanuts.example.com>
- Author: C. Schultz, Universal Features Syndicate,
- Los Angeles, CA <cschultz at peanuts.example.com>
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.
+::::::::::::
+
+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::
+Example::
+
+ Author-email: "C. Schultz" <cschultz at example.com>
- Author-email: "C. Schultz" <cschultz at example.com>
Maintainer (optional)
- A string containing the maintainer's name at a minimum; additional
- contact information may be provided.
+:::::::::::::::::::::
+
+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``.
+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::
+Example::
+
+ Maintainer: C. Schultz, Universal Features Syndicate,
+ Los Angeles, CA <cschultz at peanuts.example.com>
- 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.
+:::::::::::::::::::::::::::
+
+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``.
+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::
+Example::
+
+ Maintainer-email: "C. Schultz" <cschultz at example.com>
- 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. 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.
+::::::::::::::::::
+
+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
- 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].
+:::::::::::::::::::::::::
+
+Each entry is a string giving a single classification value
+for the package. Classifiers are described in PEP 301 [2].
+
+Examples::
+
+ Classifier: Development Status :: 4 - Beta
+ Classifier: Environment :: Console (Text Based)
- Examples::
- Classifier: Development Status :: 4 - Beta
- Classifier: Environment :: Console (Text Based)
+Requires (multiple use) (deprecated)
+::::::::::::::::::::::::::::::::::::
-Requires (multiple use)
- Each entry contains a string describing some other module or
- package required by this package.
+**This field is now deprecated in favor of "Requires-Dist"**
- 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.
+Each entry contains a string describing some other module or
+package required by this package.
- 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",
+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.
- 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 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",
- All of the following are possible requirement strings: "rfc822",
- "zlib (>=1.1.4)", "zope".
+Any number of conditional operators can be specified, e.g.
+the string ">1.0, !=1.3.4, <2.0" is a legal version declaration.
- There's no canonical list of what strings should be used; the
- Python community is left to choose its own standards.
+All of the following are possible requirement strings: "rfc822",
+"zlib (>=1.1.4)", "zope".
- Examples::
+There's no canonical list of what strings should be used; the
+Python community is left to choose its own standards.
- Requires: re
- Requires: sys
- Requires: zlib
- Requires: xml.parsers.expat (>1.0)
- Requires: psycopg
+Examples::
- Note: this field is now deprecated in favor of ``Requires-Dist``.
+ Requires: re
+ Requires: sys
+ Requires: zlib
+ Requires: xml.parsers.expat (>1.0)
+ Requires: psycopg
-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.
- Examples::
+Provides (multiple use) (deprecated)
+::::::::::::::::::::::::::::::::::::
- Provides: xml
- Provides: xml.utils
- Provides: xml.utils.iso8601
- Provides: xml.dom
- Provides: xmltools (1.3)
+**This field is now deprecated in favor of "Provides-Dist"**
- Note: this field is now deprecated in favor of ``Provides-Dist``.
+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 (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.
+Examples::
- 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.
+ Provides: xml
+ Provides: xml.utils
+ Provides: xml.utils.iso8601
+ Provides: xml.dom
+ Provides: xmltools (1.3)
- Example::
- Obsoletes: Gorgon
+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.
+::::::::::::::::::::::::::::
+
+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`_.
+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.
+
+Examples::
+
+ Requires-Dist: pkginfo
+ Requires-Dist: PasteDeploy
+ Requires-Dist: zope.interface (>3.5.0)
- 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`_.
- 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.
-
- 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
+::::::::::::::::::::::::::::
+
+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::
+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)
- 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`_.
-
- 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
+:::::::::::::::
+
+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`_.
+
+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-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.
-
- 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.
-
- 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.
+::::::::::::::::::::::::::::::::
+
+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.
+
+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.
- Notice that there's is no particular rule on the strings to be used.
+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.
- 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.
- Requires-External: C
- Requires-External: libpng (>=1.5)
+Notice that there's is no particular rule on the strings to be used.
+
+Examples::
+
+ Requires-External: C
+ Requires-External: libpng (>=1.5)
Copyright
- Indicates the party or parties, and the year of copyright
- covering the package.
+:::::::::
+
+Indicates the party or parties, and the year of copyright
+covering the package.
+
+Examples::
- Examples::
+ Copyright: Guido van Rossum, 1991
+ Copyright: Python Software Foundation, 2005
+ Copyright: Public Domain
- Copyright: Guido van Rossum, 1991
- Copyright: Python Software Foundation, 2005
- Copyright: Public Domain
+Project-URL (multiple-use)
+::::::::::::::::::::::::::
-Project-URL (multiple-use) :
- A string containing a browsable URL for the project and a label for it,
- separated by a comma.
+A string containing a browsable URL for the project and a label for it,
+separated by a comma.
- Example::
+Example::
- Bug Tracker, http://bitbucket.org/tarek/distribute/issues/
+ Bug Tracker, http://bitbucket.org/tarek/distribute/issues/
- The label is a free text limited to 32 signs.
+The label is a free text limited to 32 signs.
Version Specifiers
More information about the Python-checkins
mailing list