Merge branch 'main' into fix-direct-preference

Author: notatallshaw

docs/html/topics/dependency-resolution.md

@@ -39,7 +39,7 @@ of how dependency resolution for Python packages works.
 The user requests `pip install tea`. The package `tea` declares a dependency on
 `hot-water`, `spoon`, `cup`, amongst others.
 
-pip starts by picking the most recent version of `tea` and get the list of
+pip starts by picking the most recent version of `tea` and gets the list of
 dependencies of that version of `tea`. It will then repeat the process for
 those packages, picking the most recent version of `spoon` and then `cup`. Now,
 pip notices that the version of `cup` it has chosen is not compatible with the
@@ -245,7 +245,7 @@ To find a version of both `package_coffee` and `package_tea` that depend on
 the same version of `package_water`, you might consider:
 
 - Loosening the range of packages that you are prepared to install
-  (e.g. `pip install "package_coffee>0.44.*" "package_tea>4.0.0"`)
+  (e.g. `pip install "package_coffee>0.44" "package_tea>4.0.0"`)
 - Asking pip to install _any_ version of `package_coffee` and `package_tea`
   by removing the version specifiers altogether (e.g.
   `pip install package_coffee package_tea`)
@@ -298,7 +298,70 @@ In this situation, you could consider:
 - Refactoring your project to reduce the number of dependencies (for
   example, by breaking up a monolithic code base into smaller pieces).
 
-### Getting help
+## Handling Resolution Too Deep Errors
+
+Sometimes pip's dependency resolver may exceed its search depth and terminate
+with a `ResolutionTooDeepError` exception. This typically occurs when the
+dependency graph is extremely complex or when there are too many package
+versions to evaluate.
+
+To address this error, consider the following strategies:
+
+### Specify Reasonable Lower Bounds
+
+By setting a higher lower bound for your dependencies, you narrow the search
+space. This excludes older versions that might trigger excessive backtracking.
+For example:
+
+```{pip-cli}
+$ pip install "package_coffee>=0.44.0" "package_tea>=4.0.0"
+```
+
+### Use the `--upgrade` Flag
+
+The `--upgrade` flag directs pip to ignore already installed versions and
+search for the latest versions that meet your requirements. This can help
+avoid unnecessary resolution paths:
+
+```{pip-cli}
+$ pip install --upgrade package_coffee package_tea
+```
+
+### Utilize Constraint Files
+
+If you need to impose additional version restrictions on transitive
+dependencies (dependencies of dependencies), consider using a constraint
+file. A constraint file specifies version limits for packages that are
+indirectly required. For example:
+
+```
+# constraints.txt
+indirect_dependency>=2.0.0
+```
+
+Then install your packages with:
+
+```{pip-cli}
+$ pip install --constraint constraints.txt package_coffee package_tea
+```
+
+### Use Upper Bounds Sparingly
+
+Although upper bounds are generally discouraged because they can complicate
+dependency management, they may be necessary when certain versions are known
+to cause conflicts. Use them cautiously—for example:
+
+```{pip-cli}
+$ pip install "package_coffee>=0.44.0,<1.0.0" "package_tea>=4.0.0"
+```
+
+### Report ResolutionTooDeep Errors
+
+If you encounter a `ResolutionTooDeep` error consider reporting it, to help
+the pip team have real world examples to test against, at the dedicated
+[pip issue](https://github.com/pypa/pip/issues/13281).
+
+## Getting help
 
 If none of the suggestions above work for you, we recommend that you ask
 for help on:

news/12649.feature.rst

@@ -0,0 +1 @@
+Suggest checking "pip config debug" in case of an InvalidProxyURL error.

news/12903.bugfix.rst

@@ -0,0 +1 @@
+Support multiple global configuration paths returned by ``platformdirs`` on MacOS.

news/13282.feature.rst

@@ -0,0 +1,2 @@
+Provide hint, documentation, and link to the documentation when
+resolution too deep error occurs.

news/9727.bugfix.rst

@@ -0,0 +1 @@
+Fix fish shell completion when commandline contains multiple commands.

pyproject.toml

@@ -168,6 +168,7 @@ ignore = [
     "B020",
     "B904", # Ruff enables opinionated warnings by default
     "B905", # Ruff enables opinionated warnings by default
+    "C420", # unnecessary-dict-comprehension-for-iterable (worsens readability)
 ]
 select = [
     "ASYNC",

src/pip/_internal/commands/completion.py

@@ -38,12 +38,18 @@
     """,
     "fish": """
         function __fish_complete_pip
-            set -lx COMP_WORDS (commandline -o) ""
-            set -lx COMP_CWORD ( \\
-                math (contains -i -- (commandline -t) $COMP_WORDS)-1 \\
-            )
+            set -lx COMP_WORDS \\
+                (commandline --current-process --tokenize --cut-at-cursor) \\
+                (commandline --current-token --cut-at-cursor)
+            set -lx COMP_CWORD (math (count $COMP_WORDS) - 1)
             set -lx PIP_AUTO_COMPLETE 1
-            string split \\  -- (eval $COMP_WORDS[1])
+            set -l completions
+            if string match -q '2.*' $version
+                set completions (eval $COMP_WORDS[1])
+            else
+                set completions ($COMP_WORDS[1])
+            end
+            string split \\  -- $completions
         end
         complete -fa "(__fish_complete_pip)" -c {prog}
     """,

src/pip/_internal/commands/install.py

@@ -8,6 +8,7 @@
 from typing import List, Optional
 
 from pip._vendor.packaging.utils import canonicalize_name
+from pip._vendor.requests.exceptions import InvalidProxyURL
 from pip._vendor.rich import print_json
 
 # Eagerly import self_outdated_check to avoid crashes. Otherwise,
@@ -766,6 +767,13 @@ def create_os_error_message(
             parts.append(permissions_part)
         parts.append(".\n")
 
+    # Suggest to check "pip config debug" in case of invalid proxy
+    if type(error) is InvalidProxyURL:
+        parts.append(
+            'Consider checking your local proxy configuration with "pip config debug"'
+        )
+        parts.append(".\n")
+
     # Suggest the user to enable Long Paths if path length is
     # more than 260
     if (

src/pip/_internal/exceptions.py

@@ -807,3 +807,23 @@ def __init__(
             ),
             hint_stmt="To proceed this package must be uninstalled.",
         )
+
+
+class ResolutionTooDeepError(DiagnosticPipError):
+    """Raised when the dependency resolver exceeds the maximum recursion depth."""
+
+    reference = "resolution-too-deep"
+
+    def __init__(self) -> None:
+        super().__init__(
+            message="Dependency resolution exceeded maximum depth",
+            context=(
+                "Pip cannot resolve the current dependencies as the dependency graph "
+                "is too complex for pip to solve efficiently."
+            ),
+            hint_stmt=(
+                "Try adding lower bounds to constrain your dependencies, "
+                "for example: 'package>=2.0.0' instead of just 'package'. "
+            ),
+            link="https://pip.pypa.io/en/stable/topics/dependency-resolution/#handling-resolution-too-deep-errors",
+        )

src/pip/_internal/resolution/resolvelib/resolver.py

@@ -5,11 +5,12 @@
 from typing import TYPE_CHECKING, Dict, List, Optional, Set, Tuple, cast
 
 from pip._vendor.packaging.utils import canonicalize_name
-from pip._vendor.resolvelib import BaseReporter, ResolutionImpossible
+from pip._vendor.resolvelib import BaseReporter, ResolutionImpossible, ResolutionTooDeep
 from pip._vendor.resolvelib import Resolver as RLResolver
 from pip._vendor.resolvelib.structs import DirectedGraph
 
 from pip._internal.cache import WheelCache
+from pip._internal.exceptions import ResolutionTooDeepError
 from pip._internal.index.package_finder import PackageFinder
 from pip._internal.operations.prepare import RequirementPreparer
 from pip._internal.req.constructors import install_req_extend_extras
@@ -102,6 +103,8 @@ def resolve(
                 collected.constraints,
             )
             raise error from e
+        except ResolutionTooDeep:
+            raise ResolutionTooDeepError from None
 
         req_set = RequirementSet(check_supported_wheels=check_supported_wheels)
         # process candidates with extras last to ensure their base equivalent is