6.The Python Package Index (PyPI)

ThePython Package Index (PyPI) storesmeta-datadescribing distributions packaged with distutils, as well as package data likedistribution files if a package author wishes.

Distutils provides theregister andupload commands forpushing meta-data and distribution files to PyPI, respectively. SeeDistutils commands for information on these commands.

6.1.PyPI overview

PyPI lets you submit any number of versions of your distribution to the index.If you alter the meta-data for a particular version, you can submit it againand the index will be updated.

PyPI holds a record for each (name, version) combination submitted. The firstuser to submit information for a given name is designated the Owner of thatname. Changes can be submitted through theregister command orthrough the web interface. Owners can designate other users as Owners orMaintainers. Maintainers can edit the package information, but not designatenew Owners or Maintainers.

By default PyPI displays only the newest version of a given package. The webinterface lets one change this default behavior and manually select whichversions to display and hide.

For each version, PyPI displays a home page. The home page is created fromthelong_description which can be submitted via theregistercommand. SeePyPI package display for more information.

6.2.Distutils commands

Distutils exposes two commands for submitting package data to PyPI: theregister command for submitting meta-data to PyPIand theupload command for submitting distributionfiles. Both commands read configuration data from a special file called a.pypirc file.

6.2.1.Theregister command

The distutils commandregister is used to submit your distribution’smeta-data to an index server. It is invoked as follows:

pythonsetup.pyregister

Distutils will respond with the following prompt:

runningregisterWeneedtoknowwhoyouare,sopleasechooseeither:1.useyourexistinglogin,2.registerasanewuser,3.havetheservergenerateanewpasswordforyou(andemailittoyou),or4.quitYourselection[default1]:

Note: if your username and password are saved locally, you will not see thismenu. Also, refer toThe .pypirc file for how to store your credentials in a.pypirc file.

If you have not registered with PyPI, then you will need to do so now. Youshould choose option 2, and enter your details as required. Soon aftersubmitting your details, you will receive an email which will be used to confirmyour registration.

Once you are registered, you may choose option 1 from the menu. You will beprompted for your PyPI username and password, andregister will thensubmit your meta-data to the index.

SeeAdditional command options for options to theregister command.

6.2.2.Theupload command

The distutils commandupload pushes the distribution files to PyPI.

The command is invoked immediately after building one or more distributionfiles. For example, the command

pythonsetup.pysdistbdist_wininstupload

will cause the source distribution and the Windows installer to be uploaded toPyPI. Note that these will be uploaded even if they are built using an earlierinvocation ofsetup.py, but that only distributions named on the commandline for the invocation including theupload command are uploaded.

If aregister command was previously called in the same command,and if the password was entered in the prompt,upload will reuse theentered password. This is useful if you do not want to store a password inclear text in a.pypirc file.

You can use the--sign option to tellupload to sign eachuploaded file using GPG (GNU Privacy Guard). Thegpg program mustbe available for execution on the systemPATH. You can also specifywhich key to use for signing using the--identity=name option.

SeeAdditional command options for additional options to theuploadcommand.

6.2.3.Additional command options

This section describes options common to both theregister andupload commands.

The--repository or-r option lets you specify a PyPI serverdifferent from the default. For example:

pythonsetup.pysdistbdist_wininstupload-rhttps://example.com/pypi

For convenience, a name can be used in place of the URL when the.pypirc file is configured to do so. For example:

pythonsetup.pyregister-rother

SeeThe .pypirc file for more information on defining alternate servers.

The--show-response option displays the full response text from the PyPIserver, which is useful when debugging problems with registering and uploading.

6.2.4.The.pypirc file

Theregister andupload commands both check for theexistence of a.pypirc file at the location$HOME/.pypirc.If this file exists, the command uses the username, password, and repositoryURL configured in the file. The format of a.pypirc file is asfollows:

[distutils]index-servers=pypi[pypi]repository:<repository-url>username:<username>password:<password>

Thedistutils section defines anindex-servers variable that lists thename of all sections describing a repository.

Each section describing a repository defines three variables:

  • repository, that defines the url of the PyPI server. Defaults to

    https://upload.pypi.org/legacy/.

  • username, which is the registered username on the PyPI server.

  • password, that will be used to authenticate. If omitted the user

    will be prompt to type it when needed.

If you want to define another server a new section can be created andlisted in theindex-servers variable:

[distutils]index-servers=pypiother[pypi]repository:<repository-url>username:<username>password:<password>[other]repository:https://example.com/pypiusername:<username>password:<password>

This allows theregister andupload commands to becalled with the--repository option as described inAdditional command options.

Specifically, you might want to add thePyPI Test Repository to your.pypirc to facilitatetesting before doing your first upload toPyPI itself.

6.3.PyPI package display

Thelong_description field plays a special role at PyPI. It is used bythe server to display a home page for the registered package.

If you use thereStructuredTextsyntax for this field, PyPI will parse it and display an HTML output forthe package home page.

Thelong_description field can be attached to a text file locatedin the package:

fromdistutils.coreimportsetupwithopen('README.txt')asfile:long_description=file.read()setup(name='Distutils',long_description=long_description)

In that case,README.txt is a regular reStructuredText text file locatedin the root of the package besidessetup.py.

To prevent registering broken reStructuredText content, you can use therst2html program that is provided by thedocutils package andcheck thelong_description from the command line:

$pythonsetup.py--long-description|rst2html.py>output.html

docutils will display a warning if there’s something wrong with yoursyntax. Because PyPI applies additional checks (e.g. by passing--no-rawtorst2html.py in the command above), being able to run the command abovewithout warnings does not guarantee that PyPI will convert the contentsuccessfully.