Contributing

We are happy you have decided to contribute to twine.

Please see the GitHub repository for code and more documentation, and the official Python Packaging User Guide for user documentation. You can also join #pypa or #pypa-dev on Freenode, or the pypa-dev mailing list, to ask questions or get involved.

Getting started

We recommend you use a development environment. Using a virtualenv keeps your development environment isolated, so that twine and its dependencies do not interfere with packages already installed on your machine. You can use virtualenv or pipenv to isolate your development environment.

Clone the twine repository from GitHub, and then make and activate your virtual environment, using Python 3.6 as the Python version in the virtual environment. Example:

mkvirtualenv -p /usr/bin/python3.6 twine

Then, run the following command:

pip install -e /path/to/your/local/twine

Now, in your virtual environment, twine is pointing at your local copy, so when you have made changes, you can easily see their effect.

Building the documentation

Additions and edits to twine’s documentation are welcome and appreciated.

We use tox to build docs. Activate your virtual environment, then install tox.

pip install tox

If you are using pipenv to manage your virtual environment, you may need the tox-pipenv plugin so that tox can use pipenv environments instead of virtualenvs.

To build the docs locally using tox, activate your virtual environment, then run:

tox -e docs

The HTML of the docs will be visible in twine/docs/_build/.

When you have made your changes to the docs, please lint them before making a pull request. To run the linter from the root directory:

doc8 docs

Testing

Tests with twine are run using tox, and tested against the following Python versions: 2.7, 3.4, 3,5, and 3.6. To run these tests locally, you will need to have these versions of Python installed on your machine.

Either use tox to build against all supported Python versions (if you have them installed) or use tox -e py{version} to test against a specific version, e.g., tox -e py27 or tox -e py34.

Also, always run tox -e pep8 before submitting a pull request.

Submitting changes

  1. Fork the GitHub repository.
  2. Make a branch off of master and commit your changes to it.
  3. Run the tests with tox and lint any docs changes with doc8.
  4. Ensure that your name is added to the end of the AUTHORS file using the format Name <email@domain.com> (url), where the (url) portion is optional.
  5. Submit a Pull Request to the master branch on GitHub.

Architectural overview

Twine is a command-line tool for interacting with PyPI securely over HTTPS. Its command line arguments are parsed in twine/cli.py. Currently, twine has two principal functions: uploading new packages and registering new projects. The code for registering new projects is in twine/commands/register.py, and the code for uploading is in twine/commands/upload.py. The file twine/package.py contains a single class, PackageFile, which hashes the project files and extracts their metadata. The file twine/repository.py contains the Repository class, whose methods control the URL the package is uploaded to (which the user can specify either as a default, in the .pypirc file, or pass on the command line), and the methods that upload the package securely to a URL.

Future development

See our open issues.

In the future, pip and twine may merge into a single tool; see ongoing discussion.