python-peps/peps/pep-0301.rst

PEP: 301
Title: Package Index and Metadata for Distutils
Version: $Revision$
Last-Modified: $Date$
Author: Richard Jones <richard@python.org>
Status: Final
Type: Standards Track
Topic: Packaging
Content-Type: text/x-rst
Created: 24-Oct-2002
Python-Version: 2.3
Post-History: 08-Nov-2002


Abstract
========

This PEP proposes several extensions to the Distutils packaging system
[1]_.  These enhancements include a central package index server,
tools for submitting package information to the index and extensions
to the package metadata to include Trove [2]_ information.

This PEP does not address issues of package dependency.  It also does
not address storage and download of packages as described in :pep:`243`.
Nor is it proposing a local database of packages as described
in :pep:`262`.

Existing package repositories such as the Vaults of Parnassus [3]_,
CPAN [4]_ and PAUSE [5]_ will be investigated as prior art in this
field.


Rationale
=========

Python programmers have long needed a simple method of discovering
existing modules and systems available for their use.  It is arguable
that the existence of these systems for other languages have been a
significant contribution to their popularity.  The existence of the
Catalog-SIG, and the many discussions there indicate that there is a
large population of users who recognise this need.

The introduction of the Distutils packaging system to Python
simplified the process of distributing shareable code, and included
mechanisms for the capture of package metadata, but did little with
the metadata save ship it with the package.

An interface to the index should be hosted in the python.org domain,
giving it an air of legitimacy that existing catalog efforts do not
have.

The interface for submitting information to the catalog should be as
simple as possible - hopefully just a one-line command for most users.

Issues of package dependency are not addressed due to the complexity
of such a system.  :pep:`262` proposes such a system, but as of this
writing the PEP is still unfinished.

Issues of package dissemination (storage on a central server) are
not addressed because they require assumptions about availability of
storage and bandwidth that I am not in a position to make.  :pep:`243`,
which is still being developed, is tackling these issues and many
more.  This proposal is considered compatible with, and adjunct to
the proposal in :pep:`243`.


Specification
=============

The specification takes three parts, the `web interface`_,  the
`Distutils register command`_ and the `Distutils Trove
classification`_.


Web Interface
-------------

A web interface is implemented over a simple store.  The interface is
available through the python.org domain, either directly or as
packages.python.org.

The store has columns for all metadata fields.  The (name, version)
double is used as a uniqueness key.  Additional submissions for an
existing (name, version) will result in an *update* operation.

The web interface implements the following commands/interfaces:

**index**
  Lists known packages, optionally filtered.  An additional HTML page,
  **search**, presents a form to the user which is used to customise
  the index view.  The index will include a browsing interface like
  that presented in the Trove interface design section 4.3.  The
  results will be paginated, sorted alphabetically and only showing
  the most recent version.  The most recent version information will
  be determined using the Distutils LooseVersion class.

**display**
  Displays information about the package.  All fields are displayed as
  plain text.  The "url" (or "home_page") field is hyperlinked.

**submit**
  Accepts a POST submission of metadata about a package.  The
  "name" and "version" fields are mandatory, as they uniquely identify
  an entry in the index.  **Submit** will automatically determine
  whether to create a new entry or update an existing entry.  The
  metadata is checked for correctness where appropriate - specifically
  the Trove discriminators are compared with the allowed set.  An
  update will update all information about the package based on the
  new submitted information.

  There will also be a submit/edit form that will allow manual
  submission and updating for those who do not use Distutils.

**submit_pkg_info**
  Accepts a POST submission of a PKG-INFO file and performs the same
  function as the **submit** interface.

**user**
  Registers a new user with the index.  Requires username, password
  and email address.  Passwords will be stored in the index database
  as SHA hashes.  If the username already exists in the database:

  1. If valid HTTP Basic authentication is provided, the password and
     email address are updated with the submission information, or
  2. If no valid authentication is provided, the user is informed that
     the login is already taken.

  Registration will be a three-step process, involving:

  1. User submission of details via the Distutils *register* command
     or through the web,
  2. Index server sending email to the user's email address with a URL
     to visit to confirm registration with a random one-time key, and
  3. User visits URL with the key and confirms registration.

**roles**
  An interface for changing user Role assignments.

**password_reset**
  Using a supplied email address as the key, this resets a user's
  password and sends an email with the new password to the user.

The **submit** command will require HTTP Basic authentication,
preferably over an HTTPS connection.

The server interface will indicate success or failure of the commands
through a subset of the standard HTTP response codes:

===== ============== ================================================
Code  Meaning        Register command implications
===== ============== ================================================
200   OK             Everything worked just fine
400   Bad request    Data provided for submission was malformed
401   Unauthorised   The username or password supplied were incorrect
403   Forbidden      User does not have permission to update the
                     package information (not Owner or Maintainer)
===== ============== ================================================

User Roles
----------

Three user Roles will be assignable to users:

Owner
  Owns a package name, may assign Maintainer Role for that name.  The
  first user to register information about a package is deemed Owner
  of the package name.  The Admin user may change this if necessary.
  May submit updates for the package name.

Maintainer
  Can submit and update info for a particular package name.

Admin
  Can assign Owner Role and edit user details. Not specific to a
  package name.


Index Storage (Schema)
----------------------

The index is stored in a set of relational database tables:

**packages**
  Lists package names and holds package-level metadata (currently
  just the stable release version)

**releases**
  Each package has an entry in **releases** for each version of the
  package that is released. A row holds the bulk of the information
  given in the package's PKG-INFO file. There is one row for each
  package (*name*, *version*).

**trove_discriminators**
  Lists the Trove discriminator text and assigns each one a unique
  ID.

**release_discriminators**
  Each entry maps a package (*name*, *version*) to a
  *discriminator_id*.  We map to releases instead of packages because
  the set of discriminators may change between releases.

**journals**
  Holds information about changes to package information in the
  index. Changes to the **packages**, **releases**, **roles**,
  and **release_discriminators** tables are listed here by
  package *name* and *version* if the change is release-specific.

**users**
  Holds our user database - user name, email address and password.

**roles**
  Maps *user_name* and *role_name* to a *package_name*.

An additional table, **rego_otk** holds the One Time Keys generated
during registration and is not interesting in the scope of the index
itself.


Distutils *register* Command
----------------------------

An additional Distutils command, ``register``, is implemented which
posts the package metadata to the central index.  The *register*
command automatically handles user registration; the user is presented
with three options:

1. login and submit package information
2. register as a new packager
3. send password reminder email

On systems where the ``$HOME`` environment variable is set, the user
will be prompted at exit to save their username/password to a file
in their ``$HOME`` directory in the file ``.pypirc``.

Notification of changes to a package entry will be sent to all users
who have submitted information about the package.  That is, the
original submitter and any subsequent updaters.

The *register* command will include a ``--verify`` option which
performs a test submission to the index without actually committing
the data.  The index will perform its submission verification checks
as usual and report any errors it would have reported during a normal
submission.  This is useful for verifying correctness of Trove
discriminators.


Distutils Trove Classification
------------------------------

The Trove concept of *discrimination* will be added to the metadata
set available to package authors through the new attribute
"classifiers".  The list of classifiers will be available through the
web, and added to the package like so::

    setup(
        name = "roundup",
        version = __version__,
        classifiers = [
            'Development Status :: 4 - Beta',
            'Environment :: Console',
            'Environment :: Web Environment',
            'Intended Audience :: End Users/Desktop',
            'Intended Audience :: Developers',
            'Intended Audience :: System Administrators',
            'License :: OSI Approved :: Python Software Foundation License',
            'Operating System :: MacOS :: MacOS X',
            'Operating System :: Microsoft :: Windows',
            'Operating System :: POSIX',
            'Programming Language :: Python',
            'Topic :: Communications :: Email',
            'Topic :: Office/Business',
            'Topic :: Software Development :: Bug Tracking',
        ],
        url = 'http://sourceforge.net/projects/roundup/',
        ...
    )

It was decided that strings would be used for the classification
entries due to the deep nesting that would be involved in a more
formal Python structure.

The original Trove specification that classification namespaces be
separated by slashes ("/") unfortunately collides with many of the
names having slashes in them (e.g. "OS/2").  The double-colon solution
(" :: ") implemented by SourceForge and FreshMeat gets around this
limitation.

The list of classification values on the module index has been merged
from FreshMeat and SourceForge (with their permission).  This list
will be made available both through the web interface and through the
*register* command's ``--list-classifiers`` option as a text list
which may then be copied to the ``setup.py`` file.  The *register*
command's ``--verify`` option will check classifiers values against
the server's list.

Unfortunately, the addition of the "classifiers" property is not
backwards-compatible.  A setup.py file using it will not work under
Python 2.1.3.  It is hoped that a bug-fix release of Python 2.2 (most
likely 2.2.3) will relax the argument checking of the setup() command
to allow new keywords, even if they're not actually used.  It is
preferable that a warning be produced, rather than a show-stopping
error. The use of the new keyword should be discouraged in situations
where the package is advertised as being compatible with python
versions earlier than 2.2.3 or 2.3.

In the PKG-INFO, the classifiers list items will appear as individual
``Classifier:`` entries::

        Name: roundup
        Version: 0.5.2
        Classifier: Development Status :: 4 - Beta
        Classifier: Environment :: Console (Text Based)
                    .
                    .
        Classifier: Topic :: Software Development :: Bug Tracking
        Url: http://sourceforge.net/projects/roundup/


Implementation
==============

The server is available at:

  http://www.python.org/pypi

The code is available from the SourceForge project:

  http://sourceforge.net/projects/pypi/

The *register* command has been integrated into Python 2.3.


Rejected Proposals
==================

Originally, the index server was to return custom headers (inspired by
:pep:`243`):

**X-Pypi-Status**
  Either "success" or "fail".

**X-Pypi-Reason**
  A description of the reason for failure, or additional information
  in the case of a success.

However, it has been pointed out [6]_ that this is a bad scheme to
use.


References
==========

.. [1] Distutils packaging system
   (http://docs.python.org/library/distutils.html)

.. [2] Trove
   (http://www.catb.org/~esr/trove/)

.. [3] Vaults of Parnassus
   (http://www.vex.net/parnassus/)

.. [4] CPAN
   (http://www.cpan.org/)

.. [5] PAUSE
   (http://pause.cpan.org/)

.. [6] [PEP243] upload status is bogus
   (https://mail.python.org/pipermail/distutils-sig/2001-March/002262.html)


Copyright
=========

This document has been placed in the public domain.


Acknowledgements
================

Anthony Baxter, Martin v. Loewis and David Goodger for encouragement
and feedback during initial drafting.

A.M. Kuchling for support including hosting the second prototype.

Greg Stein for recommending that the register command interpret the
HTTP response codes rather than custom X-PyPI-* headers.

The many participants of the Distutils and Catalog SIGs for their
ideas over the years.


..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   End: