[Catalog-sig] PEP 241 draft
Tue, 13 Mar 2001 11:08:35 -0500
[Followups set to email@example.com, since that's where most of
the posters are.]
I've checked in a first draft of PEP 241. Here it is; please offer
comments and changes.
Title: Metadata for Python Software Packages
Version: $Revision: 1.1 $
Author: A.M. Kuchling <firstname.lastname@example.org>
Type: Standards Track
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 METADATA
and will be placed in the top directory of the source
distribution (where the README, INSTALL, and other files usually
Authors might expect to include a METADATA file of their own that
would be used instead of the generated file, but this will not be
permitted. It would be confusing if person B makes a custom
release of person A's software, modifies setup.py accordingly, but
uses identical metadata because person B didn't delete the
METADATA file. When running the 'sdist' command, a user-supplied
METADATA file will be ignored and a warning about this action will
XXX are we sure RFC-822 is enough?
The METADATA 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.
This section specifies the names and semantics of each of the
supported metadata fields.
The name of the package. XXX what's the set of legal characters?
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
A (XXX whitespace? comma?)-separated list of platform
specifications. Platform specifications are limited to the
XXX copy list from PPD? SourceForge?
A one-line summary of what the package does.
Example: "A module for collecting votes from beagles."
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
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.'
A list of additional keywords to be used to assist searching
for this package in a larger catalog.
XXX Keywords should probably be constrained to be from a fixed
list, but I don't think this can be enforced by the 'sdist'
command. (The list might be large, and it could only be updated
with new Distutils releases, which seems too inflexible.)
Example: 'dog puppy voting election'
A string containing the URL for the package's home page.
A string containing at a minimum the author's name. Contact
information can also be added, separating each line with
Example: 'C. Schultz\nUniversal Features Syndicate\nLos Angeles, CA'
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 ("name <email>" or "email (name)"). 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*. Author-related metadata fields are not covered by
this PEP. (XXX should they be? I think not, since nothing in
this PEP will deal with author data at all.)
Example: 'C. Schultz <email@example.com>'
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:
XXX copy list from SourceForge, + 'Other'
This document has been placed in the public domain.