1.. index:: 2 single: Python Package Index (PyPI) 3 single: PyPI; (see Python Package Index (PyPI)) 4 5.. _package-index: 6 7******************************* 8The Python Package Index (PyPI) 9******************************* 10 11The `Python Package Index (PyPI)`_ stores :ref:`meta-data <meta-data>` 12describing distributions packaged with distutils, as well as package data like 13distribution files if a package author wishes. 14 15Distutils provides the :command:`register` and :command:`upload` commands for 16pushing meta-data and distribution files to PyPI, respectively. See 17:ref:`package-commands` for information on these commands. 18 19 20PyPI overview 21============= 22 23PyPI lets you submit any number of versions of your distribution to the index. 24If you alter the meta-data for a particular version, you can submit it again 25and the index will be updated. 26 27PyPI holds a record for each (name, version) combination submitted. The first 28user to submit information for a given name is designated the Owner of that 29name. Changes can be submitted through the :command:`register` command or 30through the web interface. Owners can designate other users as Owners or 31Maintainers. Maintainers can edit the package information, but not designate 32new Owners or Maintainers. 33 34By default PyPI displays only the newest version of a given package. The web 35interface lets one change this default behavior and manually select which 36versions to display and hide. 37 38For each version, PyPI displays a home page. The home page is created from 39the ``long_description`` which can be submitted via the :command:`register` 40command. See :ref:`package-display` for more information. 41 42 43.. _package-commands: 44 45Distutils commands 46================== 47 48Distutils exposes two commands for submitting package data to PyPI: the 49:ref:`register <package-register>` command for submitting meta-data to PyPI 50and the :ref:`upload <package-upload>` command for submitting distribution 51files. Both commands read configuration data from a special file called a 52:ref:`.pypirc file <pypirc>`. 53 54 55.. _package-register: 56 57The ``register`` command 58------------------------ 59 60The distutils command :command:`register` is used to submit your distribution's 61meta-data to an index server. It is invoked as follows:: 62 63 python setup.py register 64 65Distutils will respond with the following prompt:: 66 67 running register 68 We need to know who you are, so please choose either: 69 1. use your existing login, 70 2. register as a new user, 71 3. have the server generate a new password for you (and email it to you), or 72 4. quit 73 Your selection [default 1]: 74 75Note: if your username and password are saved locally, you will not see this 76menu. Also, refer to :ref:`pypirc` for how to store your credentials in a 77:file:`.pypirc` file. 78 79If you have not registered with PyPI, then you will need to do so now. You 80should choose option 2, and enter your details as required. Soon after 81submitting your details, you will receive an email which will be used to confirm 82your registration. 83 84Once you are registered, you may choose option 1 from the menu. You will be 85prompted for your PyPI username and password, and :command:`register` will then 86submit your meta-data to the index. 87 88See :ref:`package-cmdoptions` for options to the :command:`register` command. 89 90 91.. _package-upload: 92 93The ``upload`` command 94---------------------- 95 96.. versionadded:: 2.5 97 98The distutils command :command:`upload` pushes the distribution files to PyPI. 99 100The command is invoked immediately after building one or more distribution 101files. For example, the command :: 102 103 python setup.py sdist bdist_wininst upload 104 105will cause the source distribution and the Windows installer to be uploaded to 106PyPI. Note that these will be uploaded even if they are built using an earlier 107invocation of :file:`setup.py`, but that only distributions named on the command 108line for the invocation including the :command:`upload` command are uploaded. 109 110If a :command:`register` command was previously called in the same command, 111and if the password was entered in the prompt, :command:`upload` will reuse the 112entered password. This is useful if you do not want to store a password in 113clear text in a :file:`.pypirc` file. 114 115You can use the ``--sign`` option to tell :command:`upload` to sign each 116uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must 117be available for execution on the system :envvar:`PATH`. You can also specify 118which key to use for signing using the ``--identity=name`` option. 119 120See :ref:`package-cmdoptions` for additional options to the :command:`upload` 121command. 122 123 124.. _package-cmdoptions: 125 126Additional command options 127-------------------------- 128 129This section describes options common to both the :command:`register` and 130:command:`upload` commands. 131 132The ``--repository`` or ``-r`` option lets you specify a PyPI server 133different from the default. For example:: 134 135 python setup.py sdist bdist_wininst upload -r https://example.com/pypi 136 137For convenience, a name can be used in place of the URL when the 138:file:`.pypirc` file is configured to do so. For example:: 139 140 python setup.py register -r other 141 142See :ref:`pypirc` for more information on defining alternate servers. 143 144The ``--show-response`` option displays the full response text from the PyPI 145server, which is useful when debugging problems with registering and uploading. 146 147 148.. index:: 149 single: .pypirc file 150 single: Python Package Index (PyPI); .pypirc file 151 152.. _pypirc: 153 154The ``.pypirc`` file 155-------------------- 156 157The :command:`register` and :command:`upload` commands both check for the 158existence of a :file:`.pypirc` file at the location :file:`$HOME/.pypirc`. 159If this file exists, the command uses the username, password, and repository 160URL configured in the file. The format of a :file:`.pypirc` file is as 161follows:: 162 163 [distutils] 164 index-servers = 165 pypi 166 167 [pypi] 168 repository: <repository-url> 169 username: <username> 170 password: <password> 171 172The *distutils* section defines an *index-servers* variable that lists the 173name of all sections describing a repository. 174 175Each section describing a repository defines three variables: 176 177- *repository*, that defines the url of the PyPI server. Defaults to 178 ``https://www.python.org/pypi``. 179- *username*, which is the registered username on the PyPI server. 180- *password*, that will be used to authenticate. If omitted the user 181 will be prompt to type it when needed. 182 183If you want to define another server a new section can be created and 184listed in the *index-servers* variable:: 185 186 [distutils] 187 index-servers = 188 pypi 189 other 190 191 [pypi] 192 repository: <repository-url> 193 username: <username> 194 password: <password> 195 196 [other] 197 repository: https://example.com/pypi 198 username: <username> 199 password: <password> 200 201This allows the :command:`register` and :command:`upload` commands to be 202called with the ``--repository`` option as described in 203:ref:`package-cmdoptions`. 204 205Specifically, you might want to add the `PyPI Test Repository 206<https://wiki.python.org/moin/TestPyPI>`_ to your ``.pypirc`` to facilitate 207testing before doing your first upload to ``PyPI`` itself. 208 209 210.. _package-display: 211 212PyPI package display 213==================== 214 215The ``long_description`` field plays a special role at PyPI. It is used by 216the server to display a home page for the registered package. 217 218If you use the `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ 219syntax for this field, PyPI will parse it and display an HTML output for 220the package home page. 221 222The ``long_description`` field can be attached to a text file located 223in the package:: 224 225 from distutils.core import setup 226 227 with open('README.txt') as file: 228 long_description = file.read() 229 230 setup(name='Distutils', 231 long_description=long_description) 232 233In that case, :file:`README.txt` is a regular reStructuredText text file located 234in the root of the package besides :file:`setup.py`. 235 236To prevent registering broken reStructuredText content, you can use the 237:program:`rst2html` program that is provided by the :mod:`docutils` package and 238check the ``long_description`` from the command line: 239 240.. code-block:: shell-session 241 242 $ python setup.py --long-description | rst2html.py > output.html 243 244:mod:`docutils` will display a warning if there's something wrong with your 245syntax. Because PyPI applies additional checks (e.g. by passing ``--no-raw`` 246to ``rst2html.py`` in the command above), being able to run the command above 247without warnings does not guarantee that PyPI will convert the content 248successfully. 249 250 251.. _Python Package Index (PyPI): https://pypi.python.org/pypi 252