Skip to content

Commit 13fb979

Browse files
cjerdonekcjerdonek
committed
Issue #16406: Combine the doc pages for uploading and registering to PyPI.
1 parent 1cb0cb2 commit 13fb979

File tree

5 files changed

+122
-84
lines changed

5 files changed

+122
-84
lines changed

‎Doc/distutils/index.rst‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,6 @@ very little overhead for build/release/install mechanics.
2222
sourcedist.rst
2323
builtdist.rst
2424
packageindex.rst
25-
uploading.rst
2625
examples.rst
2726
extending.rst
2827
commandref.rst

‎Doc/distutils/packageindex.rst‎

Lines changed: 115 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,33 @@
1+
.. index::
2+
single: Python Package Index (PyPI)
3+
single: PyPI; (see Python Package Index (PyPI))
4+
15
.. _package-index:
26

3-
**********************************
4-
Registering with the Package Index
5-
**********************************
7+
*******************************
8+
The Python Package Index (PyPI)
9+
*******************************
10+
11+
The `Python Package Index (PyPI)`_ holds :ref:`meta-data <meta-data>`
12+
describing distributions packaged with distutils, as well as package data like
13+
distribution files if the package author wishes.
14+
15+
Distutils exposes two commands for submitting package data to PyPI: the
16+
:ref:`register <package-register>` command for submitting meta-data to PyPI
17+
and the :ref:`upload <package-upload>` command for submitting distribution
18+
files. Both commands read configuration data from a special file called the
19+
:ref:`.pypirc file <pypirc>`. PyPI :ref:`displays a home page
20+
<package-display>` for each package created from the ``long_description``
21+
submitted by the :command:`register` command.
22+
23+
24+
.. _package-register:
625

7-
The Python Package Index (PyPI) holds meta-data describing distributions
8-
packaged with distutils. The distutils command :command:`register` is used to
9-
submit your distribution's meta-data to the index. It is invoked as follows::
26+
Registering Packages
27+
====================
28+
29+
The distutils command :command:`register` is used to submit your distribution's
30+
meta-data to the index. It is invoked as follows::
1031

1132
python setup.py register
1233

@@ -48,6 +69,52 @@ interface lets one change this default behavior and manually select which
4869
versions to display and hide.
4970

5071

72+
.. _package-upload:
73+
74+
Uploading Packages
75+
==================
76+
77+
The distutils command :command:`upload` pushes the distribution files to PyPI.
78+
79+
The command is invoked immediately after building one or more distribution
80+
files. For example, the command ::
81+
82+
python setup.py sdist bdist_wininst upload
83+
84+
will cause the source distribution and the Windows installer to be uploaded to
85+
PyPI. Note that these will be uploaded even if they are built using an earlier
86+
invocation of :file:`setup.py`, but that only distributions named on the command
87+
line for the invocation including the :command:`upload` command are uploaded.
88+
89+
The :command:`upload` command uses the username, password, and repository URL
90+
from the :file:`$HOME/.pypirc` file (see section :ref:`pypirc` for more on this
91+
file). If a :command:`register` command was previously called in the same command,
92+
and if the password was entered in the prompt, :command:`upload` will reuse the
93+
entered password. This is useful if you do not want to store a clear text
94+
password in the :file:`$HOME/.pypirc` file.
95+
96+
You can specify another PyPI server with the ``--repository=url`` option::
97+
98+
python setup.py sdist bdist_wininst upload -r http://example.com/pypi
99+
100+
See section :ref:`pypirc` for more on defining several servers.
101+
102+
You can use the ``--sign`` option to tell :command:`upload` to sign each
103+
uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must
104+
be available for execution on the system :envvar:`PATH`. You can also specify
105+
which key to use for signing using the ``--identity=name`` option.
106+
107+
Other :command:`upload` options include ``--repository=url`` or
108+
``--repository=section`` where *url* is the url of the server and
109+
*section* the name of the section in :file:`$HOME/.pypirc`, and
110+
``--show-response`` (which displays the full response text from the PyPI
111+
server for help in debugging upload problems).
112+
113+
114+
.. index::
115+
single: .pypirc file
116+
single: Python Package Index (PyPI); .pypirc file
117+
51118
.. _pypirc:
52119

53120
The .pypirc file
@@ -102,3 +169,45 @@ For convenience, the name of the section that describes the repository
102169
may also be used::
103170

104171
python setup.py register -r other
172+
173+
174+
.. _package-display:
175+
176+
PyPI package display
177+
====================
178+
179+
The ``long_description`` field plays a special role at PyPI. It is used by
180+
the server to display a home page for the registered package.
181+
182+
If you use the `reStructuredText <http://docutils.sourceforge.net/rst.html>`_
183+
syntax for this field, PyPI will parse it and display an HTML output for
184+
the package home page.
185+
186+
The ``long_description`` field can be attached to a text file located
187+
in the package::
188+
189+
from distutils.core import setup
190+
191+
with open('README.txt') as file:
192+
long_description = file.read()
193+
194+
setup(name='Distutils',
195+
long_description=long_description)
196+
197+
In that case, :file:`README.txt` is a regular reStructuredText text file located
198+
in the root of the package besides :file:`setup.py`.
199+
200+
To prevent registering broken reStructuredText content, you can use the
201+
:program:`rst2html` program that is provided by the :mod:`docutils` package and
202+
check the ``long_description`` from the command line::
203+
204+
$ python setup.py --long-description | rst2html.py > output.html
205+
206+
:mod:`docutils` will display a warning if there's something wrong with your
207+
syntax. Because PyPI applies additional checks (e.g. by passing ``--no-raw``
208+
to ``rst2html.py`` in the command above), being able to run the command above
209+
without warnings does not guarantee that PyPI will convert the content
210+
successfully.
211+
212+
213+
.. _Python Package Index (PyPI): http://pypi.python.org/

‎Doc/distutils/setupscript.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -610,8 +610,9 @@ Notes:
610610
<http://pypi.python.org/pypi>`_.
611611

612612
(5)
613-
The ``long_description`` field is used by PyPI when you are registering a
614-
package, to build its home page.
613+
The ``long_description`` field is used by PyPI when you are
614+
:ref:`registering <package-register>` a package, to
615+
:ref:`build its home page <package-display>`.
615616

616617
(6)
617618
The ``license`` field is a text indicating the license covering the

‎Doc/distutils/uploading.rst‎

Lines changed: 2 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1,80 +1,7 @@
1-
.. _package-upload:
1+
:orphan:
22

33
***************************************
44
Uploading Packages to the Package Index
55
***************************************
66

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-
14-
python setup.py sdist bdist_wininst upload
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
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.
27-
28-
You can specify another PyPI server with the ``--repository=url`` option::
29-
30-
python setup.py sdist bdist_wininst upload -r http://example.com/pypi
31-
32-
See section :ref:`pypirc` for more on defining several servers.
33-
34-
You can use the ``--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 ``--identity=name`` option.
38-
39-
Other :command:`upload` options include ``--repository=url`` or
40-
``--repository=section`` where *url* is the url of the server and
41-
*section* the name of the section in :file:`$HOME/.pypirc`, and
42-
``--show-response`` (which displays the full response text from the PyPI
43-
server for help in debugging upload problems).
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-
60-
with open('README.txt') as file:
61-
long_description = file.read()
62-
63-
setup(name='Distutils',
64-
long_description=long_description)
65-
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`.
68-
69-
To prevent registering broken reStructuredText content, you can use the
70-
:program:`rst2html` program that is provided by the :mod:`docutils` package and
71-
check the ``long_description`` from the command line::
72-
73-
$ python setup.py --long-description | rst2html.py > output.html
74-
75-
:mod:`docutils` will display a warning if there's something wrong with your
76-
syntax. Because PyPI applies additional checks (e.g. by passing ``--no-raw``
77-
to ``rst2html.py`` in the command above), being able to run the command above
78-
without warnings does not guarantee that PyPI will convert the content
79-
successfully.
80-
7+
The contents of this page have moved to the section :ref:`package-index`.

‎Misc/NEWS‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1086,6 +1086,8 @@ Tools/Demos
10861086
Documentation
10871087
-------------
10881088

1089+
- Issue #16406: Combine the pages for uploading and registering to PyPI.
1090+
10891091
- Issue #16403: Document how distutils uses the maintainer field in
10901092
PKG-INFO. Patch by Jyrki Pulliainen.
10911093

0 commit comments

Comments
 (0)