Diagnostic Error for Resolution Too Deep

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
@@ -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/13282.feature.rst

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

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