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¶
- Fork the GitHub repository.
- Make a branch off of
master
and commit your changes to it. - Run the tests with
tox
and lint any docs changes withdoc8
. - Ensure that your name is added to the end of the
AUTHORS
file using the formatName <email@domain.com> (url)
, where the(url)
portion is optional. - 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.