New upstream version 22.3+dfsg

AUTHORS.txt

@@ -100,6 +100,7 @@ Bradley Ayers
 Brandon L. Reiss
 Brandt Bucher
 Brett Randall
+Brett Rosen
 Brian Cristante
 Brian Rosner
 briantracy
@@ -136,6 +137,7 @@ Christopher Hunt
 Christopher Snyder
 cjc7373
 Clark Boylan
+Claudio Jolowicz
 Clay McClure
 Cody
 Cody Soyland
@@ -233,6 +235,8 @@ Erik Rose
 Erwin Janssen
 Eugene Vereshchagin
 everdimension
+Federico
+Felipe Peter
 Felix Yan
 fiber-space
 Filip Kokosiński
@@ -257,6 +261,7 @@ ghost
 Giftlin Rajaiah
 gizmoguy1
 gkdoc
+Godefroid Chapelle
 Gopinath M
 GOTO Hayato
 gousaiyang
@@ -273,6 +278,7 @@ Hari Charan
 Harsh Vardhan
 harupy
 Harutaka Kawamura
+hauntsaninja
 Henrich Hartzer
 Henry Schreiner
 Herbert Pfennig
@@ -297,6 +303,7 @@ Ionel Maries Cristian
 Ivan Pozdeev
 Jacob Kim
 Jacob Walls
+Jaime Sanz
 jakirkham
 Jakub Stasiak
 Jakub Vysoky
@@ -391,6 +398,7 @@ Luo Jiebin
 luojiebin
 luz.paz
 László Kiss Kollár
+M00nL1ght
 Marc Abramowitz
 Marc Tamlyn
 Marcus Smith
@@ -543,6 +551,7 @@ Reece Dunham
 Remi Rampin
 Rene Dudfield
 Riccardo Magliocchetti
+Riccardo Schirone
 Richard Jones
 Richard Si
 Ricky Ng-Adam

MANIFEST.in

@@ -24,6 +24,7 @@ exclude noxfile.py
 recursive-include src/pip/_vendor *.pem
 recursive-include src/pip/_vendor py.typed
 recursive-include docs *.css *.py *.rst *.md
+recursive-include docs *.dot *.png
 
 exclude src/pip/_vendor/six
 exclude src/pip/_vendor/six/moves

NEWS.rst

@@ -9,6 +9,87 @@
 
 .. towncrier release notes start
 
+22.3 (2022-10-15)
+=================
+
+Deprecations and Removals
+-------------------------
+
+- Deprecate ``--install-options`` which forces pip to use the deprecated ``install``
+  command of ``setuptools``. (`#11358 <https://github.com/pypa/pip/issues/11358>`_)
+- Deprecate installation with 'setup.py install' when no-binary is enabled for
+  source distributions without 'pyproject.toml'. (`#11452 <https://github.com/pypa/pip/issues/11452>`_)
+- Deprecate ```--no-binary`` disabling the wheel cache. (`#11454 <https://github.com/pypa/pip/issues/11454>`_)
+- Remove ``--use-feature=2020-resolver`` opt-in flag. This was supposed to be removed in 21.0, but missed during that release cycle. (`#11493 <https://github.com/pypa/pip/issues/11493>`_)
+- Deprecate installation with 'setup.py install' when the 'wheel' package is absent for
+  source distributions without 'pyproject.toml'. (`#8559 <https://github.com/pypa/pip/issues/8559>`_)
+- Remove the ability to use ``pip list --outdated`` in combination with ``--format=freeze``. (`#9789 <https://github.com/pypa/pip/issues/9789>`_)
+
+Features
+--------
+
+- Use ``shell=True`` for opening the editor with ``pip config edit``. (`#10716 <https://github.com/pypa/pip/issues/10716>`_)
+- Use the ``data-dist-info-metadata`` attribute from :pep:`658` to resolve distribution metadata without downloading the dist yet. (`#11111 <https://github.com/pypa/pip/issues/11111>`_)
+- Add an option to run the test suite with pip built as a zipapp. (`#11250 <https://github.com/pypa/pip/issues/11250>`_)
+- Add a ``--python`` option to allow pip to manage Python environments other
+  than the one pip is installed in. (`#11320 <https://github.com/pypa/pip/issues/11320>`_)
+- Document the new (experimental) zipapp distribution of pip. (`#11459 <https://github.com/pypa/pip/issues/11459>`_)
+- Use the much faster 'bzr co --lightweight' to obtain a copy of a Bazaar tree. (`#5444 <https://github.com/pypa/pip/issues/5444>`_)
+
+Bug Fixes
+---------
+
+- Fix ``--no-index`` when ``--index-url`` or ``--extra-index-url`` is specified
+  inside a requirements file. (`#11276 <https://github.com/pypa/pip/issues/11276>`_)
+- Ensure that the candidate ``pip`` executable exists, when checking for a new version of pip. (`#11309 <https://github.com/pypa/pip/issues/11309>`_)
+- Ignore distributions with invalid ``Name`` in metadata instead of crashing, when
+  using the ``importlib.metadata`` backend. (`#11352 <https://github.com/pypa/pip/issues/11352>`_)
+- Raise RequirementsFileParseError when parsing malformed requirements options that can't be sucessfully parsed by shlex. (`#11491 <https://github.com/pypa/pip/issues/11491>`_)
+- Fix build environment isolation on some system Pythons. (`#6264 <https://github.com/pypa/pip/issues/6264>`_)
+
+Vendored Libraries
+------------------
+
+- Upgrade certifi to 2022.9.24
+- Upgrade distlib to 0.3.6
+- Upgrade idna to 3.4
+- Upgrade pep517 to 0.13.0
+- Upgrade pygments to 2.13.0
+- Upgrade tenacity to 8.1.0
+- Upgrade typing_extensions to 4.4.0
+- Upgrade urllib3 to 1.26.12
+
+Improved Documentation
+----------------------
+
+- Mention that --quiet must be used when writing the installation report to stdout. (`#11357 <https://github.com/pypa/pip/issues/11357>`_)
+
+
+22.2.2 (2022-08-03)
+===================
+
+Bug Fixes
+---------
+
+- Avoid  ``AttributeError`` when removing the setuptools-provided ``_distutils_hack`` and it is missing its implementation. (`#11314 <https://github.com/pypa/pip/issues/11314>`_)
+- Fix import error when reinstalling pip in user site. (`#11319 <https://github.com/pypa/pip/issues/11319>`_)
+- Show pip deprecation warnings by default. (`#11330 <https://github.com/pypa/pip/issues/11330>`_)
+
+
+22.2.1 (2022-07-27)
+===================
+
+Bug Fixes
+---------
+
+- Send the pip upgrade prompt to stderr. (`#11282 <https://github.com/pypa/pip/issues/11282>`_)
+- Ensure that things work correctly in environments where setuptools-injected
+  ``distutils`` is available by default. This is done by cooperating with
+  setuptools' injection logic to ensure that pip uses the ``distutils`` from the
+  Python standard library instead. (`#11298 <https://github.com/pypa/pip/issues/11298>`_)
+- Clarify that ``pip cache``'s wheels-related output is about locally built wheels only. (`#11300 <https://github.com/pypa/pip/issues/11300>`_)
+
+
 22.2 (2022-07-21)
 =================
 

PKG-INFO

-Metadata-Version: 2.1
-Name: pip
-Version: 22.2
-Summary: The PyPA recommended tool for installing Python packages.
-Home-page: https://pip.pypa.io/
-Author: The pip developers
-Author-email: distutils-sig@python.org
-License: MIT
-Project-URL: Documentation, https://pip.pypa.io
-Project-URL: Source, https://github.com/pypa/pip
-Project-URL: Changelog, https://pip.pypa.io/en/stable/news/
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Topic :: Software Development :: Build Tools
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: Implementation :: CPython
-Classifier: Programming Language :: Python :: Implementation :: PyPy
-Requires-Python: >=3.7
-License-File: LICENSE.txt
-
-pip - The Python Package Installer
-==================================
-
-.. image:: https://img.shields.io/pypi/v/pip.svg
-   :target: https://pypi.org/project/pip/
-
-.. image:: https://readthedocs.org/projects/pip/badge/?version=latest
-   :target: https://pip.pypa.io/en/latest
-
-pip is the `package installer`_ for Python. You can use pip to install packages from the `Python Package Index`_ and other indexes.
-
-Please take a look at our documentation for how to install and use pip:
-
-* `Installation`_
-* `Usage`_
-
-We release updates regularly, with a new version every 3 months. Find more details in our documentation:
-
-* `Release notes`_
-* `Release process`_
-
-In pip 20.3, we've `made a big improvement to the heart of pip`_; `learn more`_. We want your input, so `sign up for our user experience research studies`_ to help us do it right.
-
-**Note**: pip 21.0, in January 2021, removed Python 2 support, per pip's `Python 2 support policy`_. Please migrate to Python 3.
-
-If you find bugs, need help, or want to talk to the developers, please use our mailing lists or chat rooms:
-
-* `Issue tracking`_
-* `Discourse channel`_
-* `User IRC`_
-
-If you want to get involved head over to GitHub to get the source code, look at our development documentation and feel free to jump on the developer mailing lists and chat rooms:
-
-* `GitHub page`_
-* `Development documentation`_
-* `Development mailing list`_
-* `Development IRC`_
-
-Code of Conduct
----------------
-
-Everyone interacting in the pip project's codebases, issue trackers, chat
-rooms, and mailing lists is expected to follow the `PSF Code of Conduct`_.
-
-.. _package installer: https://packaging.python.org/guides/tool-recommendations/
-.. _Python Package Index: https://pypi.org
-.. _Installation: https://pip.pypa.io/en/stable/installation/
-.. _Usage: https://pip.pypa.io/en/stable/
-.. _Release notes: https://pip.pypa.io/en/stable/news.html
-.. _Release process: https://pip.pypa.io/en/latest/development/release-process/
-.. _GitHub page: https://github.com/pypa/pip
-.. _Development documentation: https://pip.pypa.io/en/latest/development
-.. _made a big improvement to the heart of pip: https://pyfound.blogspot.com/2020/11/pip-20-3-new-resolver.html
-.. _learn more: https://pip.pypa.io/en/latest/user_guide/#changes-to-the-pip-dependency-resolver-in-20-3-2020
-.. _sign up for our user experience research studies: https://pyfound.blogspot.com/2020/03/new-pip-resolver-to-roll-out-this-year.html
-.. _Python 2 support policy: https://pip.pypa.io/en/latest/development/release-process/#python-2-support
-.. _Issue tracking: https://github.com/pypa/pip/issues
-.. _Discourse channel: https://discuss.python.org/c/packaging
-.. _Development mailing list: https://mail.python.org/mailman3/lists/distutils-sig.python.org/
-.. _User IRC: https://kiwiirc.com/nextclient/#ircs://irc.libera.chat:+6697/pypa
-.. _Development IRC: https://kiwiirc.com/nextclient/#ircs://irc.libera.chat:+6697/pypa-dev
-.. _PSF Code of Conduct: https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md
+Metadata-Version: 2.1
+Name: pip
+Version: 22.3
+Summary: The PyPA recommended tool for installing Python packages.
+Home-page: https://pip.pypa.io/
+Author: The pip developers
+Author-email: distutils-sig@python.org
+License: MIT
+Project-URL: Documentation, https://pip.pypa.io
+Project-URL: Source, https://github.com/pypa/pip
+Project-URL: Changelog, https://pip.pypa.io/en/stable/news/
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.7
+License-File: LICENSE.txt
+
+pip - The Python Package Installer
+==================================
+
+.. image:: https://img.shields.io/pypi/v/pip.svg
+   :target: https://pypi.org/project/pip/
+
+.. image:: https://readthedocs.org/projects/pip/badge/?version=latest
+   :target: https://pip.pypa.io/en/latest
+
+pip is the `package installer`_ for Python. You can use pip to install packages from the `Python Package Index`_ and other indexes.
+
+Please take a look at our documentation for how to install and use pip:
+
+* `Installation`_
+* `Usage`_
+
+We release updates regularly, with a new version every 3 months. Find more details in our documentation:
+
+* `Release notes`_
+* `Release process`_
+
+In pip 20.3, we've `made a big improvement to the heart of pip`_; `learn more`_. We want your input, so `sign up for our user experience research studies`_ to help us do it right.
+
+**Note**: pip 21.0, in January 2021, removed Python 2 support, per pip's `Python 2 support policy`_. Please migrate to Python 3.
+
+If you find bugs, need help, or want to talk to the developers, please use our mailing lists or chat rooms:
+
+* `Issue tracking`_
+* `Discourse channel`_
+* `User IRC`_
+
+If you want to get involved head over to GitHub to get the source code, look at our development documentation and feel free to jump on the developer mailing lists and chat rooms:
+
+* `GitHub page`_
+* `Development documentation`_
+* `Development IRC`_
+
+Code of Conduct
+---------------
+
+Everyone interacting in the pip project's codebases, issue trackers, chat
+rooms, and mailing lists is expected to follow the `PSF Code of Conduct`_.
+
+.. _package installer: https://packaging.python.org/guides/tool-recommendations/
+.. _Python Package Index: https://pypi.org
+.. _Installation: https://pip.pypa.io/en/stable/installation/
+.. _Usage: https://pip.pypa.io/en/stable/
+.. _Release notes: https://pip.pypa.io/en/stable/news.html
+.. _Release process: https://pip.pypa.io/en/latest/development/release-process/
+.. _GitHub page: https://github.com/pypa/pip
+.. _Development documentation: https://pip.pypa.io/en/latest/development
+.. _made a big improvement to the heart of pip: https://pyfound.blogspot.com/2020/11/pip-20-3-new-resolver.html
+.. _learn more: https://pip.pypa.io/en/latest/user_guide/#changes-to-the-pip-dependency-resolver-in-20-3-2020
+.. _sign up for our user experience research studies: https://pyfound.blogspot.com/2020/03/new-pip-resolver-to-roll-out-this-year.html
+.. _Python 2 support policy: https://pip.pypa.io/en/latest/development/release-process/#python-2-support
+.. _Issue tracking: https://github.com/pypa/pip/issues
+.. _Discourse channel: https://discuss.python.org/c/packaging
+.. _User IRC: https://kiwiirc.com/nextclient/#ircs://irc.libera.chat:+6697/pypa
+.. _Development IRC: https://kiwiirc.com/nextclient/#ircs://irc.libera.chat:+6697/pypa-dev
+.. _PSF Code of Conduct: https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md

README.rst

@@ -33,7 +33,6 @@ If you want to get involved head over to GitHub to get the source code, look at
 
 * `GitHub page`_
 * `Development documentation`_
-* `Development mailing list`_
 * `Development IRC`_
 
 Code of Conduct
@@ -56,7 +55,6 @@ rooms, and mailing lists is expected to follow the `PSF Code of Conduct`_.
 .. _Python 2 support policy: https://pip.pypa.io/en/latest/development/release-process/#python-2-support
 .. _Issue tracking: https://github.com/pypa/pip/issues
 .. _Discourse channel: https://discuss.python.org/c/packaging
-.. _Development mailing list: https://mail.python.org/mailman3/lists/distutils-sig.python.org/
 .. _User IRC: https://kiwiirc.com/nextclient/#ircs://irc.libera.chat:+6697/pypa
 .. _Development IRC: https://kiwiirc.com/nextclient/#ircs://irc.libera.chat:+6697/pypa-dev
 .. _PSF Code of Conduct: https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md

docs/html/cli/pip_download.rst

@@ -43,7 +43,9 @@ match the constraint of the current interpreter (but not your target one), it
 is recommended to specify all of these options if you are specifying one of
 them. Generic dependencies (e.g. universal wheels, or dependencies with no
 platform, abi, or implementation constraints) will still match an over-
-constrained download requirement.
+constrained download requirement. If some of your dependencies are not
+available as binaries, you can build them manually for your target platform
+and let pip download know where to find them using ``--find-links``.
 
 
 

docs/html/cli/pip_install.rst

@@ -219,18 +219,10 @@ details) is selected.
 
 See the :ref:`pip install Examples<pip install Examples>`.
 
+.. _`0-ssl certificate verification`:
+.. rubric:: SSL Certificate Verification
 
-.. _`SSL Certificate Verification`:
-
-SSL Certificate Verification
-----------------------------
-
-Starting with v1.3, pip provides SSL certificate verification over HTTP, to
-prevent man-in-the-middle attacks against PyPI downloads. This does not use
-the system certificate store but instead uses a bundled CA certificate
-store. The default bundled CA certificate store certificate store may be
-overridden by using ``--cert`` option or by using ``PIP_CERT``,
-``REQUESTS_CA_BUNDLE``, or ``CURL_CA_BUNDLE`` environment variables.
+This is now covered in :doc:`../topics/https-certificates`.
 
 .. _`0-caching`:
 .. rubric:: Caching

docs/html/cli/pip_wheel.rst

@@ -30,6 +30,14 @@ Description
 
 This is now covered in :doc:`../reference/build-system/index`.
 
+Differences to ``build``
+------------------------
+
+`build <https://pypi.org/project/build/>`_ is a simple tool which can among other things build
+wheels for projects using PEP 517. It is comparable to the execution of ``pip wheel --no-deps .``.
+It can also build source distributions which is not possible with ``pip``.
+``pip wheel`` covers the wheel scope of ``build`` but offers many additional features.
+
 Options
 =======
 

docs/html/installation.md

@@ -45,6 +45,34 @@ More details about this script can be found in [pypa/get-pip]'s README.
 
 [pypa/get-pip]: https://github.com/pypa/get-pip
 
+### Standalone zip application
+
+```{note}
+The zip application is currently experimental. We test that pip runs correctly
+in this form, but it is possible that there could be issues in some situations.
+We will accept bug reports in such cases, but for now the zip application should
+not be used in production environments.
+```
+
+In addition to installing pip in your environment, pip is available as a
+standalone [zip application](https://docs.python.org/3.11/library/zipapp.html).
+This can be downloaded from <https://bootstrap.pypa.io/pip/pip.pyz>. There are
+also zip applications for specific pip versions, named `pip-X.Y.Z.pyz`.
+
+The zip application can be run using any supported version of Python:
+
+```{pip-cli}
+$ python pip.pyz --help
+```
+
+If run directly:
+
+```{pip-cli}
+$ pip.pyz --help
+```
+
+then the currently active Python interpreter will be used.
+
 ## Alternative Methods
 
 Depending on how you installed Python, there might be other mechanisms

docs/html/reference/inspect-report.md

@@ -44,7 +44,7 @@ the following properties:
   `.egg-info` directory.
 
   ```{warning}
-  This field may not necessary point to a directory, for instance, in the case of older
+  This field may not necessarily point to a directory, for instance, in the case of older
   `.egg` installs.
   ```
 

docs/html/topics/caching.md

@@ -96,7 +96,7 @@ In some cases, pip's caching behaviour can be undesirable. As an example, if you
 have package with optional C extensions, that generates a pure Python wheel
 when the C extension can’t be built, pip will use that cached wheel even when
 you later invoke it from an environment that could have built those optional C
-extensions. This is because pip is seeing a cached wheel for that matches the
+extensions. This is because pip is seeing a cached wheel that matches the
 package being built, and pip assumes that the result of building a package from
 a package index is deterministic.
 
@@ -140,6 +140,6 @@ The {ref}`pip cache` command can be used to manage pip's cache.
 
 pip's caching behaviour is disabled by passing the `--no-cache-dir` option.
 
-It is, however, recommended to **NOT** disable pip's caching. Doing so can
+It is, however, recommended to **NOT** disable pip's caching unless you have caching at a higher level (eg: layered caches in container builds). Doing so can
 significantly slow down pip (due to repeated operations and package builds)
 and result in significantly more network usage.

docs/html/topics/configuration.md

@@ -11,6 +11,10 @@ pip allows a user to change its behaviour via 3 mechanisms:
 This page explains how the configuration files and environment variables work,
 and how they are related to pip's various command line options.
 
+```{seealso}
+{doc}`../cli/pip_config` command, which helps manage pip's configuration.
+```
+
 (config-file)=
 
 ## Configuration Files

docs/html/topics/dependency-resolution.md

@@ -155,7 +155,7 @@ how to inspect:
 - their release notes and changelogs from past versions
 
 During deployment, you can create a lockfile stating the exact package and
-version number for for each dependency of that package. You can create this
+version number for each dependency of that package. You can create this
 with [pip-tools](https://github.com/jazzband/pip-tools/).
 
 This means the "work" is done once during development process, and thus

docs/html/topics/deps.dot

+digraph G {
+  graph [fontname = "Handlee"];
+  node [fontname = "Handlee"];
+  edge [fontname = "Handlee"];
+
+  bgcolor=transparent;
+
+  A [color=blue fontcolor=blue];
+  A -> B [color=red];
+  A -> C [color=red];
+  node [color=lightgrey fontcolor=lightgrey];
+  edge [color=lightgrey];
+  node [color=lightgrey];
+  B -> B1;
+  B -> B2;
+  C -> C1;
+  C -> C2;
+
+}

docs/html/topics/https-certificates.md

+(SSL Certificate Verification)=
+
+# HTTPS Certificates
+
+```{versionadded} 1.3
+
+```
+
+By default, pip will perform SSL certificate verification for network
+connections it makes over HTTPS. These serve to prevent man-in-the-middle
+attacks against package downloads. This does not use the system certificate
+store but, instead, uses a bundled CA certificate store from {pypi}`certifi`.
+
+## Using a specific certificate store
+
+The `--cert` option (and the corresponding `PIP_CERT` environment variable)
+allow users to specify a different certificate store/bundle for pip to use. It
+is also possible to use `REQUESTS_CA_BUNDLE` or `CURL_CA_BUNDLE` environment
+variables.
+
+## Using system certificate stores
+
+```{versionadded} 22.2
+Experimental support, behind `--use-feature=truststore`.
+```
+
+It is possible to use the system trust store, instead of the bundled certifi
+certificates for verifying HTTPS certificates. This approach will typically
+support corporate proxy certificates without additional configuration.
+
+In order to use system trust stores, you need to:
+
+- Use Python 3.10 or newer.
+- Install the {pypi}`truststore` package, in the Python environment you're
+  running pip in.
+
+  This is typically done by installing this package using a system package
+  manager or by using pip in {ref}`Hash-checking mode` for this package and
+  trusting the network using the `--trusted-host` flag.
+
+  ```{pip-cli}
+  $ python -m pip install truststore
+  [...]
+  $ python -m pip install SomePackage --use-feature=truststore
+  [...]
+  Successfully installed SomePackage
+  ```
+
+### When to use
+
+You should try using system trust stores when there is a custom certificate
+chain configured for your system that pip isn't aware of. Typically, this
+situation will manifest with an `SSLCertVerificationError` with the message
+"certificate verify failed: unable to get local issuer certificate":
+
+```{pip-cli}
+$ pip install -U SomePackage
+[...]
+   SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (\_ssl.c:997)'))) - skipping
+```
+
+This error means that OpenSSL wasn't able to find a trust anchor to verify the
+chain against. Using system trust stores instead of certifi will likely solve
+this issue.
+
+If you encounter a TLS/SSL error when using the `truststore` feature you should
+open an issue on the [truststore GitHub issue tracker] instead of pip's issue
+tracker. The maintainers of truststore will help diagnose and fix the issue.
+
+[truststore github issue tracker]:
+  https://github.com/sethmlarson/truststore/issues

docs/html/topics/index.md

@@ -14,8 +14,11 @@ authentication
 caching
 configuration
 dependency-resolution
+more-dependency-resolution
+https-certificates
 local-project-installs
 repeatable-installs
 secure-installs
 vcs-support
+python-option
 ```

docs/html/topics/more-dependency-resolution.md

+# More on Dependency Resolution
+
+This article goes into more detail about pip's dependency resolution algorithm.
+In certain situations, pip can take a long time to determine what to install,
+and this article is intended to help readers understand what is happening
+"behind the scenes" during that process.
+
+```{note}
+This document is a work in progress. The details included are accurate (at the
+time of writing), but there is additional information, in particular around
+pip's interface with resolvelib, which have not yet been included.
+
+Contributions to improve this document are welcome.
+```
+
+## The dependency resolution problem
+
+The process of finding a set of packages to install, given a set of dependencies
+between them, is known to be an [NP-hard](https://en.wikipedia.org/wiki/NP-hardness)
+problem. What this means in practice is roughly that the process scales
+*extremely* badly as the size of the problem increases. So when you have a lot
+of dependencies, working out what to install will, in the worst case, take a
+very long time.
+
+The practical implication of that is that there will always be some situations
+where pip cannot determine what to install in a reasonable length of time. We
+make every effort to ensure that such situations happen rarely, but eliminating
+them altogether isn't even theoretically possible. We'll discuss what options
+yopu have if you hit a problem situation like this a little later.
+
+## Python specific issues
+
+Many algorithms for handling dependency resolution assume that you know the
+full details of the problem at the start - that is, you know all of the
+dependencies up front. Unfortunately, that is not the case for Python packages.
+With the current package index structure, dependency metadata is only available
+by downloading the package file, and extracting the data from it. And in the
+case of source distributions, the situation is even worse as the project must
+be built after being downloaded in order to determine the dependencies.
+
+Work is ongoing to try to make metadata more readily available at lower cost,
+but at the time of writing, this has not been completed.
+
+As downloading projects is a costly operation, pip cannot pre-compute the full
+dependency tree. This means that we are unable to use a number of techniques
+for solving the dependency resolution problem. In practice, we have to use a
+*backtracking algorithm*.
+
+## Dependency metadata
+
+It is worth discussing precisely what metadata is needed in order to drive the
+package resolution process. There are essentially three key pieces of
+information:
+
+* The project name
+* The release version
+* The dependencies themselves
+
+There are other pieces of data (e.g., extras, python version restrictions, wheel
+compatibility tags) which are used as well, but they do not fundamentally
+alter the process, so we will ignore them here.
+
+The most important information is the project name and version. Those two pieces
+of information identify an individual "candidate" for installation, and must
+uniquely identify such a candidate. Name and version must be available from the
+moment the candidate object is created. This is not an issue for distribution
+files (sdists and wheels) as that data is available from the filename, but for
+unpackaged source trees, pip needs to call the build backend to ask for that
+data. This is done before resolution proper starts.
+
+The dependency data is *not* requested in advance (as noted above, doing so
+would be prohibitively costly, and for a backtracking algorithm it isn't
+needed). Instead, pip requests dependency data "on demand", as the algorithm
+starts to check that particular candidate.
+
+One particular implication of the lazy fetching of dependency data is that
+often, pip *does not know* things that might be obvious to a human looking at
+the dependency tree as a whole. For example, if package A depends on version
+1.0 of package B, it's obvious to a human that there's no point in looking at
+other versions of package B. But if pip starts looking at B before it has
+considered A, it doesn't have access to A's dependency data, and so has no way
+of knowing that looking at other versions of B is wasted work. And worse still,
+pip cannot even know that there's vital information in A's dependencies.
+
+This latter point is a common theme with many cases where pip takes a long time
+to complete a resolution - there's information pip doesn't know at the point
+where it makes a "wrong" choice. Most of the heuristics added to the resolver
+to guide the algorithm are designed to guess correctly in the face of that
+lack of knowledge.
+
+## The resolver and the finder
+
+So far, we have been talking about the "resolver" as a single entity. While that
+is mostly true, the process of getting package data from an index is handled
+by another component of pip, the "finder". The finder is responsible for
+feeding candidates to the resolver, and has a key role to play in selecting
+suitable candidates.
+
+Note that the resolver is *only* relevant for packages fetched from an index.
+Candidates coming from other sources (local source directories, PEP 508
+direct URL references) do *not* go through the finder, and are merged with the
+candidates provided by the finder as part of the resolver's "provider"
+implementation.
+
+As well as determining what versions exist in the index for a given project,
+the finder selects the best distribution file to use for that candidate. This
+may be a wheel or a source distribution, and precisely what is selected is
+controlled by wheel compatibility tags, pip's options (whether to prefer binary
+or source) and metadata supplied by the index. In particular, if a file is
+marked as only being for specific Python versions, the file will be ignored by
+the finder (and the resolver may never even see that version).
+
+The finder also provides candidates for a project to the resolver in order of
+preference - the provider implements the rule that later versions are preferred
+over older versions, for example.
+
+## The resolver algorithm
+
+The resolver itself is based on a separate package, [resolvelib](https://pypi.org/project/resolvelib/).
+This implements an abstract backtracking resolution algorithm, in a way that is
+independent of the specifics of Python packages - those specifics are abstracted
+away by pip before calling the resolver.
+
+Pip's interface to resolvelib is in the form of a "provider", which is the
+interface between pip's model of packages and the resolution algorithm. The
+provider deals in "candidates" and "requirements" and implements the following
+operations:
+
+* `identify` - implements identity for candidates and requirements. It is this
+  operation that implements the rule that candidates are identified by their
+  name and version, for example.
+* `get_preference` - this provides information to the resolver to help it choose
+  which requirement to look at "next" when working through the resolution
+  process.
+* `find_matches` - given a set of constraints, determine what candidates exist
+  that satisfy them. This is essentially where the finder interacts with the
+  resolver.
+* `is_satisfied_by` - checks if a candidate satisfies a requirement. This is
+  basically the implementation of what a requirement meams.
+* `get_dependencies` - get the dependency metadata for a candidate. This is
+  the implementation of the process of getting and reading package metadata.
+
+Of these methods, the only non-trivial one is the `get_preference` method. This
+implements the heuristics used to guide the resolution, telling it which
+requirement to try to satisfy next. It's this method that is responsible for
+trying to guess which route through the dependency tree will be most productive.
+As noted above, it's doing this with limited information. See the following
+diagram
+
+![](deps.png)
+
+When the provider is asked to choose between the red requirements (A->B and
+A->C) it doesn't know anything about the dependencies of B or C (i.e., the
+grey parts of the graph).
+
+Pip's current implementation of the provider implements `get_preference` as
+follows:
+
+* Prefer if any of the known requirements is "direct", e.g. points to an
+    explicit URL.
+* If equal, prefer if any requirement is "pinned", i.e. contains
+    operator ``===`` or ``==``.
+* If equal, calculate an approximate "depth" and resolve requirements
+    closer to the user-specified requirements first.
+* Order user-specified requirements by the order they are specified.
+* If equal, prefers "non-free" requirements, i.e. contains at least one
+    operator, such as ``>=`` or ``<``.
+* If equal, order alphabetically for consistency (helps debuggability).

docs/html/topics/python-option.md

+# Managing a different Python interpreter
+
+```{versionadded} 22.3
+```
+
+Occasionally, you may want to use pip to manage a Python installation other than
+the one pip is installed into. In this case, you can use the `--python` option
+to specify the interpreter you want to manage. This option can take one of two
+values:
+
+1. The path to a Python executable.
+2. The path to a virtual environment.
+
+In both cases, pip will run exactly as if it had been invoked from that Python
+environment.
+
+One example of where this might be useful is to manage a virtual environment
+that does not have pip installed.
+
+```{pip-cli}
+$ python -m venv .venv --without-pip
+$ pip --python .venv install SomePackage
+[...]
+Successfully installed SomePackage
+```
+
+You could also use `--python .venv/bin/python` (or on Windows,
+`--python .venv\Scripts\python.exe`) if you wanted to be explicit, but the
+virtual environment name is shorter and works exactly the same.

docs/html/topics/repeatable-installs.md

@@ -20,7 +20,7 @@ specific version.
 ```
 
 A requirements file, containing pinned package versions can be generated using
-{ref}`pip freeze`. This would not only the top-level packages, but also all of
+{ref}`pip freeze`. This would pin not only the top-level packages, but also all of
 their transitive dependencies. Performing the installation using
 {ref}`--no-deps <install_--no-deps>` would provide an extra dose of insurance
 against installing anything not explicitly listed.