Skip to content

Commit

Permalink
Remove "twine register" reference in distributing.rst (pypa#271)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jni @ncoghlan
jni authored and ncoghlan committed Jun 24, 2017
1 parent 973c3ec commit 2508031
Showing 1 changed file with 32 additions and 74 deletions.
106 changes: 32 additions & 74 deletions source/distributing.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -722,112 +722,70 @@ on. For details on the naming of wheel files, see :pep:`425`
Uploading your Project to PyPI
==============================

.. note::
When you ran the command to create your distribution, a new directory ``dist/``
was created under your project's root directory. That's where you'll find your
distribution file(s) to upload.

Before releasing on main PyPI repo, you might prefer training with
.. note:: Before releasing on main PyPI repo, you might prefer training with
`PyPI test site <https://testpypi.python.org/pypi>`_
which is cleaned on a semi regular basis. See
`these instructions <https://wiki.python.org/moin/TestPyPI>`_ on how
to setup your configuration in order to use it.

When you ran the command to create your distribution, a new directory dist/ was created under your project's root directory. That's where you'll find your distribution file(s) to upload.
.. warning:: In other resources you may encounter references to using
``python setup.py register`` and ``python setup.py upload``. These methods
of registering and uploading a package are **strongly discouraged** as it may
use a plaintext HTTP or unverified HTTPS connection on some Python versions,
allowing your username and password to be intercepted during transmission.

Create an account
-----------------

First, you need a :term:`PyPI <Python Package Index (PyPI)>` user
account. There are two options:

1. Create an account manually `using the form on the PyPI website
<https://pypi.python.org/pypi?%3Aaction=register_form>`_.
First, you need a :term:`PyPI <Python Package Index (PyPI)>` user account. You
can create an account
`using the form on the PyPI website <https://pypi.python.org/pypi?%3Aaction=register_form>`_.

2. **(Not recommended):** Have an account created as part of
registering your first project (not recommended due to the
related security concerns, see option #3 below).
.. Note:: If you want to avoid entering your username and password when
uploading, you can create a ``~/.pypirc`` file with your username and
password:

If you created your account using option #1 (the form), you'll need to manually
write a ``~/.pypirc`` file like so.

::

[distutils]
index-servers=pypi
.. code-block:: text
[pypi]
repository = https://upload.pypi.org/legacy/
username = <username>
password = <password>
You can leave out the password line if you use twine with its
``-p PASSWORD`` argument or prefer to simply enter your password
when prompted.


Register your project
---------------------

Next, if this is the first release, you currently need to explicitly register your
project prior to uploading.

There are three ways to do this:

1. Use `the form on the PyPI website
<https://pypi.python.org/pypi?%3Aaction=submit_form>`_, to upload your
``PKG-INFO`` info located in your local project tree at
``myproject.egg-info/PKG-INFO``. If you don't have that file or directory,
then run ``python setup.py egg_info`` to have it generated.
2. Run ``twine register dist/mypkg.whl``, and :ref:`twine` will register your project
based on the package metadata in the specified files. Your ``~/.pypirc``
must already be appropriately configured for twine to work.
3. **(Not recommended):** Run ``python setup.py register``. If you don't have
a user account already, a wizard will create one for you. This approach is
covered here due to it being mentioned in other guides, but it is not
recommended as it may use a plaintext HTTP or unverified HTTPS connection
on some Python versions, allowing your username and password to be intercepted
during transmission.

**Be aware that this stores your password in plaintext.**

Upload your distributions
-------------------------

Finally, you can upload your distributions to :term:`PyPI <Python Package Index
(PyPI)>`.
Once you have an account you can upload your distributions to
:term:`PyPI <Python Package Index (PyPI)>` using :ref:`twine`. If this is
your first time uploading a distribution for a new project, twine will handle
registering the project.

There are two options:
.. code-block:: text
1. Use :ref:`twine`
twine upload dist/*
::

twine upload dist/*
The biggest reason to use twine is that ``python setup.py upload`` (option #2
below) uploads files over plaintext. This means anytime you use it you expose
your username and password to a MITM attack. Twine uses only verified TLS to
upload to PyPI in order to protect your credentials from theft.
.. note:: Twine allows you to pre-sign your distribution files using gpg:

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.
.. code-block:: text
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>``.
gpg --detach-sign -a dist/package-1.0.1.tar.gz
and pass the gpg-created .asc files into the command line invocation:

2. **(Not recommended):** Use :ref:`setuptools`:
.. code-block:: text
::
twine upload dist/package-1.0.1.tar.gz package-1.0.1.tar.gz.asc
python setup.py bdist_wheel sdist upload
This enables you to be assured that you're only ever typing your gpg
passphrase into gpg itself and not anything else since *you* will be
the one directly executing the ``gpg`` command.

This approach is covered here due to it being mentioned in other guides, but it
is not recommended as it may use a plaintext HTTP or unverified HTTPS connection
on some Python versions, allowing your username and password to be intercepted
during transmission.

----

Expand Down

0 comments on commit 2508031

Please sign in to comment.