The Python Package Index (PyPI)
*******************************
-The `Python Package Index (PyPI)`_ holds :ref:`meta-data <meta-data>`
+The `Python Package Index (PyPI)`_ stores :ref:`meta-data <meta-data>`
describing distributions packaged with distutils, as well as package data like
-distribution files if the package author wishes.
+distribution files if a package author wishes.
+
+Distutils provides the :command:`register` and :command:`upload` commands for
+pushing meta-data and distribution files to PyPI, respectively. See
+:ref:`package-commands` for information on these commands.
+
+
+PyPI overview
+=============
+
+PyPI lets you submit any number of versions of your distribution to the index.
+If you alter the meta-data for a particular version, you can submit it again
+and the index will be updated.
+
+PyPI holds a record for each (name, version) combination submitted. The first
+user to submit information for a given name is designated the Owner of that
+name. Changes can be submitted through the :command:`register` command or
+through the web interface. Owners can designate other users as Owners or
+Maintainers. Maintainers can edit the package information, but not designate
+new Owners or Maintainers.
+
+By default PyPI displays only the newest version of a given package. The web
+interface lets one change this default behavior and manually select which
+versions to display and hide.
+
+For each version, PyPI displays a home page. The home page is created from
+the ``long_description`` which can be submitted via the :command:`register`
+command. See :ref:`package-display` for more information.
+
+
+.. _package-commands:
+
+Distutils commands
+==================
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.
+files. Both commands read configuration data from a special file called a
+:ref:`.pypirc file <pypirc>`.
.. _package-register:
-Registering Packages
-====================
+The ``register`` command
+------------------------
The distutils command :command:`register` is used to submit your distribution's
-meta-data to the index. It is invoked as follows::
+meta-data to an index server. It is invoked as follows::
python setup.py register
Your selection [default 1]:
Note: if your username and password are saved locally, you will not see this
-menu.
+menu. Also, refer to :ref:`pypirc` for how to store your credentials in a
+:file:`.pypirc` file.
If you have not registered with PyPI, then you will need to do so now. You
should choose option 2, and enter your details as required. Soon after
prompted for your PyPI username and password, and :command:`register` will then
submit your meta-data to the index.
-You may submit any number of versions of your distribution to the index. If you
-alter the meta-data for a particular version, you may submit it again and the
-index will be updated.
-
-PyPI holds a record for each (name, version) combination submitted. The first
-user to submit information for a given name is designated the Owner of that
-name. They may submit changes through the :command:`register` command or through
-the web interface. They may also designate other users as Owners or Maintainers.
-Maintainers may edit the package information, but not designate other Owners or
-Maintainers.
-
-By default PyPI displays only the newest version of a given package. The web
-interface lets one change this default behavior and manually select which
-versions to display and hide.
+See :ref:`package-cmdoptions` for options to the :command:`register` command.
.. _package-upload:
-Uploading Packages
-==================
+The ``upload`` command
+----------------------
The distutils command :command:`upload` pushes the distribution files to PyPI.
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,
+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.
+entered password. This is useful if you do not want to store a password in
+clear text in a :file:`.pypirc` file.
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).
+See :ref:`package-cmdoptions` for additional options to the :command:`upload`
+command.
+
+
+.. _package-cmdoptions:
+
+Additional command options
+--------------------------
+
+This section describes options common to both the :command:`register` and
+:command:`upload` commands.
+
+The ``--repository`` or ``-r`` option lets you specify a PyPI server
+different from the default. For example::
+
+ python setup.py sdist bdist_wininst upload -r https://example.com/pypi
+
+For convenience, a name can be used in place of the URL when the
+:file:`.pypirc` file is configured to do so. For example::
+
+ python setup.py register -r other
+
+See :ref:`pypirc` for more information on defining alternate servers.
+
+The ``--show-response`` option displays the full response text from the PyPI
+server, which is useful when debugging problems with registering and uploading.
.. index::
.. _pypirc:
-The .pypirc file
-================
+The ``.pypirc`` file
+--------------------
-The format of the :file:`.pypirc` file is as follows::
+The :command:`register` and :command:`upload` commands both check for the
+existence of a :file:`.pypirc` file at the location :file:`$HOME/.pypirc`.
+If this file exists, the command uses the username, password, and repository
+URL configured in the file. The format of a :file:`.pypirc` file is as
+follows::
[distutils]
index-servers =
Each section describing a repository defines three variables:
- *repository*, that defines the url of the PyPI server. Defaults to
- ``http://www.python.org/pypi``.
+ ``https://www.python.org/pypi``.
- *username*, which is the registered username on the PyPI server.
- *password*, that will be used to authenticate. If omitted the user
will be prompt to type it when needed.
password: <password>
[other]
- repository: http://example.com/pypi
+ repository: https://example.com/pypi
username: <username>
password: <password>
-:command:`register` can then be called with the -r option to point the
-repository to work with::
-
- python setup.py register -r http://example.com/pypi
+This allows the :command:`register` and :command:`upload` commands to be
+called with the ``--repository`` option as described in
+:ref:`package-cmdoptions`.
-For convenience, the name of the section that describes the repository
-may also be used::
-
- python setup.py register -r other
+Specifically, you might want to add the `PyPI Test Repository
+<https://wiki.python.org/moin/TestPyPI>`_ to your ``.pypirc`` to facilitate
+testing before doing your first upload to ``PyPI`` itself.
.. _package-display:
successfully.
-.. _Python Package Index (PyPI): http://pypi.python.org/
+.. _Python Package Index (PyPI): https://pypi.python.org/
projects / python / commitdiff