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 distutils-sig
mailing list, to ask questions or get involved.
Getting started¶
We recommend you use a virtual environment, so that twine and its dependencies do not interfere with other packages installed on your machine.
Clone the twine repository from GitHub, then make and activate a virtual environment that uses Python 3.6 or newer as the default Python. For example:
cd /path/to/your/local/twine
python3.6 -m venv venv
source venv/bin/activate
Then, run the following command:
pip install -e .
Now, in your virtual environment, twine
is pointing at your local copy, so
when you make changes, you can easily see their effect.
We use tox to run tests, check code style, and build the documentation.
To install tox
in your active virtual environment, run:
pip install tox
Building the documentation¶
Additions and edits to twine’s documentation are welcome and appreciated.
To preview the docs while you’re making changes, run:
tox -e watch-docs
Then open a web browser to http://127.0.0.1:8000.
When you’re done making changes, lint and build the docs locally before making a pull request. In your active virtual environment, run:
tox -e docs
The HTML of the docs will be written to docs/_build/html
.
Code style¶
To automatically reformat your changes with isort and black, run:
tox -e format
To detect any remaining code smells with flake8, run:
tox -e lint
To perform strict type-checking using mypy, run:
tox -e types
Any errors from lint
or types
need to be fixed manually.
Additionally, we prefer that import
statements be used for packages and
modules only, rather than individual classes or functions.
Testing¶
We use pytest for writing and running tests.
To run the tests in your virtual environment, run:
tox -e py
To pass options to pytest
, e.g. the name of a test, run:
tox -e py -- tests/test_upload.py::test_exception_for_http_status
Twine is continuously tested against Python 3.6, 3.7, and 3.8 using GitHub Actions. To run the tests against a specific version, e.g. Python 3.6, you will need it installed on your machine. Then, run:
tox -e py36
To run the “integration” tests of uploading to real package indexes, run:
tox -e integration
To run the tests against all supported Python versions, check code style, and build the documentation, run:
tox
Submitting changes¶
- Fork the GitHub repository.
- Make a branch off of
master
and commit your changes to it. - Run the tests, check code style, and build the docs as described above.
- 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 three purposes are to be:
- A user-facing tool for publishing on pypi.org
- A user-facing tool for publishing on other Python package indexes
(e.g.,
devpi
instances) - A useful API for other programs (e.g.,
zest.releaser
) to call for publishing on any Python package index
Currently, twine has two principle functions: uploading new packages
and registering new projects (register
is no longer supported
on PyPI, and is in Twine for use with other package indexes).
Its command line arguments are parsed in twine/cli.py
. 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.
Where Twine gets configuration and credentials¶
A user can set the repository URL, username, and/or password via
command line, .pypirc
files, environment variables, and
keyring
.
Adding a maintainer¶
A checklist for adding a new maintainer to the project.
- Add them as a Member in the GitHub repo settings.
- Get them Test PyPI and canon PyPI usernames and add them as a Maintainer on our Test PyPI project and canon PyPI.
Making a new release¶
A checklist for creating, testing, and distributing a new version.
- Add user-facing changes to
docs/changelog.rst
. - Choose a version number, e.g.
3.2.0
. - Add a
:release:
line todocs/changelog.rst
. - Commit and open a pull request for review.
- Merge the pull request, and ensure the GitHub Actions build passes.
- Create a new git tag with
git tag -m "Release v{version}" {version}
. - Push the new tag with
git push upstream {version}
. - Watch the release in Travis.
- Send announcement email to distutils-sig mailing list and celebrate.
Future development¶
See our open issues.
In the future, pip
and twine
may
merge into a single tool; see ongoing discussion.