pip new resolver: how pip helps a user understand why a dependency conflict occurs

[ei8fdb]

[Work in progress]

• pip version: upcoming
• Python version: all
• Operating system: all OSes

User story

As a pip user, I need pip to help me understand why a dependency conflict occurs, so that I can successfully install my package.

Research objective

Some high-level research questions we want to answer:

1. What information should the new resolver provide when each dependency conflict occurs?
2. What information can we provide the user so they can understand why the conflict has occured?
3. Where should that information be displayed?
4. How should that information be formatted?

Explanation

When a user is installing a package via pip, the resolver needs to work out which package is the candidate. There are cases - exceptions - where the resolver is unable to do this. Below are the 3 main exceptions:

Resolution impossible

This is a situation where the resolver is unable to identity a logical solution - every choice it can make has a conflict.

Why this happens

Some possible causes of this exception are:

1. Install package A versions X and Y
   e.g. "install packages banana, version 1 and version 2

2. Install package A greater than version X and less than version Y
   e.g. install package banana, the version can be greater than 3, and less than 1

3. Install package A, package B (which depends on package D less than version 3) and package C (which depends on package D greater than version 3)

These requests will fail as they are logically not possible to resolve.

What this means for the user

This results in the resolver not being able to install the requested package. The user then needs to make a decision of what to do next based on understanding 1) what has happened, 2) what has caused it, 3) possible next steps they can take to fix it.

Possible solutions

• document resolution strategies on how to resolve this

Documentation recommendations on pinning dependencies (e.g. you're less likely to see this issue if you have less pinned package versions). There are blogposts already. Can they be rolled into "if you don't know what to do, start with these options and these are the reasons why"? There are good exmamples already available

---

Resolution too-deep

Why this happens

This exception is caused by pip stopping the dependency resolution process, at some point. This stopping point is still to be defined.

This exception is caused by the resolver stopping the resolution - this could be due to a number of yet (undefined) reasons:

• the large search space (it has to search through a lot of packages in order to find a suitable candidate)
• the resolution process being computational expensive,
• it taking too long to resolve

What this means for the user

This results in the resolver not really know what packages are suitable candidates. In order to save the users' time and effort, the resolver stops.

This means the resolver cannot provide the user with an exact reason for the conflict.

We're not sure how big an issue this is for users, and we're not sure of what use cases cause this exception. So far there is only [one documented example of resolution:toodeep](https://github.com/pradyunsg/zazo/issues/20](https://github.com/pradyunsg/zazo/issues/20)

Objective

We need to understand what information the user needs to see in order to be able to fix this issue.

Possible solutions

Providing helpful information to the user will be difficult in this situation as pip doesn't really know why the issue has occurred. Any information we give the user will probably be vague.

There are some possible ways to help the user:
(NB: none of these have been decided on yet)

• tell the user "pip spent a lot of time resolving these dependencies, package A and B caused most problems, maybe you should focus on those"
• collect numbers after completion about successful and failed resolutions from users, so we know what is the better metric
• record counts of:
  • total discovered requirement/candidate count
  • round count
  • backtrack count
  • some to-be-defined user-specified requirement count

The counts could then be displayed after pip has finished the resolution. The user could then report those to the team. This wouldn't really help the user resolve the issue directly, but when reported the pip team and start the troubleshooting.

• and others

Research questions

• what use cases cause resolution:impossible?
• what information do they use the resolve this conflict?

---

Some questions to answer

1. What is useful context (e.g. what the pip resolver did internally to get here) for the user?
2. How should that information be formatted?
3. What are the situations where conflicts happen?

We can create different levels of message:

• The "ideal message"
• The "this is better than no message"
• The "this is not helpful" message!

We have already answered the following questions:

1. What information do users use to fix conflicts?
2. How detailed does the information be?
3. How much of the dependency chain do users want to know about?
4. What would users "like" pip to tell them about the conflict?
5. What information does the user need to understand why the conflict has occured?
6. Where do users expect to find this information? Logfiles? pip outputs? Somewhere?

Some design guidelines

(The use of must and should are best case pip behaviours. I understand some/all of these may not be possible)

Whatever the solution, these are some user-centred guidelines we will follow as much as possible:

• pip must tell the user what package(s) have caused the conflict
• pip should give the user some possible ways to solve the conflict
• if the user wants to override the conflict and force the install they should be able to
• the verbosity of the information should be configurable by the user
• the information could be logged permanently
• the messages need to be understandable by novice and experienced pip users
• documentation should be more "usage oriented" focused on possible solutions

[pfmoore]

See #8115 for discussions on how we document "what we do now".

The question here is about how closely what we do now matches with user expectations (and hopefully the answer will be "perfectly" 🙂). But there's always a question when the behaviour is defined based on "how the implementation works", hence the need for better user feedback.

[pradyunsg]

As some "prior art" in the area, poetry does not have any output during dependency resolution, and the verbose output prints the entire sequence of what-did-the-resolver-do logs.

[ei8fdb]

I'm closing this as we're using #8377 to document the ResolutionImpossible error message work.