How to upload your package to Plone.org
This tutorial explains how to distribute your packages to Plone.org using the standard Distutils commands.
Setting up .pypirc
explains how to setup your .pypirc file to work with Plone.org and PyPI
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 :
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 affected 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
explains how to install collective.dist to be able to use your .pypirc file under Python 2.4 and 2.5
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.
$ 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
Setting up your plone.org project
explains how to set up your Plone.org project so it gets your packages.
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.
explains how to use the setuptools alias command to simplify the work
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
Using Plone.org in your buildout
explains how to use Plone.org as a package source
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: