372 lines
12 KiB
Plaintext
372 lines
12 KiB
Plaintext
|
PEP: 345
|
|||
|
|
Title: Medatadata for Python Software Packages 1.2
|
|||
|
|
Version: $Revision$
|
|||
|
|
Last-Modified: $Date$
|
|||
|
|
Author: Richard Jones <richard@mechanicalcat.net>
|
|||
|
|
Discussions-To: Distutils SIG
|
|||
|
|
Status: Draft
|
|||
|
|
Type: Standards Track
|
|||
|
|
Content-type: text/x-rst
|
|||
|
|
Created: 28-Apr-2005
|
|||
|
|
Python-Version: 2.5
|
|||
|
|
Post-History:
|
|||
|
|
Replaces: 314
|
|||
|
|
|
|||
|
|
|
|||
|
|
Abstract
|
|||
|
|
========
|
|||
|
|
|
|||
|
|
This PEP describes a mechanism for adding metadata to Python packages.
|
|||
|
|
It includes specifics of the field names, and their semantics and
|
|||
|
|
usage.
|
|||
|
|
|
|||
|
|
This document specifies version 1.2 of the metadata format.
|
|||
|
|
Version 1.0 is specified in PEP 241.
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
|
|||
|
|
Fields
|
|||
|
|
======
|
|||
|
|
|
|||
|
|
This section specifies the names and semantics of each of the
|
|||
|
|
supported metadata fields.
|
|||
|
|
|
|||
|
|
Fields marked with "(Multiple use)" may be specified multiple
|
|||
|
|
times in a single PKG-INFO file. Other fields may only occur
|
|||
|
|
once in a PKG-INFO file. Fields marked with "(optional)" are
|
|||
|
|
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::
|
|||
|
|
|
|||
|
|
Metadata-Version: 1.2
|
|||
|
|
|
|||
|
|
Name
|
|||
|
|
The name of the package.
|
|||
|
|
|
|||
|
|
Example::
|
|||
|
|
|
|||
|
|
Name: BeagleVote
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
Example::
|
|||
|
|
|
|||
|
|
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::
|
|||
|
|
|
|||
|
|
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::
|
|||
|
|
|
|||
|
|
Supported-Platform: RedHat 7.2
|
|||
|
|
Supported-Platform: i386-win32-2791
|
|||
|
|
|
|||
|
|
Summary
|
|||
|
|
A one-line summary of what the package does.
|
|||
|
|
|
|||
|
|
Example::
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
Keywords (optional)
|
|||
|
|
A list of additional keywords to be used to assist searching
|
|||
|
|
for the package in a larger catalog.
|
|||
|
|
|
|||
|
|
Example::
|
|||
|
|
|
|||
|
|
Keywords: dog puppy voting election
|
|||
|
|
|
|||
|
|
Home-page (optional)
|
|||
|
|
A string containing the URL for the package's home page.
|
|||
|
|
|
|||
|
|
Example::
|
|||
|
|
|
|||
|
|
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".)
|
|||
|
|
|
|||
|
|
Author (optional)
|
|||
|
|
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 <cschultz@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.
|
|||
|
|
|
|||
|
|
Example::
|
|||
|
|
|
|||
|
|
Author-email: "C. Schultz" <cschultz@example.com>
|
|||
|
|
|
|||
|
|
License
|
|||
|
|
Text indicating the license covering the package where the license
|
|||
|
|
is not a selection from the "License" Trove classifiers. See
|
|||
|
|
"Classifier" below.
|
|||
|
|
|
|||
|
|
Example::
|
|||
|
|
|
|||
|
|
License: This software may only be obtained by sending the
|
|||
|
|
author a postcard, and then the user promises not
|
|||
|
|
to redistribute it.
|
|||
|
|
|
|||
|
|
Classifier (multiple use)
|
|||
|
|
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)
|
|||
|
|
|
|||
|
|
Requires (multiple use)
|
|||
|
|
Each entry contains a string describing some other module or
|
|||
|
|
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,
|
|||
|
|
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",
|
|||
|
|
|
|||
|
|
Any number of conditional operators can be specified, e.g.
|
|||
|
|
the string ">1.0, !=1.3.4, <2.0" is a legal version declaration.
|
|||
|
|
|
|||
|
|
All of the following are possible requirement strings: "rfc822",
|
|||
|
|
"zlib (>=1.1.4)", "zope".
|
|||
|
|
|
|||
|
|
There's no canonical list of what strings should be used; the
|
|||
|
|
Python community is left to choose its own standards.
|
|||
|
|
|
|||
|
|
Example::
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
Example::
|
|||
|
|
|
|||
|
|
Provides: xml
|
|||
|
|
Provides: xml.utils
|
|||
|
|
Provides: xml.utils.iso8601
|
|||
|
|
Provides: xml.dom
|
|||
|
|
Provides: xmltools (1.3)
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
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
|
|||
|
|
|
|||
|
|
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".
|
|||
|
|
|
|||
|
|
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::
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
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 "!=". 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",
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
Some dependencies are anticipated to be quite broad, eg. "C",
|
|||
|
|
indicating a C compiler is required.
|
|||
|
|
|
|||
|
|
Example::
|
|||
|
|
|
|||
|
|
Requires: C
|
|||
|
|
Requires: libpng
|
|||
|
|
|
|||
|
|
|
|||
|
|
Copyright
|
|||
|
|
Indicates the party or parties, and the year of copyright
|
|||
|
|
covering the package.
|
|||
|
|
|
|||
|
|
Example::
|
|||
|
|
|
|||
|
|
Copyright: Guido van Rossum, 1991
|
|||
|
|
Copyright: Python Software Foundation, 2005
|
|||
|
|
Copyright: Public Domain
|
|||
|
|
|
|||
|
|
|
|||
|
|
External References Registry
|
|||
|
|
============================
|
|||
|
|
|
|||
|
|
Stores in the `Cheese Shop`_ database a list of (name, description,
|
|||
|
|
URI) identifying an external reference that may be used as a value in
|
|||
|
|
a Requires-External field.
|
|||
|
|
|
|||
|
|
The name and description are required, but URI is not (as there is no
|
|||
|
|
single useful URI for "C").
|
|||
|
|
|
|||
|
|
Submissions to the registry are open to the community, and may be performed
|
|||
|
|
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
|
|||
|
|
packaging system.
|
|||
|
|
|
|||
|
|
XXX command-line interface needs work, obviously
|
|||
|
|
|
|||
|
|
|
|||
|
|
References
|
|||
|
|
==========
|
|||
|
|
|
|||
|
|
This document specifies version 1.2 of the metadata format.
|
|||
|
|
Version 1.0 is specified in PEP 241.
|
|||
|
|
Version 1.1 is specified in PEP 314.
|
|||
|
|
|
|||
|
|
.. [1] reStructuredText markup:
|
|||
|
|
http://docutils.sourceforge.net/
|
|||
|
|
|
|||
|
|
.. _`Cheese Shop`: http://cheeseshop.python.org/
|
|||
|
|
|
|||
|
|
|
|||
|
|
Copyright
|
|||
|
|
=========
|
|||
|
|
|
|||
|
|
This document has been placed in the public domain.
|
|||
|
|
|
|||
|
|
|
|||
|
|
Acknowledgements
|
|||
|
|
================
|
|||
|
|
|
|||
|
|
Fred Drake, Anthony Baxter and Matthias Klose have all contributed to
|
|||
|
|
the ideas presented in this PEP.
|
|||
|
|
|
|||
|
|
|
|||
|
|
..
|
|||
|
|
Local Variables:
|
|||
|
|
mode: indented-text
|
|||
|
|
indent-tabs-mode: nil
|
|||
|
|
sentence-end-double-space: t
|
|||
|
|
fill-column: 70
|
|||
|
|
End:
|