A typical usage is to get in the package root in a shell and type :

$ python setup.py register sdist upload

This command will register the package to PyPI, using the arguments passed to the setup function in setup.py. These arguments are the meta-data of the package, like the name of the package, its version etc. (see the Distutils documentation for the meta-data list). After it's registered, a source distribution is created locally, using the sdist command, then uploaded to PyPI.

For Python versions older than 2.6 you also need collective.dist, as detailed later in this document

To make these commands work, a .pypirc file has to be added in your home, as described in the Distutils documentation.

The Plone.org Products section, based on PloneSoftwareCenter, is now compatible with this protocol, and you can register and upload your packages there using the same command, as long as you configure properly your .pypirc file :

[distutils]
index-servers =
    pypi
    plone.org

[pypi]
username:user
password:password

[plone.org]
repository:http://plone.org/products
username:ploneuser
password:password 

With this configuration, you will be able to publish your work to PyPI and/or Plone.org. The -r option will let you point the server to use. If your want to push your package to Plone.org, the command is:

$ python setup.py register sdist upload -r plone.org

And for PyPI :

$ python setup.py register sdist upload -r pypi

These commands will create an entry for your package, create a .tar.gz and upload it to whichever repository you chose.  Only the register and upload commands are effected by the -r flag; you can use any other commands as normal regardless of which package index you're uploading to.

N.B.: If no repository is specified PyPI will be used, not Plone.org

But the multiple-server .pypirc configuration is a Python 2.6 feature, and since Plone 3 and Zope 2.10 runs on Python 2.4, you need to use an alternative package if you are unable to use Python 2.6 in your environment yet. Plone 4 runs on Zope 2.12, which uses Python 2.6.

collective.dist adds two new commands for this purpose under Python 2.4 and 2.5:

• mupload: Distutils command which allows uploading packages to multiple servers under Python 2.4 and 2.5. Replaces the upload command.
  
• mregister: Distutils command which allows uploading packages to multiple servers under Python 2.4 and 2.5. Replaces the register command.
  

 To install collective.dist, you can use easy_install or pip :

$ easy_install collective.dist

 From there, you will be able to configure your .pypirc file and work woth both Plone.org and PyPI. As long as you use mregister and mupload

$ python setup.py mregister sdist mupload -r plone.org

When you upload a package to plone.org using mregister and mupload, PloneSoftwareCenter will look for a project that contains the name of the package in the distutils id field or in the distutils secondary ids field list.

These fields are located in the edit panel, in the Distutils tab. The following screenshot is showing the configuration of the collective.dist project on plone.org.

Each project can hold one or several distutils names. The best practice is to set the name of the main package of the project in the distutils id field, and to add extra names into the distutils secondary ids list. When you add a name, PloneSoftwareCenter makes sure it's not already used by another project.

If you upload a package and there's no project holding its name, a new project will be created, using this name.

Last, the long_description argument of the package configured in the distutils id field will be used for the project front page, like PyPI does.

Notice that you can use the --strict option of the mregister command in order to make sure long_description is reSt compliant:

$ python setup.py mregister --strict sdist upload 

It will stop and display the reSt parser errors.

When you are working with Plone Add-on products the best practice is to upload your releases to PyPI and Plone.org. 

Since all Plone packages are based on Setuptools, you can create two aliases to make commands shorter :

$ python setup.py alias plone_release mregister sdist mupload -r plone.org
$ python setup.py alias pypi_release mregister sdist mupload 

Setuptools will create in setup.cfg two aliases, and you will be able to register and upload your package with plone_release and pypi_release, wich is shorter;

$ python setup.py plone_release 
$ python setup.py pypi_release

When you upload a package at Plone.org, a copy is immediatly stored and made available at http://dist.plone.org/packages

Add this url to your find-links variable in your buildout configuration:

[buildout]

find-links =
   http://dist.plone.org/packages