178 lines
5.8 KiB
Plaintext
178 lines
5.8 KiB
Plaintext
PEP: 241
|
||
Title: Metadata for Python Software Packages
|
||
Version: $Revision$
|
||
Author: A.M. Kuchling <amk1@bigfoot.com>
|
||
Type: Standards Track
|
||
Created: 12-Mar-2001
|
||
Status: Draft
|
||
Post-History:
|
||
|
||
Introduction
|
||
|
||
This PEP specifies the names and semantics of the fields used to store
|
||
metadata about Python software packages.
|
||
|
||
|
||
Including Metadata in Packages
|
||
|
||
The Distutils 'sdist' command will be modified to extract the
|
||
metadata fields from the arguments and write them to a file in the
|
||
generated zipfile or tarball. This file will be named PKG-INFO
|
||
and will be placed in the top directory of the source
|
||
distribution (where the README, INSTALL, and other files usually
|
||
go).
|
||
|
||
Developers may not provide their own "PKG-INFO" file. The "sdist"
|
||
command will, if it detects an existing "PKG-INFO" file, terminate
|
||
with an appropriate error message. This should prevent confusion
|
||
caused by the "PKG-INFO" and "setup.py" files being out of sync.
|
||
|
||
The PKG-INFO file format is a single set of RFC-822 headers
|
||
parseable by the rfc822.py module. The field names listed in the
|
||
following section are used as the header names. There's no
|
||
extension mechanism in this simple format; the Catalog and Distutils
|
||
SIGs will aim at getting a more flexible format ready for Python 2.2.
|
||
|
||
|
||
Fields
|
||
|
||
This section specifies the names and semantics of each of the
|
||
supported metadata fields.
|
||
|
||
Metadata-Version
|
||
|
||
Version of the file format; currently "1.0" is the only
|
||
legal value here.
|
||
|
||
Example: '1.0'
|
||
|
||
Name
|
||
|
||
The name of the package.
|
||
|
||
Example: '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: '1.0a2'
|
||
|
||
Platforms
|
||
|
||
A (XXX whitespace? comma?)-separated list of platform
|
||
specifications. Platform specifications are limited to the
|
||
following list:
|
||
|
||
XXX copy list from PPD? SourceForge?
|
||
|
||
Example: 'XXX'
|
||
|
||
Summary
|
||
|
||
A one-line summary of what the package does.
|
||
|
||
Example: "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 one hopes that
|
||
people won't include their instruction manual as the
|
||
long-description.)
|
||
|
||
Example: '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
|
||
|
||
A list of additional keywords to be used to assist searching
|
||
for this package in a larger catalog.
|
||
|
||
Example: 'dog puppy voting election'
|
||
|
||
Home-page (optional)
|
||
|
||
A string containing the URL for the package's home page.
|
||
|
||
Example: 'http://www.example.com/~cschultz/bvote/'
|
||
|
||
Author (optional)
|
||
|
||
A string containing at a minimum the author's name. Contact
|
||
information can also be added, separating each line with
|
||
newlines.
|
||
|
||
Example: 'C. Schultz\nUniversal Features Syndicate\nLos 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: '"C. Schultz" <cschultz@example.com>'
|
||
|
||
License
|
||
|
||
A string selected from a short list of choices, specifying the
|
||
license covering the package. Some licenses result in the
|
||
software being freely redistributable, so packagers and
|
||
resellers can automatically know that they're free to
|
||
redistribute the software. Other licenses will require
|
||
a careful reading by a human to determine the software can be
|
||
repackaged and resold.
|
||
|
||
The choices are:
|
||
|
||
Artistic, BSD, DFSG, GNU PL, Lesser GNU PL, "MIT/X11",
|
||
Mozilla PL, "public domain", Python, Qt PL, Zope PL, unknown,
|
||
nocommercial, nosell, nosource, shareware, other
|
||
|
||
The definitions are:
|
||
Python Python 1.6 or higher license. Version 1.5.2 and
|
||
earlier are under the MIT/X11 license.
|
||
public domain Software is public domain, not copyrighted.
|
||
unknown Status is not known
|
||
nocommercial Free private use but commercial use not permitted
|
||
nosell Free use but distribution for profit by arrangement
|
||
nosource Freely distributable but no source code
|
||
shareware Payment is requested if software is used
|
||
other General category for other non-DFSG licenses
|
||
|
||
Some of these licenses can be interpreted to mean the software is
|
||
freely redistributable. The list of redistributable licenses is:
|
||
|
||
Artistic, BSD, DFSG, GNU PL, Lesser GNU PL, "MIT/X11",
|
||
Mozilla PL, "public domain", Python, Qt PL, Zope PL,
|
||
nosource, shareware
|
||
|
||
|
||
Note that being redistributable does not mean a package
|
||
qualifies as free software, 'nosource' and 'shareware' being
|
||
examples.
|
||
|
||
|
||
Copyright
|
||
|
||
This document has been placed in the public domain.
|
||
|
||
|
||
|
||
Local Variables:
|
||
mode: indented-text
|
||
indent-tabs-mode: nil
|
||
End:
|