cpython/Doc/distutils/uploading.rst

77 lines
3.2 KiB
ReStructuredText
Raw Normal View History

2007-08-15 11:28:22 -03:00
.. _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 distutils 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
2007-08-15 11:28:22 -03:00
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:`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.
2007-08-15 11:28:22 -03:00
Merged revisions 62998-63003,63005-63006,63009-63012,63014-63017,63019-63020,63022-63024,63026-63029,63031-63041,63043-63045,63047-63054,63056-63062 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r62998 | andrew.kuchling | 2008-05-10 15:51:55 -0400 (Sat, 10 May 2008) | 7 lines #1858 from Tarek Ziade: Allow multiple repositories in .pypirc; see http://wiki.python.org/moin/EnhancedPyPI for discussion. The patch is slightly revised from Tarek's last patch: I've simplified the PyPIRCCommand.finalize_options() method to not look at sys.argv. Tests still pass. ........ r63000 | alexandre.vassalotti | 2008-05-10 15:59:16 -0400 (Sat, 10 May 2008) | 5 lines Cleaned up io._BytesIO.write(). I am amazed that the old code, for inserting null-bytes, actually worked. Who wrote that thing? Oh, it is me... doh. ........ r63002 | brett.cannon | 2008-05-10 16:52:01 -0400 (Sat, 10 May 2008) | 2 lines Revert r62998 as it broke the build (seems distutils.config is missing). ........ r63014 | andrew.kuchling | 2008-05-10 18:12:38 -0400 (Sat, 10 May 2008) | 1 line #1858: add distutils.config module ........ r63027 | brett.cannon | 2008-05-10 21:09:32 -0400 (Sat, 10 May 2008) | 2 lines Flesh out the 3.0 deprecation to suggest using the ctypes module. ........ r63028 | skip.montanaro | 2008-05-10 22:59:30 -0400 (Sat, 10 May 2008) | 4 lines Copied two versions of the example from the interactive session. Delete one. ........ r63037 | georg.brandl | 2008-05-11 03:02:17 -0400 (Sun, 11 May 2008) | 2 lines reload() takes the module itself. ........ r63038 | alexandre.vassalotti | 2008-05-11 03:06:04 -0400 (Sun, 11 May 2008) | 4 lines Added test framework for handling module renames. Factored the import guard in test_py3kwarn.TestStdlibRemovals into a context manager, namely test_support.CleanImport. ........ r63039 | georg.brandl | 2008-05-11 03:06:05 -0400 (Sun, 11 May 2008) | 2 lines #2742: ``''`` is not converted to NULL in getaddrinfo. ........ r63040 | alexandre.vassalotti | 2008-05-11 03:08:12 -0400 (Sun, 11 May 2008) | 2 lines Fixed typo in a comment of test_support.CleanImport. ........ r63041 | alexandre.vassalotti | 2008-05-11 03:10:25 -0400 (Sun, 11 May 2008) | 2 lines Removed a dead line of code. ........ r63043 | georg.brandl | 2008-05-11 04:47:53 -0400 (Sun, 11 May 2008) | 2 lines #2812: document property.getter/setter/deleter. ........ r63049 | georg.brandl | 2008-05-11 05:06:30 -0400 (Sun, 11 May 2008) | 2 lines #1153769: document PEP 237 changes to string formatting. ........ r63050 | georg.brandl | 2008-05-11 05:11:40 -0400 (Sun, 11 May 2008) | 2 lines #2809: elaborate str.split docstring a bit. ........ r63051 | georg.brandl | 2008-05-11 06:13:59 -0400 (Sun, 11 May 2008) | 2 lines Fix typo. ........ r63052 | georg.brandl | 2008-05-11 06:33:27 -0400 (Sun, 11 May 2008) | 2 lines #2709: clarification. ........ r63053 | georg.brandl | 2008-05-11 06:42:28 -0400 (Sun, 11 May 2008) | 2 lines #2659: add ``break_on_hyphens`` to TextWrapper. ........ r63057 | georg.brandl | 2008-05-11 06:59:39 -0400 (Sun, 11 May 2008) | 2 lines #2741: clarification of value range for address_family. ........ r63058 | georg.brandl | 2008-05-11 07:09:35 -0400 (Sun, 11 May 2008) | 2 lines #2452: timeout is used for all blocking operations. ........ r63059 | andrew.kuchling | 2008-05-11 09:33:56 -0400 (Sun, 11 May 2008) | 2 lines #1792: Improve performance of marshal.dumps() on large objects by increasing the size of the buffer more quickly. ........ r63060 | andrew.kuchling | 2008-05-11 10:00:00 -0400 (Sun, 11 May 2008) | 1 line #1858: re-apply patch for this, adding the missing files ........ r63061 | benjamin.peterson | 2008-05-11 10:13:25 -0400 (Sun, 11 May 2008) | 2 lines Add the "until" command to pdb ........ r63062 | georg.brandl | 2008-05-11 10:17:13 -0400 (Sun, 11 May 2008) | 2 lines Add some sentence endings. ........
2008-05-15 21:03:33 -03:00
You can specify another PyPI server with the :option:`--repository=*url*` option::
python setup.py sdist bdist_wininst upload -r http://example.com/pypi
Merged revisions 62998-63003,63005-63006,63009-63012,63014-63017,63019-63020,63022-63024,63026-63029,63031-63041,63043-63045,63047-63054,63056-63062 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r62998 | andrew.kuchling | 2008-05-10 15:51:55 -0400 (Sat, 10 May 2008) | 7 lines #1858 from Tarek Ziade: Allow multiple repositories in .pypirc; see http://wiki.python.org/moin/EnhancedPyPI for discussion. The patch is slightly revised from Tarek's last patch: I've simplified the PyPIRCCommand.finalize_options() method to not look at sys.argv. Tests still pass. ........ r63000 | alexandre.vassalotti | 2008-05-10 15:59:16 -0400 (Sat, 10 May 2008) | 5 lines Cleaned up io._BytesIO.write(). I am amazed that the old code, for inserting null-bytes, actually worked. Who wrote that thing? Oh, it is me... doh. ........ r63002 | brett.cannon | 2008-05-10 16:52:01 -0400 (Sat, 10 May 2008) | 2 lines Revert r62998 as it broke the build (seems distutils.config is missing). ........ r63014 | andrew.kuchling | 2008-05-10 18:12:38 -0400 (Sat, 10 May 2008) | 1 line #1858: add distutils.config module ........ r63027 | brett.cannon | 2008-05-10 21:09:32 -0400 (Sat, 10 May 2008) | 2 lines Flesh out the 3.0 deprecation to suggest using the ctypes module. ........ r63028 | skip.montanaro | 2008-05-10 22:59:30 -0400 (Sat, 10 May 2008) | 4 lines Copied two versions of the example from the interactive session. Delete one. ........ r63037 | georg.brandl | 2008-05-11 03:02:17 -0400 (Sun, 11 May 2008) | 2 lines reload() takes the module itself. ........ r63038 | alexandre.vassalotti | 2008-05-11 03:06:04 -0400 (Sun, 11 May 2008) | 4 lines Added test framework for handling module renames. Factored the import guard in test_py3kwarn.TestStdlibRemovals into a context manager, namely test_support.CleanImport. ........ r63039 | georg.brandl | 2008-05-11 03:06:05 -0400 (Sun, 11 May 2008) | 2 lines #2742: ``''`` is not converted to NULL in getaddrinfo. ........ r63040 | alexandre.vassalotti | 2008-05-11 03:08:12 -0400 (Sun, 11 May 2008) | 2 lines Fixed typo in a comment of test_support.CleanImport. ........ r63041 | alexandre.vassalotti | 2008-05-11 03:10:25 -0400 (Sun, 11 May 2008) | 2 lines Removed a dead line of code. ........ r63043 | georg.brandl | 2008-05-11 04:47:53 -0400 (Sun, 11 May 2008) | 2 lines #2812: document property.getter/setter/deleter. ........ r63049 | georg.brandl | 2008-05-11 05:06:30 -0400 (Sun, 11 May 2008) | 2 lines #1153769: document PEP 237 changes to string formatting. ........ r63050 | georg.brandl | 2008-05-11 05:11:40 -0400 (Sun, 11 May 2008) | 2 lines #2809: elaborate str.split docstring a bit. ........ r63051 | georg.brandl | 2008-05-11 06:13:59 -0400 (Sun, 11 May 2008) | 2 lines Fix typo. ........ r63052 | georg.brandl | 2008-05-11 06:33:27 -0400 (Sun, 11 May 2008) | 2 lines #2709: clarification. ........ r63053 | georg.brandl | 2008-05-11 06:42:28 -0400 (Sun, 11 May 2008) | 2 lines #2659: add ``break_on_hyphens`` to TextWrapper. ........ r63057 | georg.brandl | 2008-05-11 06:59:39 -0400 (Sun, 11 May 2008) | 2 lines #2741: clarification of value range for address_family. ........ r63058 | georg.brandl | 2008-05-11 07:09:35 -0400 (Sun, 11 May 2008) | 2 lines #2452: timeout is used for all blocking operations. ........ r63059 | andrew.kuchling | 2008-05-11 09:33:56 -0400 (Sun, 11 May 2008) | 2 lines #1792: Improve performance of marshal.dumps() on large objects by increasing the size of the buffer more quickly. ........ r63060 | andrew.kuchling | 2008-05-11 10:00:00 -0400 (Sun, 11 May 2008) | 1 line #1858: re-apply patch for this, adding the missing files ........ r63061 | benjamin.peterson | 2008-05-11 10:13:25 -0400 (Sun, 11 May 2008) | 2 lines Add the "until" command to pdb ........ r63062 | georg.brandl | 2008-05-11 10:17:13 -0400 (Sun, 11 May 2008) | 2 lines Add some sentence endings. ........
2008-05-15 21:03:33 -03:00
See section :ref:`pypirc` for more on defining several servers.
2007-08-15 11:28:22 -03:00
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
2007-08-15 11:28:22 -03:00
:option:`--show-response` (which displays the full response text from the PyPI
server for help in debugging upload problems).
PyPI package display
====================
The ``long_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 ``long_description`` field can be attached to a text file located
in the package::
from distutils.core import setup
with open('README.txt') as file:
long_description = file.read()
setup(name='Distutils',
long_description=long_description)
2010-10-15 10:29:33 -03:00
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
2010-10-15 10:29:33 -03:00
:program:`rst2html` program that is provided by the :mod:`docutils` package and
check the ``long_description`` from the command line::
$ python setup.py --long-description | rst2html.py > output.html
2010-10-15 10:29:33 -03:00
:mod:`docutils` will display a warning if there's something wrong with your
syntax.