Instruct users to upload to PyPI with tokens

brainwane · brainwane · commit 66bde4c21398 · 2020-01-16T18:15:48.000-05:00
API tokens are now a production feature of PyPI and users should use them instead of passwords to upload. Toward pypa#628. Signed-off-by: Sumana Harihareswara <sh@changeset.nyc>
diff --git a/source/guides/distributing-packages-using-setuptools.rst b/source/guides/distributing-packages-using-setuptools.rst
@@ -898,19 +898,29 @@ 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.org/account/register/>`_.
 
-.. Note:: If you want to avoid entering your username and password when
-  uploading, you can create a ``$HOME/.pypirc`` file with your username and
-  password:
+Now you'll create a PyPI `API token`_ so you will be able to securely upload
+your project.
+
+Go to https://pypi.org/manage/account/#api-tokens and create a new
+`API token`_; don't limit its scope to a particular project, since you
+are creating a new project.
+
+**Don't close the page until you have copied and saved the token — you
+won't see that token again.**
+
+.. Note:: To avoid having to copy and paste the token every time you
+  upload, you can create a ``$HOME/.pypirc`` file:
 
   .. code-block:: text
 
     [pypi]
-    username = <username>
-    password = <password>
+    username = __token__
+    password = <the token value, including the `pypi-` prefix>
 
-  **Be aware that this stores your password in plaintext.**
+  **Be aware that this stores your token in plaintext.**
 
 .. _register-your-project:
+.. _API token: https://pypi.org/help/#apitoken
 
 Upload your distributions
 -------------------------
diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst
@@ -231,6 +231,18 @@ You will also need to verify your email address before you're able to upload
 any packages.  For more details on Test PyPI, see
 :doc:`/guides/using-testpypi`.
 
+Now you'll create a PyPI `API token`_ so you will be able to securely upload
+your project.
+
+Go to https://test.pypi.org/manage/account/#api-tokens and create a new
+`API token`_; don't limit its scope to a particular project, since you
+are creating a new project.
+
+**Don't close the page until you have copied and saved the token — you
+won't see that token again.**
+
+.. _API token: https://test.pypi.org/help/#apitoken
+
 Now that you are registered, you can use :ref:`twine` to upload the
 distribution packages. You'll need to install Twine:
 
@@ -244,8 +256,11 @@ Once installed, run Twine to upload all of the archives under :file:`dist`:
 
     python3 -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*
 
-You will be prompted for the username and password you registered with Test
-PyPI. After the command completes, you should see output similar to this:
+You will be prompted for a username and password. For the username,
+use ``__token__``. For the password, use the token value, including
+the ``pypi-`` prefix.
+
+After the command completes, you should see output similar to this:
 
 .. code-block:: bash
 
