Add .pypirc specification (#734)

* Add initial draft of .pypirc specification

* Incorporate review feedback

* Link to spec from other docs

* Add subsections

Author: bhrutledge

source/guides/distributing-packages-using-setuptools.rst

@@ -907,7 +907,7 @@ are creating a new project.
 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:
+  upload, you can create a :file:`$HOME/.pypirc` file:
 
   .. code-block:: text
 
@@ -917,6 +917,8 @@ won't see that token again.**
 
   **Be aware that this stores your token in plaintext.**
 
+  For more details, see the :ref:`specification <pypirc>` for :file:`.pypirc`.
+
 .. _register-your-project:
 .. _API token: https://pypi.org/help/#apitoken
 

source/guides/migrating-to-pypi-org.rst

@@ -31,7 +31,7 @@ The default upload settings switched to ``pypi.org`` in the following versions:
 In addition to ensuring you're on a new enough version of the tool for the
 tool's default to have switched, you must also make sure that you have not
 configured the tool to override its default upload URL. Typically this is
-configured in a file located at ``$HOME/.pypirc``. If you see a file like:
+configured in a file located at :file:`$HOME/.pypirc`. If you see a file like:
 
 .. code::
 
@@ -40,17 +40,17 @@ configured in a file located at ``$HOME/.pypirc``. If you see a file like:
         pypi
 
     [pypi]
-    repository:https://pypi.python.org/pypi
-    username:yourusername
-    password:yourpassword
+    repository = https://pypi.python.org/pypi
+    username = <your PyPI username>
+    password = <your PyPI username>
 
 
 Then simply delete the line starting with ``repository`` and you will use
 your upload tool's default URL.
 
 If for some reason you're unable to upgrade the version of your tool
 to a version that defaults to using PyPI.org, then you may edit
-``$HOME/.pypirc`` and include the ``repository:`` line, but use the
+:file:`$HOME/.pypirc` and include the ``repository:`` line, but use the
 value ``https://upload.pypi.org/legacy/`` instead:
 
 .. code::
@@ -60,13 +60,14 @@ value ``https://upload.pypi.org/legacy/`` instead:
         pypi
 
     [pypi]
-    repository: https://upload.pypi.org/legacy/
-    username: your username
-    password: your password
+    repository = https://upload.pypi.org/legacy/
+    username = <your PyPI username>
+    password = <your PyPI password>
 
 (``legacy`` in this URL refers to the fact that this is the new server
 implementation's emulation of the legacy server implementation's upload API.)
 
+For more details, see the :ref:`specification <pypirc>` for :file:`.pypirc`.
 
 Registering package names & metadata
 ------------------------------------
@@ -89,7 +90,7 @@ Using TestPyPI
 
 Legacy TestPyPI (testpypi.python.org) is no longer available; use
 `test.pypi.org <https://test.pypi.org>`_ instead. If you use TestPyPI,
-you must update your ``$HOME/.pypirc`` to handle TestPyPI's new
+you must update your :file:`$HOME/.pypirc` to handle TestPyPI's new
 location, by replacing ``https://testpypi.python.org/pypi`` with
 ``https://test.pypi.org/legacy/``, for example:
 
@@ -101,9 +102,11 @@ location, by replacing ``https://testpypi.python.org/pypi`` with
         testpypi
 
     [testpypi]
-    repository: https://test.pypi.org/legacy/
-    username: your testpypi username
-    password: your testpypi password
+    repository = https://test.pypi.org/legacy/
+    username = <your TestPyPI username>
+    password = <your TestPyPI password>
+
+For more details, see the :ref:`specification <pypirc>` for :file:`.pypirc`.
 
 
 Registering new user accounts

source/guides/using-testpypi.rst

@@ -53,19 +53,15 @@ you're testing has dependencies:
 
     pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple your-package
 
-Setting up TestPyPI in pypirc
------------------------------
+Setting up TestPyPI in :file:`.pypirc`
+--------------------------------------
 
 If you want to avoid entering your username, you can configure TestPyPI in
-your ``$HOME/.pypirc``.
-
-Create or modify ``$HOME/.pypirc`` with the following:
+your :file:`$HOME/.pypirc`:
 
 .. code::
 
     [testpypi]
-    username: your testpypi username
-
+    username = <your TestPyPI username>
 
-.. Warning:: Do not store passwords in the pypirc file.
-    Storing passwords in plain text is never a good idea.
+For more details, see the :ref:`specification <pypirc>` for :file:`.pypirc`.

source/key_projects.rst

@@ -229,6 +229,7 @@ classifiers.
 twine
 =====
 
+`Docs <https://twine.readthedocs.io/en/latest/>`__ |
 `Mailing list <http://mail.python.org/mailman/listinfo/distutils-sig>`__ [2]_ |
 `Issues <https://github.com/pypa/twine/issues>`__ |
 `GitHub <https://github.com/pypa/twine>`__ |

source/specifications/index.rst

@@ -31,4 +31,5 @@ Package Index Interfaces
 .. toctree::
    :maxdepth: 1
 
+   pypirc
    simple-repository-api

source/specifications/pypirc.rst

@@ -0,0 +1,132 @@
+
+.. _pypirc:
+
+========================
+The :file:`.pypirc` file
+========================
+
+A :file:`.pypirc` file allows you to define the configuration for :term:`package
+indexes <Package Index>` (referred to here as "repositories"), so that you don't
+have to enter the URL, username, or password whenever you upload a package with
+:ref:`twine` or :ref:`flit`.
+
+The format (originally defined by the :ref:`distutils` package) is:
+
+.. code-block:: ini
+
+    [distutils]
+    index-servers =
+        first-repository
+        second-repository
+
+    [first-repository]
+    repository = <first-repository URL>
+    username = <first-repository username>
+    password = <first-repository password>
+
+    [second-repository]
+    repository = <second-repository URL>
+    username = <second-repository username>
+    password = <second-repository password>
+
+The ``distutils`` section defines an ``index-servers`` field that lists the
+name of all sections describing a repository.
+
+Each section describing a repository defines three fields:
+
+- ``repository``: The URL of the repository.
+- ``username``: The registered username on the repository.
+- ``password``: The password that will used to authenticate the username.
+
+.. warning::
+
+    Be aware that this stores your password in plain text. For better security,
+    consider an alternative like `keyring`_, setting environment variables, or
+    providing the password on the command line.
+
+.. _keyring: https://pypi.org/project/keyring/
+
+Common configurations
+=====================
+
+.. note::
+
+    These examples apply to :ref:`twine`, and projects like :ref:`hatch` that
+    use it under the hood. Other projects (e.g. :ref:`flit`) also use
+    :file:`.pypirc`, but with different defaults. Please refer to each project's
+    documentation for more details and usage instructions.
+
+Twine's default configuration mimics a :file:`.pypirc` with repository sections
+for PyPI and TestPyPI:
+
+.. code-block:: ini
+
+    [distutils]
+    index-servers =
+        pypi
+        testpypi
+
+    [pypi]
+    repository = https://upload.pypi.org/legacy/
+
+    [testpypi]
+    repository = https://test.pypi.org/legacy/
+
+Twine will add additional configuration from :file:`$HOME/.pypirc`, the command
+line, and environment variables to this default configuration.
+
+Using a PyPI token
+------------------
+
+To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc`
+similar to:
+
+.. code-block:: ini
+
+    [pypi]
+    username = __token__
+    password = <PyPI token>
+
+For :ref:`TestPyPI <using-test-pypi>`, add a ``[testpypi]`` section, using the
+API token from your TestPyPI account.
+
+.. _API token: https://pypi.org/help/#apitoken
+
+Using another package index
+---------------------------
+
+To configure an additional repository, you'll need to redefine the
+``index-servers`` field to include the repository name. Here is a complete
+example of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:
+
+.. code-block:: ini
+
+    [distutils]
+    index-servers =
+        pypi
+        testpypi
+        private-repository
+
+    [pypi]
+    username = __token__
+    password = <PyPI token>
+
+    [testpypi]
+    username = __token__
+    password = <TestPyPI token>
+
+    [private-repository]
+    repository = <private-repository URL>
+    username = <private-repository username>
+    password = <private-repository password>
+
+.. warning::
+
+    Instead of using the ``password`` field, consider saving your API tokens
+    and passwords securely using `keyring`_ (which is installed by Twine):
+
+    .. code-block:: bash
+
+        keyring set https://upload.pypi.org/legacy/ __token__
+        keyring set https://test.pypi.org/legacy/ __token__
+        keyring set <private-repository URL> <private-repository username>