.. _indexing:

Adding content to PyPI
----------------------

.. index::
   single: PyPI; adding to


Registering a project on PyPI
=============================

.. index::
   single: Distributions; registering

To register a project on PyPI, you are required (*by PyPI*) to provide both a
name (which is unclaimed on PyPI) and a version number (even if you are not
actually uploading a release yet). You can register a project using the
``register`` command with a requirement giving the name and version number::

    $ distil register "frobozz (0.1)"
    Project registered: frobozz (0.1)

By default, any credentials you have set up in your PyPI configuration will be
used. If you have no PyPI configuration, you will be prompted for username and
password::

    $ distil register "frobozz 0.1"
    Enter your PyPI username:distlib_user
    Enter your PyPI password:
    Project registered: frobozz (0.1)

Note that the password is not echoed to the console.

You can specify an overriding username on the command line, which will be used
instead of any value in your PyPI configuration::

    $ distil register -u distlib_user "frobozz 0.1"
    Enter your PyPI password:
    Project registered: frobozz (0.1)

If you wish, you can also specify the password on the command line::

    $ distil register -u distlib_user --pass secret "frobozz 0.1"
    Project registered: frobozz (0.1)


Here is the complete help for ``distil``'s ``register`` command::

    $ distil help register
    usage: distil register [-h] [-u USERNAME] [--password PASSWORD] REQT

    Register a project on PyPI.

    positional arguments:
      REQT                  The requirement giving the package and version.

    optional arguments:
      -h, --help            show this help message and exit
      -u USERNAME, --username USERNAME
                            The username to use when registering.
      --password PASSWORD   The password to use when registering.


Uploading a release to PyPI
===========================

.. index::
   single: Distributions; uploading

Uploading releases is done by invoking the ``upload`` command and specifying
the project name/version and path to the archive for the release::

    $ distil upload "dummy 0.1" /tmp/dummy-0.1.tar.gz
    Release uploaded.

The reason you need to specify the name and version explicitly is that there
can be ambiguities if ``distil`` just tries to parse the archive filename.

If a source archive is specified, it is expected to contain an entry called
``PKG-INFO`` in the "name-version" directory in the root of the archive, which
has the complete metadata for the release. If a wheel is being uploaded, the
metadata for the release is contained in the conventional location in the
wheel.

Currently, ``distil`` only allows uploading of source archives and wheels.

Here is the complete help for ``distil``'s ``upload`` command::

    $ distil help upload
    usage: distil upload [-h] [-u USERNAME] [--password PASSWORD]
                         REQT ARCHIVE_OR_DIR

    Upload a release or documentation to PyPI.

    positional arguments:
      REQT                  The requirement giving the package and version.
      ARCHIVE_OR_DIR        A source archive, wheel or documentation directory.

    optional arguments:
      -h, --help            show this help message and exit
      -u USERNAME, --username USERNAME
                            The username to use when uploading.
      --password PASSWORD   The password to use when uploading.



Uploading HTML documentation
============================

.. index::
   single: Documentation; uploading

Uploading documentation is also done using the ``upload`` command, but instead
of specifying a release archive to upload, you indicate a directory which
contains HTML documentation (say, the ``docs/_build/html`` directory in your
project, if you are using normal Python conventions used by Sphinx)::

    $ distil upload "dummy 0.1" docs/_build/html
    Documentation uploaded.