mirror of https://github.com/python/cpython
81 lines
3.2 KiB
ReStructuredText
81 lines
3.2 KiB
ReStructuredText
|
.. _packaging-package-upload:
|
||
|
|
|
||
|
|
***************************************
|
||
|
|
Uploading Packages to the Package Index
|
||
|
|
***************************************
|
||
|
|
|
||
|
|
The Python Package Index (PyPI) not only stores the package info, but also the
|
||
|
|
package data if the author of the package wishes to. The packaging command
|
||
|
|
:command:`upload` pushes the distribution files to PyPI.
|
||
|
|
|
||
|
|
The command is invoked immediately after building one or more distribution
|
||
|
|
files. For example, the command ::
|
||
|
|
|
||
|
|
python setup.py sdist bdist_wininst upload
|
||
|
|
|
||
|
|
will cause the source distribution and the Windows installer to be uploaded to
|
||
|
|
PyPI. Note that these will be uploaded even if they are built using an earlier
|
||
|
|
invocation of :file:`setup.py`, but that only distributions named on the command
|
||
|
|
line for the invocation including the :command:`upload` command are uploaded.
|
||
|
|
|
||
|
|
The :command:`upload` command uses the username, password, and repository URL
|
||
|
|
from the :file:`$HOME/.pypirc` file (see section :ref:`packaging-pypirc` for more on this
|
||
|
|
file). If a :command:`register` command was previously called in the same
|
||
|
|
command, and if the password was entered in the prompt, :command:`upload` will
|
||
|
|
reuse the entered password. This is useful if you do not want to store a clear
|
||
|
|
text password in the :file:`$HOME/.pypirc` file.
|
||
|
|
|
||
|
|
You can specify another PyPI server with the :option:`--repository=*url*`
|
||
|
|
option::
|
||
|
|
|
||
|
|
python setup.py sdist bdist_wininst upload -r http://example.com/pypi
|
||
|
|
|
||
|
|
See section :ref:`packaging-pypirc` for more on defining several servers.
|
||
|
|
|
||
|
|
You can use the :option:`--sign` option to tell :command:`upload` to sign each
|
||
|
|
uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must
|
||
|
|
be available for execution on the system :envvar:`PATH`. You can also specify
|
||
|
|
which key to use for signing using the :option:`--identity=*name*` option.
|
||
|
|
|
||
|
|
Other :command:`upload` options include :option:`--repository=<url>` or
|
||
|
|
:option:`--repository=<section>` where *url* is the url of the server and
|
||
|
|
*section* the name of the section in :file:`$HOME/.pypirc`, and
|
||
|
|
:option:`--show-response` (which displays the full response text from the PyPI
|
||
|
|
server for help in debugging upload problems).
|
||
|
|
|
||
|
|
PyPI package display
|
||
|
|
====================
|
||
|
|
|
||
|
|
The ``description`` field plays a special role at PyPI. It is used by
|
||
|
|
the server to display a home page for the registered package.
|
||
|
|
|
||
|
|
If you use the `reStructuredText <http://docutils.sourceforge.net/rst.html>`_
|
||
|
|
syntax for this field, PyPI will parse it and display an HTML output for
|
||
|
|
the package home page.
|
||
|
|
|
||
|
|
The ``description`` field can be filled from a text file located in the
|
||
|
|
project::
|
||
|
|
|
||
|
|
from packaging.core import setup
|
||
|
|
|
||
|
|
fp = open('README.txt')
|
||
|
|
try:
|
||
|
|
description = fp.read()
|
||
|
|
finally:
|
||
|
|
fp.close()
|
||
|
|
|
||
|
|
setup(name='Packaging',
|
||
|
|
description=description)
|
||
|
|
|
||
|
|
In that case, :file:`README.txt` is a regular reStructuredText text file located
|
||
|
|
in the root of the package besides :file:`setup.py`.
|
||
|
|
|
||
|
|
To prevent registering broken reStructuredText content, you can use the
|
||
|
|
:program:`rst2html` program that is provided by the :mod:`docutils` package
|
||
|
|
and check the ``description`` from the command line::
|
||
|
|
|
||
|
|
$ python setup.py --description | rst2html.py > output.html
|
||
|
|
|
||
|
|
:mod:`docutils` will display a warning if there's something wrong with your
|
||
|
|
syntax.
|