Adding content to PyPI

Registering a project on PyPI

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)

Command line reference – distil register

Here is the complete help for distil‘s register command:

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

Register a project on PyPI.

positional arguments:
  DIR                   The directory containing the software to register.
                        This should contain a pydist.json or package.json
                        describing what to register.

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

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.

Command line reference – distil upload

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

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.

Searching an index

To search PyPI for a distribution by name, you can use the distil search command:

$ distil search tatterd
tatterdemalion - A dummy distribution
$ distil search pytz
gaepytz  - A version of pytz that works well on Google App Engine.
pytz     - World timezone definitions, modern and historical
pytzpure - A pure-Python version of PYTZ (timezones).