Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | .. _package-upload: |
| 2 | |
| 3 | *************************************** |
| 4 | Uploading Packages to the Package Index |
| 5 | *************************************** |
| 6 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | The Python Package Index (PyPI) not only stores the package info, but also the |
| 8 | package data if the author of the package wishes to. The distutils command |
| 9 | :command:`upload` pushes the distribution files to PyPI. |
| 10 | |
| 11 | The command is invoked immediately after building one or more distribution |
| 12 | files. For example, the command :: |
| 13 | |
Tarek Ziadé | 13f7c3b | 2009-01-09 00:15:45 +0000 | [diff] [blame] | 14 | python setup.py sdist bdist_wininst upload |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 15 | |
| 16 | will cause the source distribution and the Windows installer to be uploaded to |
| 17 | PyPI. Note that these will be uploaded even if they are built using an earlier |
| 18 | invocation of :file:`setup.py`, but that only distributions named on the command |
| 19 | line for the invocation including the :command:`upload` command are uploaded. |
| 20 | |
| 21 | The :command:`upload` command uses the username, password, and repository URL |
| 22 | from the :file:`$HOME/.pypirc` file (see section :ref:`pypirc` for more on this |
Tarek Ziadé | 13f7c3b | 2009-01-09 00:15:45 +0000 | [diff] [blame] | 23 | file). If a :command:`register` command was previously called in the same command, |
| 24 | and if the password was entered in the prompt, :command:`upload` will reuse the |
| 25 | entered password. This is useful if you do not want to store a clear text |
| 26 | password in the :file:`$HOME/.pypirc` file. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 27 | |
Alexandre Vassalotti | 5f8ced2 | 2008-05-16 00:03:33 +0000 | [diff] [blame] | 28 | You can specify another PyPI server with the :option:`--repository=*url*` option:: |
| 29 | |
Tarek Ziadé | 13f7c3b | 2009-01-09 00:15:45 +0000 | [diff] [blame] | 30 | python setup.py sdist bdist_wininst upload -r http://example.com/pypi |
Alexandre Vassalotti | 5f8ced2 | 2008-05-16 00:03:33 +0000 | [diff] [blame] | 31 | |
| 32 | See section :ref:`pypirc` for more on defining several servers. |
| 33 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 34 | You can use the :option:`--sign` option to tell :command:`upload` to sign each |
| 35 | uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must |
| 36 | be available for execution on the system :envvar:`PATH`. You can also specify |
| 37 | which key to use for signing using the :option:`--identity=*name*` option. |
| 38 | |
Georg Brandl | 36ab1ef | 2009-01-03 21:17:04 +0000 | [diff] [blame] | 39 | Other :command:`upload` options include :option:`--repository=<url>` or |
| 40 | :option:`--repository=<section>` where *url* is the url of the server and |
| 41 | *section* the name of the section in :file:`$HOME/.pypirc`, and |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 42 | :option:`--show-response` (which displays the full response text from the PyPI |
| 43 | server for help in debugging upload problems). |
Tarek Ziadé | 3177f2f | 2009-02-27 02:22:25 +0000 | [diff] [blame] | 44 | |
| 45 | PyPI package display |
| 46 | ==================== |
| 47 | |
| 48 | The ``long_description`` field plays a special role at PyPI. It is used by |
| 49 | the server to display a home page for the registered package. |
| 50 | |
| 51 | If you use the `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ |
| 52 | syntax for this field, PyPI will parse it and display an HTML output for |
| 53 | the package home page. |
| 54 | |
| 55 | The ``long_description`` field can be attached to a text file located |
| 56 | in the package:: |
| 57 | |
| 58 | from distutils.core import setup |
| 59 | |
Éric Araujo | 7d9d34f | 2011-02-25 21:45:06 +0000 | [diff] [blame] | 60 | with open('README.txt') as file: |
| 61 | long_description = file.read() |
| 62 | |
Tarek Ziadé | 3177f2f | 2009-02-27 02:22:25 +0000 | [diff] [blame] | 63 | setup(name='Distutils', |
Éric Araujo | 7d9d34f | 2011-02-25 21:45:06 +0000 | [diff] [blame] | 64 | long_description=long_description) |
Tarek Ziadé | 3177f2f | 2009-02-27 02:22:25 +0000 | [diff] [blame] | 65 | |
Senthil Kumaran | 8227045 | 2010-10-15 13:29:33 +0000 | [diff] [blame] | 66 | In that case, :file:`README.txt` is a regular reStructuredText text file located |
| 67 | in the root of the package besides :file:`setup.py`. |
Tarek Ziadé | 3177f2f | 2009-02-27 02:22:25 +0000 | [diff] [blame] | 68 | |
| 69 | To prevent registering broken reStructuredText content, you can use the |
Senthil Kumaran | 8227045 | 2010-10-15 13:29:33 +0000 | [diff] [blame] | 70 | :program:`rst2html` program that is provided by the :mod:`docutils` package and |
| 71 | check the ``long_description`` from the command line:: |
Tarek Ziadé | 3177f2f | 2009-02-27 02:22:25 +0000 | [diff] [blame] | 72 | |
| 73 | $ python setup.py --long-description | rst2html.py > output.html |
| 74 | |
Senthil Kumaran | 8227045 | 2010-10-15 13:29:33 +0000 | [diff] [blame] | 75 | :mod:`docutils` will display a warning if there's something wrong with your |
| 76 | syntax. |