Merge pull request #10027 from pradyunsg/topic/authentication

Add a topic guide for Authentication

Author: pradyunsg

docs/html/topics/authentication.md

@@ -0,0 +1,83 @@
+# Authentication
+
+## Basic HTTP authentication
+
+pip supports basic HTTP-based authentication credentials. This is done by
+providing the username (and optionally password) in the URL:
+
+```
+https://username:[email protected]/simple
+```
+
+For indexes that only require single-part authentication tokens, provide the
+token as the "username" and do not provide a password:
+
+```
+https://[email protected]/simple
+```
+
+### Percent-encoding special characters
+
+```{versionaddded} 10.0
+```
+
+Certain special characters are not valid in the credential part of a URL.
+If the user or password part of your login credentials contain any of these
+[special characters][reserved-chars], then they must be percent-encoded. As an
+example, for a user with username `user` and password `he//o` accessing a
+repository at `pypi.company.com/simple`, the URL with credentials would look
+like:
+
+```
+https://user:he%2F%[email protected]/simple
+```
+
+[reserved-chars]: https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters
+
+## netrc support
+
+pip supports loading credentials from a user's `.netrc` file. If no credentials
+are part of the URL, pip will attempt to get authentication credentials for the
+URL's hostname from the user's `.netrc` file. This behaviour comes from the
+underlying use of {pypi}`requests`, which in turn delegates it to the
+[Python standard library's `netrc` module][netrc-std-lib].
+
+```{note}
+As mentioned in the [standard library documentation for netrc][netrc-std-lib],
+only ASCII characters are allowed in `.netrc` files. Whitespace and
+non-printable characters are not allowed in passwords.
+```
+
+Below is an example `.netrc`, for the host `example.com`, with a user named
+`daniel`, using the password `qwerty`:
+
+```
+machine example.com
+login daniel
+password qwerty
+```
+
+More information about the `.netrc` file format can be found in the GNU [`ftp`
+man pages][netrc-docs].
+
+[netrc-docs]: https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html
+[netrc-std-lib]: https://docs.python.org/3/library/netrc.html
+
+## Keyring Support
+
+pip supports loading credentials stored in your keyring using the
+{pypi}`keyring` library.
+
+```bash
+$ pip install keyring  # install keyring from PyPI
+$ echo "your-password" | keyring set pypi.company.com your-username
+$ pip install your-package --index-url https://pypi.company.com/
+```
+
+Note that `keyring` (the Python package) needs to be installed separately from
+pip. This can create a bootstrapping issue if you need the credentials stored in
+the keyring to download and install keyring.
+
+It is, thus, expected that users that wish to use pip's keyring support have
+some mechanism for downloading and installing {pypi}`keyring` in their Python
+environment.

docs/html/topics/index.md

@@ -9,4 +9,6 @@ This section of the documentation is currently being fleshed out. See
 
 ```{toctree}
 :maxdepth: 1
+
+authentication
 ```

docs/html/user_guide.rst

@@ -63,72 +63,17 @@ For more information and examples, see the :ref:`pip install` reference.
 Basic Authentication Credentials
 ================================
 
-pip supports basic authentication credentials. Basically, in the URL there is
-a username and password separated by ``:``.
-
-``https://[username[:password]@]pypi.company.com/simple``
-
-Certain special characters are not valid in the authentication part of URLs.
-If the user or password part of your login credentials contain any of the
-special characters
-`here <https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters>`_
-then they must be percent-encoded. For example, for a
-user with username "user" and password "he//o" accessing a repository at
-pypi.company.com, the index URL with credentials would look like:
-
-``https://user:he%2F%[email protected]``
-
-Support for percent-encoded authentication in index URLs was added in pip 10.0.0
-(in `#3236 <https://github.com/pypa/pip/issues/3236>`_). Users that must use authentication
-for their Python repository on systems with older pip versions should make the latest
-get-pip.py available in their environment to bootstrap pip to a recent-enough version.
-
-For indexes that only require single-part authentication tokens, provide the token
-as the "username" and do not provide a password, for example -
-
-``https://[email protected]``
-
+This is now covered in {doc}`topics/authentication`.
 
 netrc Support
 -------------
 
-If no credentials are part of the URL, pip will attempt to get authentication credentials
-for the URL’s hostname from the user’s .netrc file. This behaviour comes from the underlying
-use of `requests`_ which in turn delegates it to the `Python standard library`_.
-
-The .netrc file contains login and initialization information used by the auto-login process.
-It resides in the user's home directory. The .netrc file format is simple. You specify lines
-with a machine name and follow that with lines for the login and password that are
-associated with that machine. Machine name is the hostname in your URL.
-
-An example .netrc for the host example.com with a user named 'daniel', using the password
-'qwerty' would look like:
-
-.. code-block:: shell
-
-   machine example.com
-   login daniel
-   password qwerty
-
-As mentioned in the `standard library docs <https://docs.python.org/3/library/netrc.html>`_,
-only ASCII characters are allowed. Whitespace and non-printable characters are not allowed in passwords.
-
+This is now covered in {doc}`topics/authentication`.
 
 Keyring Support
 ---------------
 
-pip also supports credentials stored in your keyring using the `keyring`_
-library. Note that ``keyring`` will need to be installed separately, as pip
-does not come with it included.
-
-.. code-block:: shell
-
-   pip install keyring
-   echo your-password | keyring set pypi.company.com your-username
-   pip install your-package --index-url https://pypi.company.com/
-
-.. _keyring: https://pypi.org/project/keyring/
-
+This is now covered in {doc}`topics/authentication`.
 
 Using a Proxy Server
 ====================
@@ -1904,6 +1849,4 @@ announcements on the `low-traffic packaging announcements list`_ and
 .. _low-traffic packaging announcements list: https://mail.python.org/mailman3/lists/pypi-announce.python.org/
 .. _our survey on upgrades that create conflicts: https://docs.google.com/forms/d/e/1FAIpQLSeBkbhuIlSofXqCyhi3kGkLmtrpPOEBwr6iJA6SzHdxWKfqdA/viewform
 .. _the official Python blog: https://blog.python.org/
-.. _requests: https://requests.readthedocs.io/en/latest/user/authentication/#netrc-authentication
-.. _Python standard library: https://docs.python.org/3/library/netrc.html
 .. _Python Windows launcher: https://docs.python.org/3/using/windows.html#launcher