[Catalog-sig] PEP 241 draft

[Andrew Kuchling]

[Followups set to distutils-sig@python.org, 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.

PEP: 241
Title: Metadata for Python Software Packages
Version: $Revision: 1.1 $
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 METADATA
    and will be placed in the top directory of the source
    distribution (where the README, INSTALL, and other files usually
    go).

    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
    be printed.

    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.
    

Fields

    This section specifies the names and semantics of each of the
    supported metadata fields.
    
    Name

      The name of the package.  XXX what's the set of legal characters?

      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'
      
    Description

      A one-line summary of what the package does.

      Example: "A module for collecting votes from beagles."
      
    Long-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.

      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'
      
    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 ("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 <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:

        XXX copy list from SourceForge, + 'Other'


Copyright

    This document has been placed in the public domain.



Local Variables:
mode: indented-text
indent-tabs-mode: nil
End: