Merge pull request #11698 from Darsstar/keyring-multi-choice

1 files changed, 105 insertions, 10 deletions

diff --git a/docs/html/topics/authentication.md b/docs/html/topics/authentication.md
index f5b553160..966ac3e7a 100644
--- a/docs/html/topics/authentication.md
+++ b/docs/html/topics/authentication.md
@@ -66,25 +66,120 @@ man pages][netrc-docs].
 ## Keyring Support
 
 pip supports loading credentials stored in your keyring using the
-{pypi}`keyring` library.
+{pypi}`keyring` library, which can be enabled py passing `--keyring-provider`
+with a value of `auto`, `disabled`, `import`, or `subprocess`. The default
+value `auto` respects `--no-input` and not query keyring at all if the option
+is used; otherwise it tries the `import`, `subprocess`, and `disabled`
+providers (in this order) and uses the first one that works.
 
-pip will first try to use `keyring` in the same environment as itself and
-fallback to using any `keyring` installation which is available on `PATH`.
+### Configuring pip's keyring usage
 
-Therefore, either of the following setups will work:
+Since the keyring configuration is likely system-wide, a more common way to
+configure its usage would be to use a configuration instead:
+
+```{seealso}
+{doc}`./configuration` describes how pip configuration works.
+```
 
 ```bash
-$ pip install keyring  # install keyring from PyPI into same environment as pip
-$ echo "your-password" | keyring set pypi.company.com your-username
-$ pip install your-package --index-url https://pypi.company.com/
+$ pip config set --global global.keyring-provider subprocess
+
+# A different user on the same system which has PYTHONPATH configured and and
+# wanting to use keyring installed that way could then run
+$ pip config set --user global.keyring-provider import
+
+# For a specific virtual environment you might want to use disable it again
+# because you will only be using PyPI and the private repo (and mirror)
+# requires 2FA with a keycard and a pincode
+$ pip config set --site global.index https://pypi.org/simple
+$ pip config set --site global.keyring-provider disabled
+
+# configuring it via environment variable is also possible
+$ export PIP_KEYRING_PROVIDER=disabled
 ```
 
-or
+### Using keyring's Python module
+
+Setting `keyring-provider` to `import` makes pip communicate with `keyring` via
+its Python interface.
 
 ```bash
-$ pipx install keyring  # install keyring from PyPI into standalone environment
+# install keyring from PyPI
+$ pip install keyring --index-url https://pypi.org/simple
 $ echo "your-password" | keyring set pypi.company.com your-username
-$ pip install your-package --index-url https://pypi.company.com/
+$ pip install your-package --keyring-provider import --index-url https://pypi.company.com/
+```
+
+### Using keyring as a command line application
+
+Setting `keyring-provider` to `subprocess` makes pip look for and use the
+`keyring` command found on `PATH`.
+
+For this use case, a username *must* be included in the URL, since it is
+required by `keyring`'s command line interface. See the example below or the
+basic HTTP authentication section at the top of this page.
+
+```bash
+# Install keyring from PyPI using pipx, which we assume is installed properly
+# you can also create a venv somewhere and add it to the PATH yourself instead
+$ pipx install keyring --index-url https://pypi.org/simple
+
+# For Azure DevOps, also install its keyring backend.
+$ pipx inject keyring artifacts-keyring --index-url https://pypi.org/simple
+
+# For Google Artifact Registry, also install and initialize its keyring backend.
+$ pipx inject keyring keyrings.google-artifactregistry-auth --index-url https://pypi.org/simple
+$ gcloud auth login
+
+# Note that a username is required in the index URL.
+$ pip install your-package --keyring-provider subprocess --index-url https://username@pypi.example.com/
+```
+
+### Here be dragons
+
+The `auto` provider is conservative and does not query keyring at all when
+`--no-input` is used because the keyring might require user interaction such as
+prompting the user on the console. Third party tools frequently call Pip for
+you and do indeed pass `--no-input` as they are well-behaved and don't have
+much information to work with. (Keyring does have an api to request a backend
+that does not require user input.) You have more information about your system,
+however!
+
+You can force keyring usage by requesting a keyring provider other than `auto`
+(or `disabled`). Leaving `import` and `subprocess`. You do this by passing
+`--keyring-provider import` or one of the following methods:
+
+```bash
+# via config file, possibly with --user, --global or --site
+$ pip config set global.keyring-provider subprocess
+# or via environment variable
+$ export PIP_KEYRING_PROVIDER=import
+```
+
+```{warning}
+Be careful when doing this since it could cause tools such as pipx and Pipenv
+to appear to hang. They show their own progress indicator while hiding output
+from the subprocess in which they run Pip. You won't know whether the keyring
+backend is waiting the user input or not in such situations.
+```
+
+pip is conservative and does not query keyring at all when `--no-input` is used
+because the keyring might require user interaction such as prompting the user
+on the console. You can force keyring usage by passing `--force-keyring` or one
+of the following:
+
+```bash
+# possibly with --user, --global or --site
+$ pip config set global.force-keyring true
+# or
+$ export PIP_FORCE_KEYRING=1
+```
+
+```{warning}
+Be careful when doing this since it could cause tools such as pipx and Pipenv
+to appear to hang. They show their own progress indicator while hiding output
+from the subprocess in which they run Pip. You won't know whether the keyring
+backend is waiting the user input or not in such situations.
 ```
 
 Note that `keyring` (the Python package) needs to be installed separately from