.\" Man page generated from reStructuredText.
.
.TH "TWINE" "1" "Jul 22, 2021" "3.4" "twine"
.SH NAME
twine \- twine Documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
Twine is \fI\%a utility\fP for \fI\%publishing\fP Python packages on \fI\%PyPI\fP\&.
.sp
It provides build system independent uploads of source and binary
\fI\%distribution artifacts\fP for both new and existing
\fI\%projects\fP\&.
.SS Table of Contents
.INDENT 0.0
.IP \(bu 2
\fI\%Why Should I Use This?\fP
.IP \(bu 2
\fI\%Features\fP
.IP \(bu 2
\fI\%Installation\fP
.IP \(bu 2
\fI\%Using Twine\fP
.IP \(bu 2
\fI\%Commands\fP
.INDENT 2.0
.IP \(bu 2
\fI\%twine upload\fP
.IP \(bu 2
\fI\%twine check\fP
.IP \(bu 2
\fI\%twine register\fP
.UNINDENT
.IP \(bu 2
\fI\%Configuration\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Environment Variables\fP
.UNINDENT
.IP \(bu 2
\fI\%Keyring Support\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Disabling Keyring\fP
.UNINDENT
.IP \(bu 2
\fI\%Resources\fP
.IP \(bu 2
\fI\%Contributing\fP
.IP \(bu 2
\fI\%Code of Conduct\fP
.UNINDENT
.SH WHY SHOULD I USE THIS?
.sp
The goal of Twine is to improve PyPI interaction by improving
security and testability.
.sp
The biggest reason to use Twine is that it securely authenticates
you to \fI\%PyPI\fP over HTTPS using a verified connection, regardless of
the underlying Python version. Meanwhile, \fBpython setup.py upload\fP
will only work correctly and securely if your build system, Python
version, and underlying operating system are configured properly.
.sp
Secondly, Twine encourages you to build your distribution files. \fBpython
setup.py upload\fP only allows you to upload a package as a final step after
building with \fBdistutils\fP or \fBsetuptools\fP, within the same command
invocation. This means that you cannot test the exact file you’re going to
upload to PyPI to ensure that it works before uploading it.
.sp
Finally, Twine allows you to pre\-sign your files and pass the
\fB\&.asc\fP files into the command line invocation (\fBtwine upload
myproject\-1.0.1.tar.gz myproject\-1.0.1.tar.gz.asc\fP). This enables you
to be assured that you’re typing your \fBgpg\fP passphrase into \fBgpg\fP
itself and not anything else, since \fIyou\fP will be the one directly
executing \fBgpg \-\-detach\-sign \-a <filename>\fP\&.
.SH FEATURES
.INDENT 0.0
.IP \(bu 2
Verified HTTPS connections
.IP \(bu 2
Uploading doesn’t require executing \fBsetup.py\fP
.IP \(bu 2
Uploading files that have already been created, allowing testing of
distributions before release
.IP \(bu 2
Supports uploading any packaging format (including \fI\%wheels\fP)
.UNINDENT
.SH INSTALLATION
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ pip install twine
.ft P
.fi
.UNINDENT
.UNINDENT
.SH USING TWINE
.INDENT 0.0
.IP 1. 3
Create some distributions in the normal way:
.INDENT 3.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ python setup.py sdist bdist_wheel
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.IP 2. 3
Upload with \fBtwine\fP to \fI\%Test PyPI\fP and verify things look right.
Twine will automatically prompt for your username and password:
.INDENT 3.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ twine upload \-r testpypi dist/*
username: ...
password:
\&...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.IP 3. 3
Upload to \fI\%PyPI\fP:
.INDENT 3.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ twine upload dist/*
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.IP 4. 3
Done!
.UNINDENT
.sp
More documentation on using Twine to upload packages to PyPI is in
the \fI\%Python Packaging User Guide\fP\&.
.SH COMMANDS
.SS \fBtwine upload\fP
.sp
Uploads one or more distributions to a repository.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ twine upload \-h
usage: twine upload [\-h] [\-r REPOSITORY] [\-\-repository\-url REPOSITORY_URL]
                    [\-s] [\-\-sign\-with SIGN_WITH] [\-i IDENTITY] [\-u USERNAME]
                    [\-p PASSWORD] [\-c COMMENT] [\-\-config\-file CONFIG_FILE]
                    [\-\-skip\-existing] [\-\-cert path] [\-\-client\-cert path]
                    [\-\-verbose] [\-\-disable\-progress\-bar]
                    dist [dist ...]

positional arguments:
  dist                  The distribution files to upload to the repository
                        (package index). Usually dist/* . May additionally
                        contain a .asc file to include an existing signature
                        with the file upload.

optional arguments:
  \-h, \-\-help            show this help message and exit
  \-r REPOSITORY, \-\-repository REPOSITORY
                        The repository (package index) to upload the package
                        to. Should be a section in the config file (default:
                        pypi). (Can also be set via TWINE_REPOSITORY
                        environment variable.)
  \-\-repository\-url REPOSITORY_URL
                        The repository (package index) URL to upload the
                        package to. This overrides \-\-repository. (Can also be
                        set via TWINE_REPOSITORY_URL environment variable.)
  \-s, \-\-sign            Sign files to upload using GPG.
  \-\-sign\-with SIGN_WITH
                        GPG program used to sign uploads (default: gpg).
  \-i IDENTITY, \-\-identity IDENTITY
                        GPG identity used to sign files.
  \-u USERNAME, \-\-username USERNAME
                        The username to authenticate to the repository
                        (package index) as. (Can also be set via
                        TWINE_USERNAME environment variable.)
  \-p PASSWORD, \-\-password PASSWORD
                        The password to authenticate to the repository
                        (package index) with. (Can also be set via
                        TWINE_PASSWORD environment variable.)
  \-\-non\-interactive     Do not interactively prompt for username/password
                        if the required credentials are missing. (Can also
                        be set via TWINE_NON_INTERACTIVE environment
                        variable.)
  \-c COMMENT, \-\-comment COMMENT
                        The comment to include with the distribution file.
  \-\-config\-file CONFIG_FILE
                        The .pypirc config file to use.
  \-\-skip\-existing       Continue uploading files if one already exists. (Only
                        valid when uploading to PyPI. Other implementations
                        may not support this.)
  \-\-cert path           Path to alternate CA bundle (can also be set via
                        TWINE_CERT environment variable).
  \-\-client\-cert path    Path to SSL client certificate, a single file
                        containing the private key and the certificate in PEM
                        format.
  \-\-verbose             Show verbose output.
  \-\-disable\-progress\-bar
                        Disable the progress bar.
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBtwine check\fP
.sp
Checks whether your distribution’s long description will render correctly on
PyPI.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ twine check \-h
usage: twine check [\-h] [\-\-strict] dist [dist ...]

positional arguments:
  dist        The distribution files to check, usually dist/*

optional arguments:
  \-h, \-\-help  show this help message and exit
  \-\-strict    Fail on warnings
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBtwine register\fP
.sp
\fBWARNING\fP: The \fBregister\fP command is \fI\%no longer necessary if you are
uploading to pypi.org\fP\&.  As such, it is \fI\%no longer supported\fP in \fI\%Warehouse\fP
(the new PyPI software running on pypi.org). However, you may need this if you
are using a different package index.
.sp
For completeness, its usage:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ twine register \-h

usage: twine register [\-h] \-r REPOSITORY [\-\-repository\-url REPOSITORY_URL]
                      [\-u USERNAME] [\-p PASSWORD] [\-c COMMENT]
                      [\-\-config\-file CONFIG_FILE] [\-\-cert path]
                      [\-\-client\-cert path]
                      package

positional arguments:
  package               File from which we read the package metadata.

optional arguments:
  \-h, \-\-help            show this help message and exit
  \-r REPOSITORY, \-\-repository REPOSITORY
                        The repository (package index) to register the package
                        to. Should be a section in the config file. (Can also
                        be set via TWINE_REPOSITORY environment variable.)
                        Initial package registration no longer necessary on
                        pypi.org:
                        https://packaging.python.org/guides/migrating\-to\-pypi\-
                        org/
  \-\-repository\-url REPOSITORY_URL
                        The repository (package index) URL to register the
                        package to. This overrides \-\-repository. (Can also be
                        set via TWINE_REPOSITORY_URL environment variable.)
  \-u USERNAME, \-\-username USERNAME
                        The username to authenticate to the repository
                        (package index) as. (Can also be set via
                        TWINE_USERNAME environment variable.)
  \-p PASSWORD, \-\-password PASSWORD
                        The password to authenticate to the repository
                        (package index) with. (Can also be set via
                        TWINE_PASSWORD environment variable.)
  \-\-non\-interactive     Do not interactively prompt for username/password
                        if the required credentials are missing. (Can also
                        be set via TWINE_NON_INTERACTIVE environment
                        variable.)
  \-c COMMENT, \-\-comment COMMENT
                        The comment to include with the distribution file.
  \-\-config\-file CONFIG_FILE
                        The .pypirc config file to use.
  \-\-cert path           Path to alternate CA bundle (can also be set via
                        TWINE_CERT environment variable).
  \-\-client\-cert path    Path to SSL client certificate, a single file
                        containing the private key and the certificate in PEM
                        format.
.ft P
.fi
.UNINDENT
.UNINDENT
.SH CONFIGURATION
.sp
Twine can read repository configuration from a \fB\&.pypirc\fP file, either in your
home directory, or provided with the \fB\-\-config\-file\fP option. For details on
writing and using \fB\&.pypirc\fP, see the \fI\%specification\fP in the Python
Packaging User Guide.
.SS Environment Variables
.sp
Twine also supports configuration via environment variables. Options passed on
the command line will take precedence over options set via environment
variables. Definition via environment variable is helpful in environments where
it is not convenient to create a \fB\&.pypirc\fP file (for example,
on a CI/build server).
.INDENT 0.0
.IP \(bu 2
\fBTWINE_USERNAME\fP \- the username to use for authentication to the
repository.
.IP \(bu 2
\fBTWINE_PASSWORD\fP \- the password to use for authentication to the
repository.
.IP \(bu 2
\fBTWINE_REPOSITORY\fP \- the repository configuration, either defined as a
section in \fB\&.pypirc\fP or provided as a full URL.
.IP \(bu 2
\fBTWINE_REPOSITORY_URL\fP \- the repository URL to use.
.IP \(bu 2
\fBTWINE_CERT\fP \- custom CA certificate to use for repositories with
self\-signed or untrusted certificates.
.IP \(bu 2
\fBTWINE_NON_INTERACTIVE\fP \- Do not interactively prompt for username/password
if the required credentials are missing.
.UNINDENT
.SH KEYRING SUPPORT
.sp
Instead of typing in your password every time you upload a distribution, Twine
allows storing a username and password securely using \fI\%keyring\fP\&.
Keyring is installed with Twine but for some systems (Linux mainly) may
require \fI\%additional installation steps\fP\&.
.sp
Once Twine is installed, use the \fBkeyring\fP program to set a
username and password to use for each package index (repository) to
which you may upload.
.sp
For example, to set a username and password for PyPI:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ keyring set https://upload.pypi.org/legacy/ your\-username
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
or
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ python3 \-m keyring set https://upload.pypi.org/legacy/ your\-username
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
and enter the password when prompted.
.sp
For a different repository, replace the URL with the relevant repository
URL. For example, for Test PyPI, use \fBhttps://test.pypi.org/legacy/\fP\&.
.sp
The next time you run \fBtwine\fP, it will prompt you for a username and will
grab the appropriate password from the keyring.
.sp
\fBNote:\fP If you are using Linux in a headless environment (such as on a
server) you’ll need to do some additional steps to ensure that Keyring can
store secrets securely. See \fI\%Using Keyring on headless systems\fP\&.
.SS Disabling Keyring
.sp
In most cases, simply not setting a password with \fBkeyring\fP will allow Twine
to fall back to prompting for a password. In some cases, the presence of
Keyring will cause unexpected or undesirable prompts from the backing system.
In these cases, it may be desirable to disable Keyring altogether. To disable
Keyring, simply invoke:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ keyring \-\-disable
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
or
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ python \-m keyring \-\-disable
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
That command will configure for the current user the “null” keyring,
effectively disabling the functionality, and allowing Twine to prompt
for passwords.
.sp
See \fI\%twine 338\fP for
discussion and background.
.SH RESOURCES
.INDENT 0.0
.IP \(bu 2
\fI\%GitHub repository\fP
.IP \(bu 2
User and developer \fI\%documentation\fP
.IP \(bu 2
\fI\%Python Packaging User Guide\fP
.IP \(bu 2
\fI\%Python packaging issue tracker\fP
.IP \(bu 2
\fI\%IRC\fP:
\fB#pypa\fP on irc.libera.chat
.UNINDENT
.SH CONTRIBUTING
.sp
See our \fI\%developer documentation\fP for how to get started, an
architectural overview, and our future development plans.
.SH CODE OF CONDUCT
.sp
Everyone interacting in the Twine project’s codebases, issue
trackers, chat rooms, and mailing lists is expected to follow the
\fI\%PSF Code of Conduct\fP\&.
.SS Contributing
.sp
We are happy you have decided to contribute to twine.
.sp
Please see \fI\%the GitHub repository\fP for code and more documentation,
and the \fI\%official Python Packaging User Guide\fP for user documentation.
To ask questions or get involved, you can join the \fI\%Python Packaging
Discourse forum\fP, \fB#pypa\fP or \fB#pypa\-dev\fP on \fI\%IRC\fP, or the
\fI\%distutils\-sig mailing list\fP\&.
.SS Getting started
.sp
We use \fI\%tox\fP to run tests, check code style, and build the documentation.
To install \fBtox\fP, run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python3 \-m pip install tox
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Clone the twine repository from GitHub, then run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cd /path/to/your/local/twine
tox \-e dev
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This creates a \fI\%virtual environment\fP, so that twine and its
dependencies do not interfere with other packages installed on your
machine. In the virtual environment, \fBtwine\fP is pointing at your
local copy, so when you make changes, you can easily see their effect.
.sp
The virtual environment also contains the tools for running tests
and checking code style, so you can run them on single files directly or
in your code editor. However, we still encourage using the \fBtox\fP commands
below on the whole codebase.
.sp
To use the virtual environment, run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
source venv/bin/activate
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Building the documentation
.sp
Additions and edits to twine’s documentation are welcome and
appreciated.
.sp
To preview the docs while you’re making changes, run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tox \-e watch\-docs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then open a web browser to \fI\%http://127.0.0.1:8000\fP\&.
.sp
When you’re done making changes, lint and build the docs locally before making
a pull request. In your active virtual environment, run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tox \-e docs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The HTML of the docs will be written to \fBdocs/_build/html\fP\&.
.SS Code style
.sp
To automatically reformat your changes with \fI\%isort\fP and \fI\%black\fP, run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tox \-e format
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To detect any remaining code smells with \fI\%flake8\fP, run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tox \-e lint
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To perform strict type\-checking using \fI\%mypy\fP, run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tox \-e types
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Any errors from \fBlint\fP or \fBtypes\fP need to be fixed manually.
.sp
Additionally, we prefer that \fBimport\fP statements be used for packages and
modules only, rather than individual classes or functions.
.SS Testing
.sp
We use \fI\%pytest\fP for writing and running tests.
.sp
To run the tests in your virtual environment, run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tox \-e py
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To pass options to \fBpytest\fP, e.g. the name of a test, run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tox \-e py \-\- tests/test_upload.py::test_exception_for_http_status
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Twine is continuously tested against Python 3.6, 3.7, 3.8, and 3.9 using
\fI\%GitHub Actions\fP\&. To run the tests against a specific version, e.g. Python
3.6, you will need it installed on your machine. Then, run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tox \-e py36
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To run the “integration” tests of uploading to real package indexes, run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tox \-e integration
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To run the tests against all supported Python versions, check code style,
and build the documentation, run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tox
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Submitting changes
.INDENT 0.0
.IP 1. 3
Fork \fI\%the GitHub repository\fP\&.
.IP 2. 3
Make a branch off of \fBmain\fP and commit your changes to it.
.IP 3. 3
Run the tests, check code style, and build the docs as described above.
.IP 4. 3
Optionally, add your name to the end of the \fBAUTHORS\fP
file using the format \fBName <email@domain.com> (url)\fP, where the
\fB(url)\fP portion is optional.
.IP 5. 3
Submit a pull request to the \fBmain\fP branch on GitHub, referencing an
open issue.
.IP 6. 3
Add a changelog entry.
.UNINDENT
.SS Changelog entries
.sp
The \fBdocs/changelog.rst\fP file is built by \fI\%towncrier\fP from files in the
\fBchangelog/\fP directory. To add an entry, create a file in that directory
named \fB{number}.{type}.rst\fP, where \fB{number}\fP is the pull request number,
and \fB{type}\fP is \fBfeature\fP, \fBbugfix\fP, \fBdoc\fP, \fBremoval\fP, or \fBmisc\fP\&.
.sp
For example, if your PR number is 1234 and it’s fixing a bug, then you
would create \fBchangelog/1234.bugfix.rst\fP\&. PRs can span multiple categories by
creating multiple files: if you added a feature and deprecated/removed an old
feature in PR #5678, you would create \fBchangelog/5678.feature.rst\fP and
\fBchangelog/5678.removal.rst\fP\&.
.sp
A changelog entry is meant for end users and should only contain details
relevant to them. In order to maintain a consistent style, please keep the
entry to the point, in sentence case, shorter than 80 characters, and in an
imperative tone. An entry should complete the sentence “This change will …”.
If one line is not enough, use a summary line in an imperative tone, followed
by a description of the change in one or more paragraphs, each wrapped at 80
characters and separated by blank lines.
.sp
You don’t need to reference the pull request or issue number in a changelog
entry, since towncrier will add a link using the number in the file name,
and the pull request should reference an issue number. Similarly, you don’t
need to add your name to the entry, since that will be associated with the pull
request.
.sp
Changelog entries are rendered using \fI\%reStructuredText\fP, but they should only
have minimal formatting (such as \fB\(ga\(gamonospaced text\(ga\(ga\fP).
.SS Architectural overview
.sp
Twine is a command\-line tool for interacting with PyPI securely over
HTTPS. Its three purposes are to be:
.INDENT 0.0
.IP 1. 3
A user\-facing tool for publishing on pypi.org
.IP 2. 3
A user\-facing tool for publishing on other Python package indexes
(e.g., \fBdevpi\fP instances)
.IP 3. 3
A useful API for other programs (e.g., \fBzest.releaser\fP) to call
for publishing on any Python package index
.UNINDENT
.sp
Currently, twine has two principle functions: uploading new packages
and registering new \fI\%projects\fP (\fBregister\fP is no longer supported
on PyPI, and is in Twine for use with other package indexes).
.sp
Its command line arguments are parsed in \fBtwine/cli.py\fP\&. The
code for registering new projects is in
\fBtwine/commands/register.py\fP, and the code for uploading is in
\fBtwine/commands/upload.py\fP\&. The file \fBtwine/package.py\fP
contains a single class, \fBPackageFile\fP, which hashes the project
files and extracts their metadata. The file
\fBtwine/repository.py\fP contains the \fBRepository\fP class, whose
methods control the URL the package is uploaded to (which the user can
specify either as a default, in the \fB\&.pypirc\fP file, or pass on
the command line), and the methods that upload the package securely to
a URL.
.SS Where Twine gets configuration and credentials
.sp
A user can set the repository URL, username, and/or password via
command line, \fB\&.pypirc\fP files, environment variables, and
\fBkeyring\fP\&.
.SS Adding a maintainer
.sp
A checklist for adding a new maintainer to the project.
.INDENT 0.0
.IP 1. 3
Add them as a Member in the GitHub repo settings.
.IP 2. 3
Get them Test PyPI and canon PyPI usernames and add them as a
Maintainer on \fI\%our Test PyPI project\fP and
\fI\%canon PyPI\fP\&.
.UNINDENT
.SS Making a new release
.sp
A checklist for creating, testing, and distributing a new version.
.INDENT 0.0
.IP 1. 3
Choose a version number, e.g. \fBVERSION=3.3.0\fP\&.
.IP 2. 3
Create a new branch, e.g. \fBgit switch \-c release\-$VERSION\fP\&.
.IP 3. 3
Run \fBtox \-e changelog \-\- \-\-version $VERSION\fP to build
\fBdocs/changelog.rst\fP\&.
.IP 4. 3
Commit and open a pull request for review.
.IP 5. 3
Merge the pull request, and ensure the \fI\%GitHub Actions\fP build passes.
.IP 6. 3
Create a new git tag with \fBgit tag \-m "Release v$VERSION" $VERSION\fP\&.
.IP 7. 3
Push the new tag with \fBgit push upstream $VERSION\fP\&.
.IP 8. 3
Watch the release in \fI\%GitHub Actions\fP\&.
.IP 9. 3
Send announcement email to \fI\%distutils\-sig mailing list\fP and celebrate.
.UNINDENT
.SS Future development
.sp
See our \fI\%open issues\fP\&.
.sp
In the future, \fBpip\fP and \fBtwine\fP may
merge into a single tool; see \fI\%ongoing discussion\fP\&.
.SS Changelog
.sp
This project follows the \fI\%semantic versioning\fP
and \fI\%pre\-release versioning\fP
schemes recommended by the Python Packaging Authority.
.SS Twine 3.4.2 (2021\-07\-20)
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Improve error message for unsupported metadata. (\fI\%#755\fP)
.IP \(bu 2
Improve error message for a missing config file. (\fI\%#770\fP)
.IP \(bu 2
Do not include md5_digest or blake2_256_digest if FIPS mode is enabled on the
host. This removes those fields from the metadata before sending the metadata
to the repository. (\fI\%#776\fP)
.UNINDENT
.SS Twine 3.4.1 (2021\-03\-16)
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Fix a regression that was causing some namespace packages with dots in them fail to upload to PyPI. (\fI\%#745\fP)
.UNINDENT
.SS Twine 3.4.0 (2021\-03\-15)
.SS Features
.INDENT 0.0
.IP \(bu 2
Prefer importlib.metadata for entry point handling. (\fI\%#728\fP)
.IP \(bu 2
Rely on importlib_metadata 3.6 for nicer entry point processing. (\fI\%#732\fP)
.IP \(bu 2
Eliminate dependency on setuptools/pkg_resources and replace with packaging and importlib_metadata. (\fI\%#736\fP)
.UNINDENT
.SS Twine 3.3.0 (2020\-12\-23)
.SS Features
.INDENT 0.0
.IP \(bu 2
Print files to be uploaded using \fBupload \-\-verbose\fP (\fI\%#670\fP)
.IP \(bu 2
Print configuration file location when using \fBupload \-\-verbose\fP (\fI\%#675\fP)
.IP \(bu 2
Print source and values of credentials when using \fBupload \-\-verbose\fP (\fI\%#685\fP)
.IP \(bu 2
Add support for Python 3.9 (\fI\%#708\fP)
.IP \(bu 2
Turn warnings into errors when using \fBcheck \-\-strict\fP (\fI\%#715\fP)
.UNINDENT
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Make password optional when using \fBupload \-\-client\-cert\fP (\fI\%#678\fP)
.IP \(bu 2
Support more Nexus versions with \fBupload \-\-skip\-existing\fP (\fI\%#693\fP)
.IP \(bu 2
Support Gitlab Enterprise with \fBupload \-\-skip\-existing\fP (\fI\%#698\fP)
.IP \(bu 2
Show a better error message for malformed files (\fI\%#714\fP)
.UNINDENT
.SS Improved Documentation
.INDENT 0.0
.IP \(bu 2
Adopt PSF code of conduct (\fI\%#680\fP)
.IP \(bu 2
Adopt towncrier for the changleog (\fI\%#718\fP)
.UNINDENT
.SS Twine 3.2.0 (2020\-06\-24)
.SS Features
.INDENT 0.0
.IP \(bu 2
Improve display of HTTP errors during upload (\fI\%#666\fP)
.IP \(bu 2
Print packages and signatures to be uploaded when using \fB\-\-verbose\fP option (\fI\%#652\fP)
.IP \(bu 2
Use red text when printing errors on the command line (\fI\%#649\fP)
.IP \(bu 2
Require repository URL scheme to be \fBhttp\fP or \fBhttps\fP (\fI\%#602\fP)
.IP \(bu 2
Add type annotations, checked with mypy, with \fI\%PEP 561\fP support for users of Twine’s API (\fI\%#231\fP)
.UNINDENT
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Update URL to \fB\&.pypirc\fP specification (\fI\%#655\fP)
.IP \(bu 2
Don’t raise an exception when Python version can’t be parsed from filename (\fI\%#612\fP)
.IP \(bu 2
Fix inaccurate retry message during \fBupload\fP (\fI\%#611\fP)
.IP \(bu 2
Clarify error messages for archive format (\fI\%#601\fP)
.UNINDENT
.SS Twine 3.1.1 (2019\-11\-27)
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Restore \fB\-\-non\-interactive\fP as a flag not expecting an argument. (\fI\%#548\fP)
.UNINDENT
.SS Twine 3.1.0 (2019\-11\-23)
.SS Features
.INDENT 0.0
.IP \(bu 2
Add support for specifying \fB\-\-non\-interactive\fP as an environment variable. (\fI\%#547\fP)
.UNINDENT
.SS Twine 3.0.0 (2019\-11\-18)
.SS Features
.INDENT 0.0
.IP \(bu 2
When a client certificate is indicated, all password processing is disabled. (\fI\%#336\fP)
.IP \(bu 2
Add \fB\-\-non\-interactive\fP flag to abort upload rather than interactively prompt if credentials are missing. (\fI\%#489\fP)
.IP \(bu 2
Twine now unconditionally requires the keyring library and no longer supports uninstalling \fBkeyring\fP as a means to disable that functionality. Instead, use \fBkeyring \-\-disable\fP keyring functionality if necessary. (\fI\%#524\fP)
.IP \(bu 2
Add Python 3.8 to classifiers. (\fI\%#518\fP)
.UNINDENT
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
More robust handling of server response in \fB\-\-skip\-existing\fP (\fI\%#332\fP)
.UNINDENT
.SS Twine 2.0.0 (2019\-09\-24)
.SS Features
.INDENT 0.0
.IP \(bu 2
Twine now requires Python 3.6 or later. Use pip 9 or pin to “twine<2” to install twine on older Python versions. (\fI\%#437\fP)
.UNINDENT
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Require requests 2.20 or later to avoid reported security vulnerabilities in earlier releases. (\fI\%#491\fP)
.UNINDENT
.SS Twine 1.15.0 (2019\-09\-17)
.SS Features
.INDENT 0.0
.IP \(bu 2
Improved output on \fBcheck\fP command: Prints a message when there are no distributions given to check. Improved handling of errors in a distribution’s markup, avoiding messages flowing through to the next distribution’s errors. (\fI\%#488\fP)
.UNINDENT
.SS Twine 1.14.0 (2019\-09\-06)
.SS Features
.INDENT 0.0
.IP \(bu 2
Show Warehouse URL after uploading a package (\fI\%#459\fP)
.IP \(bu 2
Better error handling and gpg2 fallback if gpg not available. (\fI\%#456\fP)
.IP \(bu 2
Now provide a more meaningful error on redirect during upload. (\fI\%#310\fP)
.UNINDENT
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Fail more gracefully when encountering bad metadata (\fI\%#341\fP)
.UNINDENT
.SS Twine 1.13.0 (2019\-02\-13)
.SS Features
.INDENT 0.0
.IP \(bu 2
Add disable_progress_bar option to disable tqdm. (\fI\%#427\fP)
.IP \(bu 2
Allow defining an empty username and password in .pypirc. (\fI\%#426\fP)
.IP \(bu 2
Support keyring.get_credential. (\fI\%#419\fP)
.IP \(bu 2
Support keyring.get_username_and_password. (\fI\%#418\fP)
.IP \(bu 2
Add Python 3.7 to classifiers. (\fI\%#416\fP)
.UNINDENT
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Restore prompts while retaining support for suppressing prompts. (\fI\%#452\fP)
.IP \(bu 2
Avoid requests\-toolbelt to 0.9.0 to prevent attempting to use openssl when it isn’t available. (\fI\%#447\fP)
.IP \(bu 2
Use io.StringIO instead of StringIO. (\fI\%#444\fP)
.IP \(bu 2
Only install pyblake2 if needed. (\fI\%#441\fP)
.IP \(bu 2
Use modern Python language features. (\fI\%#436\fP)
.IP \(bu 2
Specify python_requires in setup.py (\fI\%#435\fP)
.IP \(bu 2
Use https URLs everywhere. (\fI\%#432\fP)
.IP \(bu 2
Fix –skip\-existing for Nexus Repos. (\fI\%#428\fP)
.IP \(bu 2
Remove unnecessary usage of readme_render.markdown. (\fI\%#421\fP)
.IP \(bu 2
Don’t crash if there’s no package description. (\fI\%#412\fP)
.IP \(bu 2
Fix keyring support. (\fI\%#408\fP)
.UNINDENT
.SS Misc
.INDENT 0.0
.IP \(bu 2
Refactor tox env and travis config. (\fI\%#439\fP)
.UNINDENT
.SS Twine 1.12.1 (2018\-09\-24)
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Fix regression with upload exit code (\fI\%#404\fP)
.UNINDENT
.SS Twine 1.12.0 (2018\-09\-24)
.SS Features
.INDENT 0.0
.IP \(bu 2
Add \fBtwine check\fP command to check long description (\fI\%#395\fP)
.IP \(bu 2
Drop support for Python 3.3 (\fI\%#392\fP)
.IP \(bu 2
Empower \fB\-\-skip\-existing\fP for Artifactory repositories (\fI\%#363\fP)
.UNINDENT
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Avoid MD5 when Python is compiled in FIPS mode (\fI\%#367\fP)
.UNINDENT
.SS Twine 1.11.0 (2018\-03\-19)
.SS Features
.INDENT 0.0
.IP \(bu 2
Remove PyPI as default \fBregister\fP package index. (\fI\%#320\fP)
.IP \(bu 2
Support Metadata 2.1 (\fI\%PEP 566\fP), including Markdown for \fBdescription\fP fields. (\fI\%#319\fP)
.UNINDENT
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Raise exception if attempting upload to deprecated legacy PyPI URLs. (\fI\%#322\fP)
.IP \(bu 2
Avoid uploading to PyPI when given alternate repository URL, and require \fBhttp://\fP or \fBhttps://\fP in \fBrepository_url\fP\&. (\fI\%#269\fP)
.UNINDENT
.SS Misc
.INDENT 0.0
.IP \(bu 2
\fI\%Update PyPI URLs\fP\&. (\fI\%#318\fP)
.IP \(bu 2
Add new maintainer, release checklists. (\fI\%#314\fP)
.IP \(bu 2
Add instructions on how to use keyring. (\fI\%#277\fP)
.UNINDENT
.SS Twine 1.10.0 (2018\-03\-07)
.SS Features
.INDENT 0.0
.IP \(bu 2
Link to changelog from \fBREADME\fP (\fI\%#46\fP)
.IP \(bu 2
Reorganize & improve user & developer documentation. (\fI\%#304\fP)
.IP \(bu 2
Revise docs predicting future of \fBtwine\fP (\fI\%#303\fP)
.IP \(bu 2
Add architecture overview to docs (\fI\%#296\fP)
.IP \(bu 2
Add doc building instructions (\fI\%#295\fP)
.IP \(bu 2
Declare support for Python 3.6 (\fI\%#257\fP)
.IP \(bu 2
Improve progressbar (\fI\%#256\fP)
.UNINDENT
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Degrade gracefully when keyring is unavailable (\fI\%#315\fP)
.IP \(bu 2
Fix changelog formatting (\fI\%#299\fP)
.IP \(bu 2
Fix syntax highlighting in \fBREADME\fP (\fI\%#298\fP)
.IP \(bu 2
Fix Read the Docs, tox, Travis configuration (\fI\%#297\fP)
.IP \(bu 2
Fix Travis CI and test configuration (\fI\%#286\fP)
.IP \(bu 2
Print progress to \fBstdout\fP, not \fBstderr\fP (\fI\%#268\fP)
.IP \(bu 2
Fix \fB\-\-repository[\-url]\fP help text (\fI\%#265\fP)
.IP \(bu 2
Remove obsolete registration guidance (\fI\%#200\fP)
.UNINDENT
.SS Twine 1.9.1 (2017\-05\-27)
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Blacklist known bad versions of Requests. (\fI\%#253\fP)
.UNINDENT
.SS Twine 1.9.0 (2017\-05\-22)
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Twine sends less information about the user’s system in the User\-Agent string. (\fI\%#229\fP)
.IP \(bu 2
Fix \fB\-\-skip\-existing\fP when used to upload a package for the first time. (\fI\%#220\fP)
.IP \(bu 2
Fix precedence of \fB\-\-repository\-url\fP over \fB\-\-repository\fP\&. (\fI\%#206\fP)
.UNINDENT
.SS Misc
.INDENT 0.0
.IP \(bu 2
Twine will now resolve passwords using the \fI\%keyring\fP if available. Module can be required with the \fBkeyring\fP extra.
.IP \(bu 2
Twine will use \fBhashlib.blake2b\fP on Python 3.6+ instead of pyblake2
.UNINDENT
.SS Twine 1.8.1 (2016\-08\-09)
.SS Misc
.INDENT 0.0
.IP \(bu 2
Check if a package exists if the URL is one of:
.INDENT 2.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fBhttps://pypi.python.org/pypi/\fP
.IP \(bu 2
\fBhttps://upload.pypi.org/\fP
.IP \(bu 2
\fBhttps://upload.pypi.io/\fP
.UNINDENT
.sp
This helps people with \fBhttps://upload.pypi.io\fP still in their
\fB\&.pypirc\fP file.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Twine 1.8.0 (2016\-08\-08)
.SS Features
.INDENT 0.0
.IP \(bu 2
Switch from upload.pypi.io to upload.pypi.org. (\fI\%#201\fP)
.IP \(bu 2
Retrieve configuration from the environment as a default. (\fI\%#144\fP)
.INDENT 2.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Repository URL will default to \fBTWINE_REPOSITORY\fP
.IP \(bu 2
Username will default to \fBTWINE_USERNAME\fP
.IP \(bu 2
Password will default to \fBTWINE_PASSWORD\fP
.UNINDENT
.UNINDENT
.UNINDENT
.IP \(bu 2
Allow the Repository URL to be provided on the command\-line (\fB\-\-repository\-url\fP) or via an environment variable (\fBTWINE_REPOSITORY_URL\fP). (\fI\%#166\fP)
.IP \(bu 2
Generate Blake2b 256 digests for packages \fIif\fP \fBpyblake2\fP is installed. Users can use \fBpython \-m pip install twine[with\-blake2]\fP to have \fBpyblake2\fP installed with Twine. (\fI\%#171\fP)
.UNINDENT
.SS Misc
.INDENT 0.0
.IP \(bu 2
Generate SHA256 digest for all packages by default.
.IP \(bu 2
Stop testing on Python 2.6.
.IP \(bu 2
Warn users if they receive a 500 error when uploading to \fB*pypi.python.org\fP (\fI\%#199\fP)
.UNINDENT
.SS Twine 1.7.4 (2016\-07\-09)
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Correct a packaging error.
.UNINDENT
.SS Twine 1.7.3 (2016\-07\-08)
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Fix uploads to instances of pypiserver using \fB\-\-skip\-existing\fP\&. We were not properly checking the return status code on the response after attempting an upload. (\fI\%#195\fP)
.UNINDENT
.SS Misc
.INDENT 0.0
.IP \(bu 2
Avoid attempts to upload a package if we can find it on Legacy PyPI.
.UNINDENT
.SS Twine 1.7.2 (2016\-07\-05)
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Fix issue where we were checking the existence of packages even if the user didn’t specify \fB\-\-skip\-existing\fP\&. (\fI\%#189\fP) (\fI\%#191\fP)
.UNINDENT
.SS Twine 1.7.1 (2016\-07\-05)
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Clint was not specified in the wheel metadata as a dependency. (\fI\%#187\fP)
.UNINDENT
.SS Twine 1.7.0 (2016\-07\-04)
.SS Features
.INDENT 0.0
.IP \(bu 2
Support \fB\-\-cert\fP and \fB\-\-client\-cert\fP command\-line flags and config file options for feature parity with pip. This allows users to verify connections to servers other than PyPI (e.g., local package repositories) with different certificates. (\fI\%#142\fP)
.IP \(bu 2
Add progress bar to uploads. (\fI\%#152\fP)
.IP \(bu 2
Allow \fB\-\-skip\-existing\fP to work for 409 status codes. (\fI\%#162\fP)
.IP \(bu 2
Implement retries when the CDN in front of PyPI gives us a 5xx error. (\fI\%#167\fP)
.IP \(bu 2
Switch Twine to upload to pypi.io instead of pypi.python.org. (\fI\%#177\fP)
.UNINDENT
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Allow passwords to have \fB%\fPs in them. (\fI\%#186\fP)
.UNINDENT
.SS Twine 1.6.5 (2015\-12\-16)
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Bump requests\-toolbelt version to ensure we avoid ConnectionErrors (\fI\%#155\fP)
.UNINDENT
.SS Twine 1.6.4 (2015\-10\-27)
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Paths with hyphens in them break the Wheel regular expression. (\fI\%#145\fP)
.IP \(bu 2
Exception while accessing the \fBrepository\fP key (sic) when raising a redirect exception. (\fI\%#146\fP)
.UNINDENT
.SS Twine 1.6.3 (2015\-10\-05)
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Fix uploading signatures causing a 500 error after large file support was added. (\fI\%#137\fP, \fI\%#140\fP)
.UNINDENT
.SS Twine 1.6.2 (2015\-09\-28)
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Upload signatures with packages appropriately (\fI\%#132\fP)
.INDENT 2.0
.INDENT 3.5
As part of the refactor for the 1.6.0 release, we were using the wrong
name to find the signature file.
.sp
This also uncovered a bug where if you’re using twine in a situation where
\fB*\fP is not expanded by your shell, we might also miss uploading
signatures to PyPI. Both were fixed as part of this.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Twine 1.6.1 (2015\-09\-18)
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Fix signing support for uploads (\fI\%#130\fP)
.UNINDENT
.SS Twine 1.6.0 (2015\-09\-14)
.SS Features
.INDENT 0.0
.IP \(bu 2
Allow the user to specify the location of their \fB\&.pypirc\fP (\fI\%#97\fP)
.IP \(bu 2
Support registering new packages with \fBtwine register\fP (\fI\%#8\fP)
.IP \(bu 2
Add the \fB\-\-skip\-existing\fP flag to \fBtwine upload\fP to allow users to skip releases that already exist on PyPI. (\fI\%#115\fP)
.IP \(bu 2
Upload wheels first to PyPI (\fI\%#106\fP)
.IP \(bu 2
Large file support via the \fBrequests\-toolbelt\fP (\fI\%#104\fP)
.UNINDENT
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Raise an exception on redirects (\fI\%#92\fP)
.IP \(bu 2
Work around problems with Windows when using \fBgetpass.getpass\fP (\fI\%#116\fP)
.IP \(bu 2
Warnings triggered by pkginfo searching for \fBPKG\-INFO\fP files should no longer be user visible. (\fI\%#114\fP)
.IP \(bu 2
Provide more helpful messages if \fB\&.pypirc\fP is out of date. (\fI\%#111\fP)
.UNINDENT
.SS Twine 1.5.0 (2015\-03\-10)
.SS Features
.INDENT 0.0
.IP \(bu 2
Support commands not named “gpg” for signing (\fI\%#29\fP)
.UNINDENT
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Display information about the version of setuptools installed (\fI\%#85\fP)
.IP \(bu 2
Support deprecated pypirc file format (\fI\%#61\fP)
.UNINDENT
.SS Misc
.INDENT 0.0
.IP \(bu 2
Add lower\-limit to requests dependency
.UNINDENT
.SS Twine 1.4.0 (2014\-12\-12)
.SS Features
.INDENT 0.0
.IP \(bu 2
Switch to a git style dispatching for the commands to enable simpler commands and programmatic invocation. (\fI\%#6\fP)
.IP \(bu 2
Parse \fB~/.pypirc\fP ourselves and use \fBsubprocess\fP instead of the \fBdistutils.spawn\fP module. (\fI\%#13\fP)
.UNINDENT
.SS Bugfixes
.INDENT 0.0
.IP \(bu 2
Expand globs and check for existence of dists to upload (\fI\%#65\fP)
.IP \(bu 2
Fix issue uploading packages with \fB_\fPs in the name (\fI\%#47\fP)
.IP \(bu 2
List registered commands in help text (\fI\%#34\fP)
.IP \(bu 2
Use \fBpkg_resources\fP to load registered commands (\fI\%#32\fP)
.IP \(bu 2
Prevent ResourceWarning from being shown (\fI\%#28\fP)
.IP \(bu 2
Add support for uploading Windows installers (\fI\%#26\fP)
.UNINDENT
.SS Twine 1.3.0 (2014\-03\-31)
.SS Features
.INDENT 0.0
.IP \(bu 2
Additional functionality.
.UNINDENT
.SS Twine 1.2.2 (2013\-10\-03)
.SS Features
.INDENT 0.0
.IP \(bu 2
Basic functionality.
.UNINDENT
.INDENT 0.0
.IP \(bu 2
search
.UNINDENT
.SH AUTHOR
Donald Stufft, Individual contributors
.SH COPYRIGHT
2021, Donald Stufft and individual contributors
.\" Generated by docutils manpage writer.
.