Diagnostic Error for Resolution Too Deep

[notatallshaw]

This adds additional documentation and a diagnostic error when ResolutionTooDeep is thrown from resolvelib.

Further, it points users, who have read the documentation, to the issue #13281 that I would like to maintain and use to collect reports of ResolutionTooDeep.

I am motivated both for collecting these kind of errors in general from users because I'm worried they have been under reported, and because resolvelib 1.1.0 makes these errors more likely for some complex requirements.

The error looks like this:

error: resolution-too-deep

× Dependency resolution exceeded maximum depth
╰─> Pip cannot resolve the current dependencies as the dependency graph is too complex for pip to solve efficiently.

hint: 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

I appreciate I am doing a couple of extra things here compared to normal, feedback welcome.

[ichard26]

Looks good. I'm worried that not many people will see the call to action to report ResolutionTooDeep errors in the documentation (we know how likely users are to read documentation...). It'll likely select for only the individuals with the very complex scenarios or who are unable to address themselves. Is that the intention?

We could put the issue in the error directly (at least for a single release cycle). That would have the opposite problem where we may be flooded with (possibly low-quality) reports. Given this is your project, I'll leave to you to decide how you want to approach engaging with community reports.

[notatallshaw]

It'll likely select for only the individuals with the very complex scenarios or who are unable to address themselves. Is that the intention?

Yes, my intent with this PR was to deliberately make it so users only found the issue if they read through the documentation, hopefully increasing the chance of higher quality reports.

We could put the issue in the error directly (at least for a single release cycle).

I thought quite a bit about that and for a number of reasons I decided I'd rather link users to the official documentation rather than an issues link. As well as the above reason, pip gets used in all sorts of places, and I'd rather users were guided toward the official documentation rather than GitHub for resolving an error.

[ichard26]

Coolio 👍. I'll let you merge this PR when you see fit. Thanks for working on this!