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