Abstract

For a module repository system (such as Perl’s CPAN) to besuccessful, it must be as easy as possible for module authors tosubmit their work. An obvious place for this submit to happen isin the Distutils tools after the distribution archive has beensuccessfully created. For example, after a module author hastested their software (verifying the results ofsetup.pysdist),they might typesetup.pysdist--submit. This would flagDistutils to submit the source distribution to the archive serverfor inclusion and distribution to the mirrors.

This PEP only deals with the mechanism for submitting the softwaredistributions to the archive, and does not deal with the actualarchive/catalog server.

Upload Process

The upload will include the DistutilsPKG-INFO meta-datainformation (as specified inPEP 241), the actual softwaredistribution, and other optional information. This informationwill be uploaded as a multi-part form encoded the same as aregular HTML file upload request. This form is posted usingENCTYPE="multipart/form-data" encoding (RFC 1867).

The upload will be made to the host “www.python.org” on port80/tcp (POSThttp://www.python.org:80/pypi). The formwill consist of the following fields:

• distribution – The file containing the module software (forexample, a.tar.gz or.zip file).
• distmd5sum – The MD5 hash of the uploaded distribution,encoded in ASCII representing the hexadecimal representationof the digest (forbyteindigest:s=s+('%02x'%ord(byte))).
• pkginfo (optional) – The file containing the distributionmeta-data (as specified inPEP 241). Note that if this isnot included, the distribution file is expected to be in.tarformat (gzipped and bzipped compressed are allowed) or.zipformat, with aPKG-INFO file in the top-level directory itextracts (package-1.00/PKG-INFO).
• infomd5sum (required if pkginfo field is present) – The MD5 hashof the uploaded meta-data, encoded in ASCII representing thehexadecimal representation of the digest (forbyteindigest:s=s+('%02x'%ord(byte))).
• platform (optional) – A string representing the targetplatform for this distribution. This is only for binarydistributions. It is encoded as<os_name>-<os_version>-<platformarchitecture>-<pythonversion>.
• signature (optional) – AOpenPGP-compatible signature ofthe uploaded distribution as signed by the author. This maybe used by the cataloging system to automate acceptance ofuploads.
• protocol_version – A string indicating the protocol version thatthe client supports. This document describes protocol version “1”.

Return Data

The status of the upload will be reported using HTTP non-standard(X-*) headers. TheX-Swalow-Status header may have the followingvalues:

• SUCCESS – Indicates that the upload has succeeded.
• FAILURE – The upload is, for some reason, unable to beprocessed.
• TRYAGAIN – The server is unable to accept the upload at thistime, 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 aX-Swalow-Reason header which includes ahuman-readable string which provides more detailed information abouttheX-Swalow-Status.

If there is noX-Swalow-Status header, or it does not contain one ofthe three strings above, it should be treated as a temporary failure.

Example:

>>>f=urllib.urlopen('http://www.python.org:80/pypi')>>>s=f.headers['x-swalow-status']>>>s=s+': '+f.headers.get('x-swalow-reason','<None>')>>>printsFAILURE: Required field "distribution" missing.

Sample Form

The upload client must submit the page in the same form asNetscape Navigator version 4.76 for Linux produces when presentedwith the following form:

<H1>Uploadfile</H1><FORMNAME="fileupload"METHOD="POST"ACTION="pypi"ENCTYPE="multipart/form-data"><INPUTTYPE="file"NAME="distribution"><BR><INPUTTYPE="text"NAME="distmd5sum"><BR><INPUTTYPE="file"NAME="pkginfo"><BR><INPUTTYPE="text"NAME="infomd5sum"><BR><INPUTTYPE="text"NAME="platform"><BR><INPUTTYPE="text"NAME="signature"><BR><INPUTTYPE="hidden"NAME="protocol_version"VALUE="1"><BR><INPUTTYPE="SUBMIT"VALUE="Upload"></FORM>

Platforms

The following are valid os names:

aixbeosdebiandosfreebsdhpuxmacmacosmandrakenetbsdopenbsdqnxredhatsolarissusewindowsyellowdog

The above include a number of different types of distributions ofLinux. Because of versioning issues these must be split out, andit is expected that when it makes sense for one system to usedistributions made on other similar systems, the download clientwill make the distinction.

Version is the official version string specified by the vendor forthe particular release. For example, “2000” and “nt” (Windows),“9.04” (HP-UX), “7.0” (RedHat, Mandrake).

The following are valid architectures:

alphahppaix86powerpcsparcultrasparc

Status

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’sPEP 241 for specifying distributionmeta-data, I hope to have a platform which will allow us to gatherreal-world data for finalizing the catalog system for the 2.2release.

Copyright

This document has been placed in the public domain.