PEP 243 – Module Repository Upload Mechanism
- Sean Reifschneider <jafo-pep at tummy.com>
- Distutils-SIG list
- Standards Track
- 20-Mar-2001, 24-Mar-2001
For a module repository system (such as Perl’s CPAN) to be
successful, it must be as easy as possible for module authors to
submit their work. An obvious place for this submit to happen is
in the Distutils tools after the distribution archive has been
successfully created. For example, after a module author has
tested their software (verifying the results of
they might type
setup.py sdist --submit. This would flag
Distutils to submit the source distribution to the archive server
for inclusion and distribution to the mirrors.
This PEP only deals with the mechanism for submitting the software distributions to the archive, and does not deal with the actual archive/catalog server.
The upload will include the Distutils
information (as specified in PEP 241), the actual software
distribution, and other optional information. This information
will be uploaded as a multi-part form encoded the same as a
regular HTML file upload request. This form is posted using
ENCTYPE="multipart/form-data" encoding (RFC 1867).
The upload will be made to the host “www.python.org” on port
POST http://www.python.org:80/pypi). The form
will consist of the following fields:
distribution– The file containing the module software (for example, a
distmd5sum– The MD5 hash of the uploaded distribution, encoded in ASCII representing the hexadecimal representation of the digest (
for byte in digest: s = s + ('%02x' % ord(byte))).
pkginfo(optional) – The file containing the distribution meta-data (as specified in PEP 241). Note that if this is not included, the distribution file is expected to be in
.tarformat (gzipped and bzipped compressed are allowed) or
.zipformat, with a
PKG-INFOfile in the top-level directory it extracts (
infomd5sum(required if pkginfo field is present) – The MD5 hash of the uploaded meta-data, encoded in ASCII representing the hexadecimal representation of the digest (
for byte in digest: s = s + ('%02x' % ord(byte))).
platform(optional) – A string representing the target platform for this distribution. This is only for binary distributions. It is encoded as
<os_name>-<os_version>-<platform architecture>-<python version>.
signature(optional) – A OpenPGP-compatible signature of the uploaded distribution as signed by the author. This may be used by the cataloging system to automate acceptance of uploads.
protocol_version– A string indicating the protocol version that the client supports. This document describes protocol version “1”.
The status of the upload will be reported using HTTP non-standard
X-*) headers. The
X-Swalow-Status header may have the following
SUCCESS– Indicates that the upload has succeeded.
FAILURE– The upload is, for some reason, unable to be processed.
TRYAGAIN– The server is unable to accept the upload at this time, but the client should try again at a later time. Potential causes of this are resource shortages on the server, administrative down-time, etc…
Optionally, there may be a
X-Swalow-Reason header which includes a
human-readable string which provides more detailed information about
If there is no
X-Swalow-Status header, or it does not contain one of
the three strings above, it should be treated as a temporary failure.
>>> f = urllib.urlopen('http://www.python.org:80/pypi') >>> s = f.headers['x-swalow-status'] >>> s = s + ': ' + f.headers.get('x-swalow-reason', '<None>') >>> print s FAILURE: Required field "distribution" missing.
The upload client must submit the page in the same form as Netscape Navigator version 4.76 for Linux produces when presented with the following form:
<H1>Upload file</H1> <FORM NAME="fileupload" METHOD="POST" ACTION="pypi" ENCTYPE="multipart/form-data"> <INPUT TYPE="file" NAME="distribution"><BR> <INPUT TYPE="text" NAME="distmd5sum"><BR> <INPUT TYPE="file" NAME="pkginfo"><BR> <INPUT TYPE="text" NAME="infomd5sum"><BR> <INPUT TYPE="text" NAME="platform"><BR> <INPUT TYPE="text" NAME="signature"><BR> <INPUT TYPE="hidden" NAME="protocol_version" VALUE="1"><BR> <INPUT TYPE="SUBMIT" VALUE="Upload"> </FORM>
The following are valid os names:
aix beos debian dos freebsd hpux mac macos mandrake netbsd openbsd qnx redhat solaris suse windows yellowdog
The above include a number of different types of distributions of Linux. Because of versioning issues these must be split out, and it is expected that when it makes sense for one system to use distributions made on other similar systems, the download client will make the distinction.
Version is the official version string specified by the vendor for the particular release. For example, “2000” and “nt” (Windows), “9.04” (HP-UX), “7.0” (RedHat, Mandrake).
The following are valid architectures:
alpha hppa ix86 powerpc sparc ultrasparc
I currently have a proof-of-concept client and server implemented. I plan to have the Distutils patches ready for the 2.1 release. Combined with Andrew’s PEP 241 for specifying distribution meta-data, I hope to have a platform which will allow us to gather real-world data for finalizing the catalog system for the 2.2 release.
This document has been placed in the public domain.
Last modified: 2023-09-09 17:39:29 GMT