Reorder metadata field descriptions in PEP 426
This tries to create a slightly easier to read ordering for the field descriptions. Roughly: - basic metadata - URLs - contacts - licensing & classifiers - what the distribution provides - what the distribution needs - extended metadata
This commit is contained in:
Nick Coghlan
parent
f07255bc68
commit
300db2f1cc
234
pep-0426.txt
234
pep-0426.txt
|
|
@ -117,35 +117,6 @@ Example::
|
|||
Summary: A module for collecting votes from beagles.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
__ `Classifier (multiple use)`_
|
||||
|
||||
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
|
||||
|
||||
|
||||
Description (optional, deprecated)
|
||||
----------------------------------
|
||||
|
||||
|
|
@ -197,6 +168,19 @@ can be downloaded. (This means that the URL can't be something like
|
|||
".../BeagleVote-latest.tgz", but instead must be ".../BeagleVote-0.45.tgz".)
|
||||
|
||||
|
||||
Project-URL (multiple use)
|
||||
--------------------------
|
||||
|
||||
A string containing a label and a browsable URL for the project, separated
|
||||
by the last occurrence of comma and space ", ".
|
||||
|
||||
The label consists of any permitted header text, including commas.
|
||||
|
||||
Example::
|
||||
|
||||
Bug, Issue Tracker, http://bitbucket.org/tarek/distribute/issues/
|
||||
|
||||
|
||||
Author (optional)
|
||||
-----------------
|
||||
|
||||
|
|
@ -285,6 +269,88 @@ Examples::
|
|||
Classifier: Environment :: Console (Text Based)
|
||||
|
||||
|
||||
Provides-Dist (multiple use)
|
||||
----------------------------
|
||||
|
||||
Each entry contains a string naming a requirement that is satisfied by
|
||||
installing this distribution. These strings must be of the form
|
||||
``Name`` or ``Name (Version)``, following the formats of the corresponding
|
||||
field definitions.
|
||||
|
||||
For ease of metadata consumption, distributions are required to explicitly
|
||||
include a ``Provides-Dist`` entry for their own name and version. This also
|
||||
allows developers of a project to discourage users explicitly depending on
|
||||
the project (by deliberately omitting this entry).
|
||||
|
||||
A distribution may provide additional names, e.g. to indicate that
|
||||
multiple projects have been merged into and replaced by a single
|
||||
distribution or to indicate that this project is a substitute for another.
|
||||
For instance, distribute (a fork of setuptools) can include a
|
||||
``Provides-Dist: setuptools`` entry to prevent the conflicting
|
||||
package from being downloaded and installed when distribute is already
|
||||
installed. A distribution that has been merged with another might
|
||||
``Provides-Dist`` the obsolete name(s) to satisfy any projects that
|
||||
require the obsolete distribution's name.
|
||||
|
||||
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 ``ExampleORM-somedb-bindings``, allowing other
|
||||
projects to depend only on having at least one of them installed.
|
||||
|
||||
A version declaration may be supplied and must follow the rules described
|
||||
in `Version Scheme`_. The distribution's version number will be implied
|
||||
if none is specified.
|
||||
|
||||
Examples::
|
||||
|
||||
Provides-Dist: ThisProject
|
||||
Provides-Dist: AnotherProject (3.4)
|
||||
Provides-Dist: virtual_package
|
||||
|
||||
|
||||
Provides-Extra (multiple use)
|
||||
-----------------------------
|
||||
|
||||
A string containing the name of an optional feature. Must be printable
|
||||
ASCII, not containing whitespace, comma (,), or square brackets [].
|
||||
May be used to make a dependency conditional on whether the optional
|
||||
feature has been requested.
|
||||
|
||||
See `Optional Features`_ for details on the use of this field.
|
||||
|
||||
Example::
|
||||
|
||||
Name: beaglevote
|
||||
Provides-Extra: pdf
|
||||
Requires-Dist: reportlab; extra == 'pdf'
|
||||
Requires-Dist: nose; extra == 'test'
|
||||
Requires-Dist: sphinx; extra == 'doc'
|
||||
|
||||
|
||||
Obsoleted-By (optional)
|
||||
-----------------------
|
||||
|
||||
Indicates that this project is no longer being developed. The named
|
||||
project provides a substitute or replacement.
|
||||
|
||||
A version declaration may be supplied and must follow the rules described
|
||||
in `Version Specifiers`_.
|
||||
|
||||
Possible uses for this field include handling project name changes and
|
||||
project mergers.
|
||||
|
||||
Examples::
|
||||
|
||||
Name: BadName
|
||||
Obsoleted-By: AcceptableName
|
||||
|
||||
Name: SeparateProject
|
||||
Obsoleted-By: MergedProject (>=4.0.0)
|
||||
|
||||
|
||||
Requires-Dist (multiple use)
|
||||
----------------------------
|
||||
|
||||
|
|
@ -340,69 +406,6 @@ dependency is needed during distribution creation or installation
|
|||
``Setup-Requires-Dist``.
|
||||
|
||||
|
||||
Provides-Dist (multiple use)
|
||||
----------------------------
|
||||
|
||||
Each entry contains a string naming a requirement that is satisfied by
|
||||
installing this distribution. These strings must be of the form
|
||||
``Name`` or ``Name (Version)``, following the formats of the corresponding
|
||||
field definitions.
|
||||
|
||||
For ease of metadata consumption, distributions are required to explicitly
|
||||
include a ``Provides-Dist`` entry for their own name and version. This also
|
||||
allows developers of a project to discourage users explicitly depending on
|
||||
the project (by deliberately omitting this entry).
|
||||
|
||||
A distribution may provide additional names, e.g. to indicate that
|
||||
multiple projects have been merged into and replaced by a single
|
||||
distribution or to indicate that this project is a substitute for another.
|
||||
For instance, distribute (a fork of setuptools) can include a
|
||||
``Provides-Dist: setuptools`` entry to prevent the conflicting
|
||||
package from being downloaded and installed when distribute is already
|
||||
installed. A distribution that has been merged with another might
|
||||
``Provides-Dist`` the obsolete name(s) to satisfy any projects that
|
||||
require the obsolete distribution's name.
|
||||
|
||||
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 ``ExampleORM-somedb-bindings``, allowing other
|
||||
projects to depend only on having at least one of them installed.
|
||||
|
||||
A version declaration may be supplied and must follow the rules described
|
||||
in `Version Scheme`_. The distribution's version number will be implied
|
||||
if none is specified.
|
||||
|
||||
Examples::
|
||||
|
||||
Provides-Dist: ThisProject
|
||||
Provides-Dist: AnotherProject (3.4)
|
||||
Provides-Dist: virtual_package
|
||||
|
||||
|
||||
Obsoleted-By (optional)
|
||||
-----------------------
|
||||
|
||||
Indicates that this project is no longer being developed. The named
|
||||
project provides a substitute or replacement.
|
||||
|
||||
A version declaration may be supplied and must follow the rules described
|
||||
in `Version Specifiers`_.
|
||||
|
||||
Possible uses for this field include handling project name changes and
|
||||
project mergers.
|
||||
|
||||
Examples::
|
||||
|
||||
Name: BadName
|
||||
Obsoleted-By: AcceptableName
|
||||
|
||||
Name: SeparateProject
|
||||
Obsoleted-By: MergedProject (>=4.0.0)
|
||||
|
||||
|
||||
Requires-Python (multiple use)
|
||||
------------------------------
|
||||
|
||||
|
|
@ -448,36 +451,33 @@ Examples::
|
|||
Requires-External: libpng (>=1.5)
|
||||
|
||||
|
||||
Project-URL (multiple use)
|
||||
--------------------------
|
||||
Platform (multiple use)
|
||||
-----------------------
|
||||
|
||||
A string containing a label and a browsable URL for the project, separated
|
||||
by the last occurrence of comma and space ", ".
|
||||
A Platform specification describing an operating system supported by
|
||||
the distribution which is not listed in the "Operating System" Trove
|
||||
classifiers. See `Classifier`__ above.
|
||||
|
||||
The label consists of any permitted header text, including commas.
|
||||
__ `Classifier (multiple use)`_
|
||||
|
||||
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::
|
||||
|
||||
Bug, Issue Tracker, http://bitbucket.org/tarek/distribute/issues/
|
||||
|
||||
|
||||
Provides-Extra (multiple use)
|
||||
-----------------------------
|
||||
|
||||
A string containing the name of an optional feature. Must be printable
|
||||
ASCII, not containing whitespace, comma (,), or square brackets [].
|
||||
May be used to make a dependency conditional on whether the optional
|
||||
feature has been requested.
|
||||
|
||||
See `Optional Features`_ for details on the use of this field.
|
||||
|
||||
Example::
|
||||
|
||||
Name: beaglevote
|
||||
Provides-Extra: pdf
|
||||
Requires-Dist: reportlab; extra == 'pdf'
|
||||
Requires-Dist: nose; extra == 'test'
|
||||
Requires-Dist: sphinx; extra == 'doc'
|
||||
Supported-Platform: RedHat 7.2
|
||||
Supported-Platform: i386-win32-2791
|
||||
|
||||
|
||||
Extension (multiple use)
|
||||
|
|
|
|||
Loading…
Reference in New Issue