docs: Description of "--upgrade-strategy=only-if-needed" seems inconsistent?

[EricCousineau-TRI]

Environment

N/A

Description

See doc permalinks (through GitHub, I dunno how to permalink the pypa.io stuff):

• https://github.com/pypa/pip/blob/f17c1d6d3bf4b4ee8b7b0e669c449b9cd86e94f6/docs/html/user_guide.rst#only-if-needed-recursive-upgrade
• https://github.com/pypa/pip/blob/f17c1d6d3bf4b4ee8b7b0e669c449b9cd86e94f6/docs/html/development/architecture/upgrade-options.rst#controlling-what-gets-installed

Non-permlinks:

• https://pip.pypa.io/en/stable/reference/pip_install/?highlight=upgrade#cmdoption-u
• https://pip.pypa.io/en/stable/development/architecture/upgrade-options/#controlling-what-gets-installed

In the "user-guide" section, --upgrade-strategy=only-if-needed is described as upgrading only if the existing package does not meet given requirements. However, in the "architecture" section, --upgrade-strategy=to-satisfy-only seems to cover this, while only-if-needed seems to now upgrade iff the package is a direct dependency.

Expected behavior

The docs match? Or, at least if to-satisfy-only is to remain hidden away, at least the behavior of only-if-needed is reconciled?

How to Reproduce

See citations above.

Output

N/A

\cc @thduynguyen

[uranusjr]

Both docs are correct, but the wording is a bit confusing. to-satisfy-only is indeed intended to be hidden from the user, and never passed in from the command line manually; it is only set internally when you *don’t° pass --upgrade. The other two options imply the user is passing in --upgrade. So “dependencies” in the user guide are excluding packages specified in the command line by the user, since persuambly the user want them upgraded, and therefore shouldn’t be covered by this “not upgraded unless needed” rule.

[EricCousineau-TRI]

Gotcha. So one way to solve is mention in the user-facing docs what happens when --upgrade is not passed, and then have the dev docs more explicitly link to-satisfy-only to that case.

However, I feel that it doesn't cover the fact that the only-if-needed is still inconsistent -- in the user docs, --upgrade --upgrade-strategy=only-if-needed in the user docs really corresponds to [--noupgrade] --upgrade-strategy=to-satisfy-only, whereas from the dev docs, the behavior of --upgrade --upgrade=strategy=only-if-needed isn't really mentioned in the user docs?

[uranusjr]

Both only-if-needed descriptions are correct. You are messing up the subject of each documentation.

Here’s a run down of the differences. Say you have a and b installed, and b depends on some certain versions of a...

• pip install b without any upgrade flags (i.e. to-satisfy-only):
  • b is never reinstalled even if there is a newer version.
  • a is reinstalled only if the currently installed versions does not satisfy b as a dependency.
• pip install b --upgrade (i.e. only-if-needed):
  • b is reinstalled if there is a newer version.
  • a is reinstalled only if the currently installed versions does not satisfy b as a dependency.

The user documentation says --upgrade-strategy controls how dependency upgrading should be handled, which only covers a, not b (since the latter is user-specified). The two values behaves the same for a (which is a non-user-specified package, i.e. “dependency”), so there is no mismatch here.

[EricCousineau-TRI]

Ah, gotcha. I read "direct requirements" as "direct dependency of requirements", as you've pointed out.

So then a better solution (to help lazy people like me :P) would be to use the same wording in both places (if possible), and possibly copy the explanation from dev docs to the user docs, possibly with your example in tow. Will take a whack at it.

[uranusjr]

The difficult part would to figure out what the best wording is. Packages probably won’t work in the --upgrade-strategy user docs (confused user: what do you mean pip only upgrades packages if needed when I supply --upgrade?) but dependency is a vague for developers since it is often used as a synonym to requirements and includes user-specified ones. I am pretty bad at this though and won’t be surprised if there’s a good solution that I didn’t think of.