traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Issue #16406: Combine the doc pages for uploading and registering to PyPI.

This commit is contained in:
Chris Jerdonek 2013-02-27 10:03:26 -08:00
parent e98631d541 13fb979638
commit 79333db79a
5 changed files with 122 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
Doc/distutils/index.rst
View File

@ -22,7 +22,6 @@ very little overhead for build/release/install mechanics.
sourcedist.rst sourcedist.rst
builtdist.rst builtdist.rst
packageindex.rst packageindex.rst
uploading.rst
examples.rst examples.rst
extending.rst extending.rst
commandref.rst commandref.rst

121
Doc/distutils/packageindex.rst
View File

@ -1,12 +1,33 @@
.. index::
single: Python Package Index (PyPI)
single: PyPI; (see Python Package Index (PyPI))
.. _package-index: .. _package-index:
********************************** *******************************
Registering with the Package Index The Python Package Index (PyPI)
********************************** *******************************
The Python Package Index (PyPI) holds meta-data describing distributions The `Python Package Index (PyPI)`_ holds :ref:`meta-data <meta-data>`
packaged with distutils. The distutils command :command:`register` is used to describing distributions packaged with distutils, as well as package data like
submit your distribution's meta-data to the index. It is invoked as follows:: distribution files if the package author wishes.
Distutils exposes two commands for submitting package data to PyPI: the
:ref:`register <package-register>` command for submitting meta-data to PyPI
and the :ref:`upload <package-upload>` command for submitting distribution
files. Both commands read configuration data from a special file called the
:ref:`.pypirc file <pypirc>`. PyPI :ref:`displays a home page
<package-display>` for each package created from the ``long_description``
submitted by the :command:`register` command.
.. _package-register:
Registering Packages
====================
The distutils command :command:`register` is used to submit your distribution's
meta-data to the index. It is invoked as follows::
python setup.py register python setup.py register
@ -48,6 +69,52 @@ interface lets one change this default behavior and manually select which
versions to display and hide. versions to display and hide.
.. _package-upload:
Uploading Packages
==================
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
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.
You can specify another PyPI server with the ``--repository=url`` option::
python setup.py sdist bdist_wininst upload -r http://example.com/pypi
See section :ref:`pypirc` for more on defining several servers.
You can use the ``--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 ``--identity=name`` option.
Other :command:`upload` options include ``--repository=url`` or
``--repository=section`` where *url* is the url of the server and
*section* the name of the section in :file:`$HOME/.pypirc`, and
``--show-response`` (which displays the full response text from the PyPI
server for help in debugging upload problems).
.. index::
single: .pypirc file
single: Python Package Index (PyPI); .pypirc file
.. _pypirc: .. _pypirc:
The .pypirc file The .pypirc file
@ -102,3 +169,45 @@ For convenience, the name of the section that describes the repository
may also be used:: may also be used::
python setup.py register -r other python setup.py register -r other
.. _package-display:
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)
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 ``long_description`` from the command line::
$ python setup.py --long-description | rst2html.py > output.html
:mod:`docutils` will display a warning if there's something wrong with your
syntax. Because PyPI applies additional checks (e.g. by passing ``--no-raw``
to ``rst2html.py`` in the command above), being able to run the command above
without warnings does not guarantee that PyPI will convert the content
successfully.
.. _Python Package Index (PyPI): http://pypi.python.org/

5
Doc/distutils/setupscript.rst
View File

@ -610,8 +610,9 @@ Notes:
<http://pypi.python.org/pypi>`_. <http://pypi.python.org/pypi>`_.
(5) (5)
The ``long_description`` field is used by PyPI when you are registering a The ``long_description`` field is used by PyPI when you are
package, to build its home page. :ref:`registering <package-register>` a package, to
:ref:`build its home page <package-display>`.
(6) (6)
The ``license`` field is a text indicating the license covering the The ``license`` field is a text indicating the license covering the

77
Doc/distutils/uploading.rst
View File

@ -1,80 +1,7 @@
.. _package-upload: :orphan:
*************************************** ***************************************
Uploading Packages to the Package Index Uploading Packages to the Package Index
*************************************** ***************************************
The Python Package Index (PyPI) not only stores the package info, but also the The contents of this page have moved to the section :ref:`package-index`.
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
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.
You can specify another PyPI server with the ``--repository=url`` option::
python setup.py sdist bdist_wininst upload -r http://example.com/pypi
See section :ref:`pypirc` for more on defining several servers.
You can use the ``--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 ``--identity=name`` option.
Other :command:`upload` options include ``--repository=url`` or
``--repository=section`` where *url* is the url of the server and
*section* the name of the section in :file:`$HOME/.pypirc`, and
``--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)
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 ``long_description`` from the command line::
$ python setup.py --long-description | rst2html.py > output.html
:mod:`docutils` will display a warning if there's something wrong with your
syntax. Because PyPI applies additional checks (e.g. by passing ``--no-raw``
to ``rst2html.py`` in the command above), being able to run the command above
without warnings does not guarantee that PyPI will convert the content
successfully.

2
Misc/NEWS
View File

@ -774,6 +774,8 @@ Tools/Demos
Documentation Documentation
------------- -------------
- Issue #16406: Combine the pages for uploading and registering to PyPI.
- Issue #16403: Document how distutils uses the maintainer field in - Issue #16403: Document how distutils uses the maintainer field in
PKG-INFO. Patch by Jyrki Pulliainen. PKG-INFO. Patch by Jyrki Pulliainen.