diff --git a/Doc/distutils/packageindex.rst b/Doc/distutils/packageindex.rst --- a/Doc/distutils/packageindex.rst +++ b/Doc/distutils/packageindex.rst @@ -8,26 +8,57 @@ The Python Package Index (PyPI) ******************************* -The `Python Package Index (PyPI)`_ holds :ref:`meta-data ` +The `Python Package Index (PyPI)`_ stores :ref:`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 ` command for submitting meta-data to PyPI and the :ref:`upload ` command for submitting distribution -files. Both commands read configuration data from a special file called the -:ref:`.pypirc file `. PyPI :ref:`displays a home page -` 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 `. .. _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 @@ -42,7 +73,8 @@ 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 @@ -53,26 +85,13 @@ 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. @@ -86,29 +105,42 @@ 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 http://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:: @@ -117,10 +149,14 @@ .. _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 = @@ -160,15 +196,9 @@ username: 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 - -For convenience, the name of the section that describes the repository -may also be used:: - - python setup.py register -r other +This allows the :command:`register` and :command:`upload` commands to be +called with the ``--repository`` option as described in +:ref:`package-cmdoptions`. .. _package-display: