Web Interface

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

The store has columns for all metadata fields. The (name, version)double is used as a uniqueness key. Additional submissions for anexisting (name, version) will result in anupdate 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 customisethe index view. The index will include a browsing interface likethat presented in the Trove interface design section 4.3. Theresults will be paginated, sorted alphabetically and only showingthe most recent version. The most recent version information willbe determined using the Distutils LooseVersion class.

display

Displays information about the package. All fields are displayed asplain 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 identifyan entry in the index.Submit will automatically determinewhether to create a new entry or update an existing entry. Themetadata is checked for correctness where appropriate - specificallythe Trove discriminators are compared with the allowed set. Anupdate will update all information about the package based on thenew submitted information.

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

submit_pkg_info

Accepts a POST submission of a PKG-INFO file and performs the samefunction as thesubmit interface.

user

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

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

Registration will be a three-step process, involving:

1. User submission of details via the Distutilsregister commandor through the web,
2. Index server sending email to the user’s email address with a URLto 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’spassword and sends an email with the new password to the user.

Thesubmit command will require HTTP Basic authentication,preferably over an HTTPS connection.

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

User Roles

Three user Roles will be assignable to users:

Owner

Owns a package name, may assign Maintainer Role for that name. Thefirst user to register information about a package is deemed Ownerof 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 apackage name.

Index Storage (Schema)

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

packages

Lists package names and holds package-level metadata (currentlyjust the stable release version)

releases

Each package has an entry inreleases for each version of thepackage that is released. A row holds the bulk of the informationgiven in the package’s PKG-INFO file. There is one row for eachpackage (name,version).

trove_discriminators

Lists the Trove discriminator text and assigns each one a uniqueID.

release_discriminators

Each entry maps a package (name,version) to adiscriminator_id. We map to releases instead of packages becausethe set of discriminators may change between releases.

journals

Holds information about changes to package information in theindex. Changes to thepackages,releases,roles,andrelease_discriminators tables are listed here bypackagename andversion if the change is release-specific.

users

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

roles

Mapsuser_name androle_name to apackage_name.

An additional table,rego_otk holds the One Time Keys generatedduring registration and is not interesting in the scope of the indexitself.

Distutilsregister Command

An additional Distutils command,register, is implemented whichposts the package metadata to the central index. Theregistercommand automatically handles user registration; the user is presentedwith 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 userwill be prompted at exit to save their username/password to a filein their$HOME directory in the file.pypirc.

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

Theregister command will include a--verify option whichperforms a test submission to the index without actually committingthe data. The index will perform its submission verification checksas usual and report any errors it would have reported during a normalsubmission. This is useful for verifying correctness of Trovediscriminators.

Distutils Trove Classification

The Trove concept ofdiscrimination will be added to the metadataset available to package authors through the new attribute“classifiers”. The list of classifiers will be available through theweb, 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 classificationentries due to the deep nesting that would be involved in a moreformal Python structure.

The original Trove specification that classification namespaces beseparated by slashes (“/”) unfortunately collides with many of thenames having slashes in them (e.g. “OS/2”). The double-colon solution(” :: “) implemented by SourceForge and FreshMeat gets around thislimitation.

The list of classification values on the module index has been mergedfrom FreshMeat and SourceForge (with their permission). This listwill be made available both through the web interface and through theregister command’s--list-classifiers option as a text listwhich may then be copied to thesetup.py file. Theregistercommand’s--verify option will check classifiers values againstthe server’s list.

Unfortunately, the addition of the “classifiers” property is notbackwards-compatible. A setup.py file using it will not work underPython 2.1.3. It is hoped that a bug-fix release of Python 2.2 (mostlikely 2.2.3) will relax the argument checking of the setup() commandto allow new keywords, even if they’re not actually used. It ispreferable that a warning be produced, rather than a show-stoppingerror. The use of the new keyword should be discouraged in situationswhere the package is advertised as being compatible with pythonversions earlier than 2.2.3 or 2.3.

In the PKG-INFO, the classifiers list items will appear as individualClassifier: entries:

Name:roundupVersion:0.5.2Classifier:DevelopmentStatus::4-BetaClassifier:Environment::Console(TextBased)..Classifier:Topic::SoftwareDevelopment::BugTrackingUrl:http://sourceforge.net/projects/roundup/