1 .. index:: 2 single: Python Package Index (PyPI) 3 single: PyPI; (see Python Package Index (PyPI)) 4 5 .. _package-index: 6 7 ******************************* 8 The Python Package Index (PyPI) 9 ******************************* 10 11 The `Python Package Index (PyPI)`_ stores :ref:`meta-data <meta-data>` 12 describing distributions packaged with distutils, as well as package data like 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 ================== 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 51 files. Both commands read configuration data from a special file called a 52 :ref:`.pypirc file <pypirc>`. 53 54 55 .. _package-register: 56 57 The ``register`` command 58 ------------------------ 59 60 The distutils command :command:`register` is used to submit your distribution's 61 meta-data to an index server. It is invoked as follows:: 62 63 python setup.py register 64 65 Distutils 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 75 Note: if your username and password are saved locally, you will not see this 76 menu. Also, refer to :ref:`pypirc` for how to store your credentials in a 77 :file:`.pypirc` file. 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 88 See :ref:`package-cmdoptions` for options to the :command:`register` command. 89 90 91 .. _package-upload: 92 93 The ``upload`` command 94 ---------------------- 95 96 The distutils command :command:`upload` pushes the distribution files to PyPI. 97 98 The command is invoked immediately after building one or more distribution 99 files. For example, the command :: 100 101 python setup.py sdist bdist_wininst upload 102 103 will cause the source distribution and the Windows installer to be uploaded to 104 PyPI. Note that these will be uploaded even if they are built using an earlier 105 invocation of :file:`setup.py`, but that only distributions named on the command 106 line for the invocation including the :command:`upload` command are uploaded. 107 108 If a :command:`register` command was previously called in the same command, 109 and if the password was entered in the prompt, :command:`upload` will reuse the 110 entered password. This is useful if you do not want to store a password in 111 clear text in a :file:`.pypirc` file. 112 113 You can use the ``--sign`` option to tell :command:`upload` to sign each 114 uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must 115 be available for execution on the system :envvar:`PATH`. You can also specify 116 which key to use for signing using the ``--identity=name`` option. 117 118 See :ref:`package-cmdoptions` for additional options to the :command:`upload` 119 command. 120 121 122 .. _package-cmdoptions: 123 124 Additional command options 125 -------------------------- 126 127 This section describes options common to both the :command:`register` and 128 :command:`upload` commands. 129 130 The ``--repository`` or ``-r`` option lets you specify a PyPI server 131 different from the default. For example:: 132 133 python setup.py sdist bdist_wininst upload -r https://example.com/pypi 134 135 For convenience, a name can be used in place of the URL when the 136 :file:`.pypirc` file is configured to do so. For example:: 137 138 python setup.py register -r other 139 140 See :ref:`pypirc` for more information on defining alternate servers. 141 142 The ``--show-response`` option displays the full response text from the PyPI 143 server, which is useful when debugging problems with registering and uploading. 144 145 146 .. index:: 147 single: .pypirc file 148 single: Python Package Index (PyPI); .pypirc file 149 150 .. _pypirc: 151 152 The ``.pypirc`` file 153 -------------------- 154 155 The :command:`register` and :command:`upload` commands both check for the 156 existence of a :file:`.pypirc` file at the location :file:`$HOME/.pypirc`. 157 If this file exists, the command uses the username, password, and repository 158 URL configured in the file. The format of a :file:`.pypirc` file is as 159 follows: 160 161 .. code-block:: ini 162 163 [distutils] 164 index-servers = 165 pypi 166 167 [pypi] 168 repository: <repository-url> 169 username: <username> 170 password: <password> 171 172 The *distutils* section defines an *index-servers* variable that lists the 173 name of all sections describing a repository. 174 175 Each section describing a repository defines three variables: 176 177 - *repository*, that defines the url of the PyPI server. Defaults to 178 ``https://upload.pypi.org/legacy/``. 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 183 If you want to define another server a new section can be created and 184 listed in the *index-servers* variable: 185 186 .. code-block:: ini 187 188 [distutils] 189 index-servers = 190 pypi 191 other 192 193 [pypi] 194 repository: <repository-url> 195 username: <username> 196 password: <password> 197 198 [other] 199 repository: https://example.com/pypi 200 username: <username> 201 password: <password> 202 203 This allows the :command:`register` and :command:`upload` commands to be 204 called with the ``--repository`` option as described in 205 :ref:`package-cmdoptions`. 206 207 Specifically, you might want to add the `PyPI Test Repository 208 <https://wiki.python.org/moin/TestPyPI>`_ to your ``.pypirc`` to facilitate 209 testing before doing your first upload to ``PyPI`` itself. 210 211 212 .. _package-display: 213 214 PyPI package display 215 ==================== 216 217 The ``long_description`` field plays a special role at PyPI. It is used by 218 the server to display a home page for the registered package. 219 220 If you use the `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ 221 syntax for this field, PyPI will parse it and display an HTML output for 222 the package home page. 223 224 The ``long_description`` field can be attached to a text file located 225 in the package:: 226 227 from distutils.core import setup 228 229 with open('README.txt') as file: 230 long_description = file.read() 231 232 setup(name='Distutils', 233 long_description=long_description) 234 235 In that case, :file:`README.txt` is a regular reStructuredText text file located 236 in the root of the package besides :file:`setup.py`. 237 238 To prevent registering broken reStructuredText content, you can use the 239 :program:`rst2html` program that is provided by the :mod:`docutils` package and 240 check the ``long_description`` from the command line: 241 242 .. code-block:: shell-session 243 244 $ python setup.py --long-description | rst2html.py > output.html 245 246 :mod:`docutils` will display a warning if there's something wrong with your 247 syntax. Because PyPI applies additional checks (e.g. by passing ``--no-raw`` 248 to ``rst2html.py`` in the command above), being able to run the command above 249 without warnings does not guarantee that PyPI will convert the content 250 successfully. 251 252 253 .. _Python Package Index (PyPI): https://pypi.org 254
