PEP: 243
Title: Module Repository Upload Mechanism
Version: $Revision$
Author: jafo-pep@tummy.com (Sean Reifschneider)
Status: Draft
Type: Standards Track
Created: 18-Mar-2001
Python-Version: 2.1
Post-History: 
Discussions-To: distutils-sig@python.org


Abstract

    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 "setup.py sdist"),
    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.


Upload Process

    The upload will include the Distutils "PKG-INFO" meta-data
    information (as specified in PEP-241 [1]), 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.

    The upload will be made to the host "modules.python.org" on port
    80/tcp.  The form will consist of the following fields:

	distribution -- The file containing the module software (for
	example, a .tar.gz or .zip file).

	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 -- The file containing the distribution meta-data (as
	specified in PEP-241 [1]).

	infomd5sum -- 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>".

	signature (optional) -- A GPG signature of the uploaded
	distribution as signed by the author.  This may be used by the
	cataloging system to automate acceptance of uploads.


Return Data

    The upload will report the status of the upload by sending the
    string "Upload status:" followed by one of 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...

    Following the above string may be a human-readable string
    providing further information.  This message continues to the end
    of the returned data-stream.

    Returned data which does not fit the above format should be
    treated as a temporary failure.


Sample Form

    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="swalowpost.cgi"
	      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="SUBMIT" VALUE="Upload">
	</FORM>


Platforms

    The following are valid os names:

	debian
	hpux
	mandrake
	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, "nt" (Windows), "9.04"
    (HP-UX), "7.0" (RedHat, Mandrake).

    The following are valid architectures:

	alpha
	hppa
	ix86
	powerpc
	sparc
	ultrasparc


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's PEP-241 [1] 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.


References

    [1] Metadata for Python Software Package, Kuchling,
        http://python.sourceforge.net/peps/pep-0241.html


Copyright

    This document has been placed in the public domain.


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