← Back to branch summary

~dkuhlman/python-training-materials/Materials

« back to all changes in this revision

Viewing changes to python-3.5.1-docs-html/_sources/distutils/packageindex.txt

  • Committer: Dave Kuhlman
  • Date: 2017-04-15 16:24:56 UTC
  • Revision ID: dkuhlman@davekuhlman.org-20170415162456-iav9vozzg4iwqwv3
Updated docs

Show diffs side-by-side

added added

removed removed

Lines of Context:
python-3.5.1-docs-html/_sources/distutils/packageindex.txt
1
 
.. index::
2
 
   single: Python Package Index (PyPI)
3
 
   single: PyPI; (see Python Package Index (PyPI))
4
 
 
5
 
.. _package-index:
6
 
 
7
 
*******************************
8
 
The Python Package Index (PyPI)
9
 
*******************************
10
 
 
11
 
The `Python Package Index (PyPI)`_ stores :ref:`meta-data <meta-data>`
12
 
describing distributions packaged with distutils, as well as package data like
13
 
distribution files if a package author wishes.
14
 
 
15
 
Distutils provides the :command:`register` and :command:`upload` commands for
16
 
pushing meta-data and distribution files to PyPI, respectively.  See
17
 
:ref:`package-commands` for information on these commands.
18
 
 
19
 
 
20
 
PyPI overview
21
 
=============
22
 
 
23
 
PyPI lets you submit any number of versions of your distribution to the index.
24
 
If you alter the meta-data for a particular version, you can submit it again
25
 
and the index will be updated.
26
 
 
27
 
PyPI holds a record for each (name, version) combination submitted.  The first
28
 
user to submit information for a given name is designated the Owner of that
29
 
name.  Changes can be submitted through the :command:`register` command or
30
 
through the web interface.  Owners can designate other users as Owners or
31
 
Maintainers.  Maintainers can edit the package information, but not designate
32
 
new Owners or Maintainers.
33
 
 
34
 
By default PyPI displays only the newest version of a given package.  The web
35
 
interface lets one change this default behavior and manually select which
36
 
versions to display and hide.
37
 
 
38
 
For each version, PyPI displays a home page.  The home page is created from
39
 
the ``long_description`` which can be submitted via the :command:`register`
40
 
command.  See :ref:`package-display` for more information.
41
 
 
42
 
 
43
 
.. _package-commands:
44
 
 
45
 
Distutils commands
46
 
==================
47
 
 
48
 
Distutils exposes two commands for submitting package data to PyPI: the
49
 
:ref:`register <package-register>` command for submitting meta-data to PyPI
50
 
and the :ref:`upload <package-upload>` command for submitting distribution
51
 
files.  Both commands read configuration data from a special file called a
52
 
:ref:`.pypirc file <pypirc>`.
53
 
 
54
 
 
55
 
.. _package-register:
56
 
 
57
 
The ``register`` command
58
 
------------------------
59
 
 
60
 
The distutils command :command:`register` is used to submit your distribution's
61
 
meta-data to an index server. It is invoked as follows::
62
 
 
63
 
    python setup.py register
64
 
 
65
 
Distutils will respond with the following prompt::
66
 
 
67
 
    running register
68
 
    We need to know who you are, so please choose either:
69
 
        1. use your existing login,
70
 
        2. register as a new user,
71
 
        3. have the server generate a new password for you (and email it to you), or
72
 
        4. quit
73
 
    Your selection [default 1]:
74
 
 
75
 
Note: if your username and password are saved locally, you will not see this
76
 
menu.  Also, refer to :ref:`pypirc` for how to store your credentials in a
77
 
:file:`.pypirc` file.
78
 
 
79
 
If you have not registered with PyPI, then you will need to do so now. You
80
 
should choose option 2, and enter your details as required. Soon after
81
 
submitting your details, you will receive an email which will be used to confirm
82
 
your registration.
83
 
 
84
 
Once you are registered, you may choose option 1 from the menu. You will be
85
 
prompted for your PyPI username and password, and :command:`register` will then
86
 
submit your meta-data to the index.
87
 
 
88
 
See :ref:`package-cmdoptions` for options to the :command:`register` command.
89
 
 
90
 
 
91
 
.. _package-upload:
92
 
 
93
 
The ``upload`` command
94
 
----------------------
95
 
 
96
 
The distutils command :command:`upload` pushes the distribution files to PyPI.
97
 
 
98
 
The command is invoked immediately after building one or more distribution
99
 
files.  For example, the command ::
100
 
 
101
 
    python setup.py sdist bdist_wininst upload
102
 
 
103
 
will cause the source distribution and the Windows installer to be uploaded to
104
 
PyPI.  Note that these will be uploaded even if they are built using an earlier
105
 
invocation of :file:`setup.py`, but that only distributions named on the command
106
 
line for the invocation including the :command:`upload` command are uploaded.
107
 
 
108
 
If a :command:`register` command was previously called in the same command,
109
 
and if the password was entered in the prompt, :command:`upload` will reuse the
110
 
entered password.  This is useful if you do not want to store a password in
111
 
clear text in a :file:`.pypirc` file.
112
 
 
113
 
You can use the ``--sign`` option to tell :command:`upload` to sign each
114
 
uploaded file using GPG (GNU Privacy Guard).  The  :program:`gpg` program must
115
 
be available for execution on the system :envvar:`PATH`.  You can also specify
116
 
which key to use for signing using the ``--identity=name`` option.
117
 
 
118
 
See :ref:`package-cmdoptions` for additional options to the :command:`upload`
119
 
command.
120
 
 
121
 
 
122
 
.. _package-cmdoptions:
123
 
 
124
 
Additional command options
125
 
--------------------------
126
 
 
127
 
This section describes options common to both the :command:`register` and
128
 
:command:`upload` commands.
129
 
 
130
 
The ``--repository`` or ``-r`` option lets you specify a PyPI server
131
 
different from the default.  For example::
132
 
 
133
 
    python setup.py sdist bdist_wininst upload -r https://example.com/pypi
134
 
 
135
 
For convenience, a name can be used in place of the URL when the
136
 
:file:`.pypirc` file is configured to do so.  For example::
137
 
 
138
 
    python setup.py register -r other
139
 
 
140
 
See :ref:`pypirc` for more information on defining alternate servers.
141
 
 
142
 
The ``--show-response`` option displays the full response text from the PyPI
143
 
server, which is useful when debugging problems with registering and uploading.
144
 
 
145
 
 
146
 
.. index::
147
 
   single: .pypirc file
148
 
   single: Python Package Index (PyPI); .pypirc file
149
 
 
150
 
.. _pypirc:
151
 
 
152
 
The ``.pypirc`` file
153
 
--------------------
154
 
 
155
 
The :command:`register` and :command:`upload` commands both check for the
156
 
existence of a :file:`.pypirc` file at the location :file:`$HOME/.pypirc`.
157
 
If this file exists, the command uses the username, password, and repository
158
 
URL configured in the file.  The format of a :file:`.pypirc` file is as
159
 
follows::
160
 
 
161
 
    [distutils]
162
 
    index-servers =
163
 
        pypi
164
 
 
165
 
    [pypi]
166
 
    repository: <repository-url>
167
 
    username: <username>
168
 
    password: <password>
169
 
 
170
 
The *distutils* section defines an *index-servers* variable that lists the
171
 
name of all sections describing a repository.
172
 
 
173
 
Each section describing a repository defines three variables:
174
 
 
175
 
- *repository*, that defines the url of the PyPI server. Defaults to
176
 
    ``https://www.python.org/pypi``.
177
 
- *username*, which is the registered username on the PyPI server.
178
 
- *password*, that will be used to authenticate. If omitted the user
179
 
    will be prompt to type it when needed.
180
 
 
181
 
If you want to define another server a new section can be created and
182
 
listed in the *index-servers* variable::
183
 
 
184
 
    [distutils]
185
 
    index-servers =
186
 
        pypi
187
 
        other
188
 
 
189
 
    [pypi]
190
 
    repository: <repository-url>
191
 
    username: <username>
192
 
    password: <password>
193
 
 
194
 
    [other]
195
 
    repository: https://example.com/pypi
196
 
    username: <username>
197
 
    password: <password>
198
 
 
199
 
This allows the :command:`register` and :command:`upload` commands to be
200
 
called with the ``--repository`` option as described in
201
 
:ref:`package-cmdoptions`.
202
 
 
203
 
Specifically, you might want to add the `PyPI Test Repository
204
 
<https://wiki.python.org/moin/TestPyPI>`_ to your ``.pypirc`` to facilitate
205
 
testing before doing your first upload to ``PyPI`` itself.
206
 
 
207
 
 
208
 
.. _package-display:
209
 
 
210
 
PyPI package display
211
 
====================
212
 
 
213
 
The ``long_description`` field plays a special role at PyPI. It is used by
214
 
the server to display a home page for the registered package.
215
 
 
216
 
If you use the `reStructuredText <http://docutils.sourceforge.net/rst.html>`_
217
 
syntax for this field, PyPI will parse it and display an HTML output for
218
 
the package home page.
219
 
 
220
 
The ``long_description`` field can be attached to a text file located
221
 
in the package::
222
 
 
223
 
    from distutils.core import setup
224
 
 
225
 
    with open('README.txt') as file:
226
 
        long_description = file.read()
227
 
 
228
 
    setup(name='Distutils',
229
 
          long_description=long_description)
230
 
 
231
 
In that case, :file:`README.txt` is a regular reStructuredText text file located
232
 
in the root of the package besides :file:`setup.py`.
233
 
 
234
 
To prevent registering broken reStructuredText content, you can use the
235
 
:program:`rst2html` program that is provided by the :mod:`docutils` package and
236
 
check the ``long_description`` from the command line::
237
 
 
238
 
    $ python setup.py --long-description | rst2html.py > output.html
239
 
 
240
 
:mod:`docutils` will display a warning if there's something wrong with your
241
 
syntax.  Because PyPI applies additional checks (e.g. by passing ``--no-raw``
242
 
to ``rst2html.py`` in the command above), being able to run the command above
243
 
without warnings does not guarantee that PyPI will convert the content
244
 
successfully.
245
 
 
246
 
 
247
 
.. _Python Package Index (PyPI): https://pypi.python.org/pypi