Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

better "register" guidance and pypi.org migration advice #320

Merged
merged 6 commits into from
Mar 15, 2018
Merged

better "register" guidance and pypi.org migration advice #320

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0cf4630
Remove pypi.org default for register command
brainwane Mar 14, 2018
7664372
Improve register usage guidance
brainwane Mar 14, 2018
e2c2ec9
Improve phased-out PyPI upload error message
brainwane Mar 14, 2018
0220b54
Advise users to use Test PyPI first
brainwane Mar 14, 2018
a578fd9
Improve style in README and upload usage
brainwane Mar 14, 2018
3bc3507
Update changelog
brainwane Mar 15, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 73 additions & 63 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,26 +14,27 @@ Why Should I Use This?
The goal of ``twine`` is to improve PyPI interaction by improving
security and testability.

The biggest reason to use ``twine`` is that it securely authenticates you to PyPI
over HTTPS using a verified connection, while ``python setup.py upload`` `only
recently stopped using HTTP <https://bugs.python.org/issue12226>`_ in Python
2.7.9+ and Python 3.2+. This means anytime you use ``python setup.py upload``
with an older Python version, you expose your username and password to being
easily sniffed. Twine uses only verified TLS to upload to PyPI, protecting your
credentials from theft.
The biggest reason to use ``twine`` is that it securely authenticates
you to `PyPI`_ over HTTPS using a verified connection, while ``python
setup.py upload`` `only recently stopped using HTTP
<https://bugs.python.org/issue12226>`_ in Python 2.7.9+ and Python
3.2+. This means anytime you use ``python setup.py upload`` with an
older Python version, you expose your username and password to being
easily sniffed. Twine uses only verified TLS to upload to PyPI,
protecting your credentials from theft.

Secondly, it allows you to precreate your distribution files.
``python setup.py upload`` only allows you to upload something that you've
created in 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.

Finally, it allows you to pre-sign your files and pass the ``.asc``
files into the command line invocation (``twine upload
twine-1.0.1.tar.gz twine-1.0.1.tar.gz.asc``). This enables you to be
assured that you're typing your ``gpg`` passphrase into ``gpg`` itself
and not anything else, since *you* will be the one directly executing
``gpg --detach-sign -a <filename>``.
Finally, ``twine`` allows you to pre-sign your files and pass the
``.asc`` files into the command line invocation (``twine upload
myproject-1.0.1.tar.gz myproject-1.0.1.tar.gz.asc``). This enables you
to be assured that you're typing your ``gpg`` passphrase into ``gpg``
itself and not anything else, since *you* will be the one directly
executing ``gpg --detach-sign -a <filename>``.


Features
Expand All @@ -43,7 +44,7 @@ Features
- Uploading doesn't require executing ``setup.py``
- Uploading files that have already been created, allowing testing of
distributions before release
- Supports uploading any packaging format (including wheels)
- Supports uploading any packaging format (including `wheels`_)


Installation
Expand All @@ -63,13 +64,19 @@ Usage

$ python setup.py sdist bdist_wheel

2. Upload with ``twine``:
2. Upload with ``twine`` to `Test PyPI`_ and verify things look right:

.. code-block:: console

$ twine upload --repository-url https://test.pypi.org/legacy/ dist/*

3. Upload to `PyPI`_:

.. code-block:: console

$ twine upload dist/*

3. Done!
4. Done!

More documentation on using ``twine`` to upload packages to PyPI is in
the `Python Packaging User Guide`_.
Expand All @@ -89,48 +96,47 @@ Options
dist [dist ...]

positional arguments:
dist The distribution files to upload to the repository,
may additionally contain a .asc file to include an
existing signature with the file upload
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 to upload the package to. Can be a
section in the config file or a full URL to the
repository (default: pypi). (Can also be set via
TWINE_REPOSITORY environment variable)
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 URL to upload the package to. This can
be specified with --repository because it will be used
if there is no configuration for the value passed to
--repository. (Can also be set via
TWINE_REPOSITORY_URL environment variable.)
-s, --sign Sign files to upload using gpg
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)
GPG program used to sign uploads (default: gpg).
-i IDENTITY, --identity IDENTITY
GPG identity used to sign files
GPG identity used to sign files.
-u USERNAME, --username USERNAME
The username to authenticate to the repository as (can
also be set via TWINE_USERNAME environment variable)
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 with
(can also be set via TWINE_PASSWORD environment
variable)
The password to authenticate to the repository
(package index) with. (Can also be set via
TWINE_PASSWORD environment variable.)
-c COMMENT, --comment COMMENT
The comment to include with the distribution file
The comment to include with the distribution file.
--config-file CONFIG_FILE
The .pypirc config file to use
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)
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

format.

Twine also includes a ``register`` command.

Expand All @@ -148,45 +154,47 @@ For completeness, its usage:
.. code-block:: console

$ twine register -h
usage: twine register [-h] [-r REPOSITORY] [--repository-url REPOSITORY_URL]

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
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 to register the package to. Can be a
section in the config file or a full URL to the
repository (default: pypi). (Can also be set via
TWINE_REPOSITORY environment variable)
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 URL to upload the package to. This can
be specified with --repository because it will be used
if there is no configuration for the value passed to
--repository. (Can also be set via
TWINE_REPOSITORY_URL environment variable.)
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 as (can
also be set via TWINE_USERNAME environment variable)
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 with
(can also be set via TWINE_PASSWORD environment
variable)
The password to authenticate to the repository
(package index) with. (Can also be set via
TWINE_PASSWORD environment variable.)
-c COMMENT, --comment COMMENT
The comment to include with the distribution file
The comment to include with the distribution file.
--config-file CONFIG_FILE
The .pypirc config file to use
The .pypirc config file to use.
--cert path Path to alternate CA bundle (can also be set via
TWINE_CERT environment variable)
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

format.

Environment Variables
^^^^^^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -230,10 +238,12 @@ trackers, chat rooms, and mailing lists is expected to follow the
.. _`a utility`: https://pypi.org/project/twine/
.. _`publishing`: https://packaging.python.org/tutorials/distributing-packages/
.. _`PyPI`: https://pypi.org
.. _`Test PyPI`: https://packaging.python.org/guides/using-testpypi/
.. _`Python Packaging User Guide`: https://packaging.python.org/tutorials/distributing-packages/
.. _`documentation`: http://twine.readthedocs.io/
.. _`documentation`: https://twine.readthedocs.io/
.. _`developer documentation`: https://twine.readthedocs.io/en/latest/contributing.html
.. _`projects`: https://packaging.python.org/glossary/#term-project
.. _`distributions`: https://packaging.python.org/glossary/#term-distribution-package
.. _`PyPA Code of Conduct`: https://www.pypa.io/en/latest/code-of-conduct/
.. _`Warehouse`: https://github.com/pypa/warehouse
.. _`wheels`: https://packaging.python.org/glossary/#term-wheel
5 changes: 3 additions & 2 deletions docs/changelog.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,9 @@
Changelog
=========

* :feature:`319` Support Metadata 2.1 (`PEP 566
<https://www.python.org/dev/peps/pep-0566/>`_).
* :feature:`320` Remove PyPI as default ``register`` package index.
* :feature:`319` Support Metadata 2.1 (:pep:`566`), including Markdown
for ``description`` fields.
* :support:`318` `Update PyPI URLs
<https://packaging.python.org/guides/migrating-to-pypi-org/>`_.
* :release:`1.10.0 <2018-03-07>`
Expand Down
33 changes: 17 additions & 16 deletions twine/commands/register.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,46 +69,47 @@ def main(args):
"-r", "--repository",
action=utils.EnvironmentDefault,
env="TWINE_REPOSITORY",
default="pypi",
help="The repository to register the package to. "
"Should be a section in the config file (default: "
"%(default)s). (Can also be set via %(env)s environment "
"variable)",
default=None,
help="The repository (package index) to register the package to. "
"Should be a section in the config file. (Can also be set "
"via %(env)s environment variable.) "
"Initial package registration no longer necessary on pypi.org: "
"https://packaging.python.org/guides/migrating-to-pypi-org/",
)
parser.add_argument(
"--repository-url",
action=utils.EnvironmentDefault,
env="TWINE_REPOSITORY_URL",
default=None,
required=False,
help="The repository URL to register the package to. "
"This overrides --repository."
help="The repository (package index) URL to register the package to. "
"This overrides --repository. "
"(Can also be set via %(env)s environment variable.)"
)
parser.add_argument(
"-u", "--username",
action=utils.EnvironmentDefault,
env="TWINE_USERNAME",
required=False, help="The username to authenticate to the repository "
"as (can also be set via %(env)s environment "
"variable)",
"(package index) as. (Can also be set via "
"%(env)s environment variable.)",
)
parser.add_argument(
"-p", "--password",
action=utils.EnvironmentDefault,
env="TWINE_PASSWORD",
required=False, help="The password to authenticate to the repository "
"with (can also be set via %(env)s environment "
"variable)",
"(package index) with. (Can also be set via "
"%(env)s environment variable.)",
)
parser.add_argument(
"-c", "--comment",
help="The comment to include with the distribution file",
help="The comment to include with the distribution file.",
)
parser.add_argument(
"--config-file",
default="~/.pypirc",
help="The .pypirc config file to use",
help="The .pypirc config file to use.",
)
parser.add_argument(
"--cert",
Expand All @@ -118,18 +119,18 @@ def main(args):
required=False,
metavar="path",
help="Path to alternate CA bundle (can also be set via %(env)s "
"environment variable)",
"environment variable).",
)
parser.add_argument(
"--client-cert",
metavar="path",
help="Path to SSL client certificate, a single file containing the "
"private key and the certificate in PEM format",
"private key and the certificate in PEM format.",
)
parser.add_argument(
"package",
metavar="package",
help="File from which we read the package metadata",
help="File from which we read the package metadata.",
)

args = parser.parse_args(args)
Expand Down
Loading