`--pre` flag is ambiguous while used alongside other flags

[captn3m0]

Environment

• pip version: pip 20.1.1 from /usr/lib/python3.8/site-packages/pip
• Python version: (python 3.8)
• OS: ArchLinux

Description

The --pre flag is ambiguous while used alongside other flags. The documentation describes it as:

Include pre-release and development versions. By default, pip only finds stable versions.

A simple issue that arises is in usage while listing outdated packages.

Running pip list --outdated --pre gives a list of all packages that can be upgrade to a pre-release/development version.

Running pip list --pre gives a list of all installed packages, including those that are currently at a pre-release/development version.

The behavior of --pre is different in these 2 cases: The first decides the upgrade policy, while the second is just a list filter.

Broken behavior

The --pre filter in the pip list --outdated --pre gets applied twice in a sense:

1. First the pip list command is run against --pre so we have all packages including pre-releases.
2. Then the --pre upgrade policy is applied, so upgrades to all packages where a pre-release is available is shown.

How to Reproduce

First, install 2 packages where the meaning of --pre is different:

# Install stable version of this
pip install Jinja2 
# Install pre-release version of this
pip install mistune==2.0.0a4

Output

First we run pip list --outdated. Since Jinja2 is already at the most stable version, and there are no stable upgrades on mistune, this list is empty.

Then, we run it with the --pre flag to attempt an upgrade on mistune, which has a new pre-release.

pip list --outdated --pre
Package            Version Latest   Type
------------------ ------- -------- -----
Jinja2             2.11.2  3.0.0a1  wheel
mistune            2.0.0a4 2.0.0a5  wheel

This is where the ambigous behavior shows up, since --pre is taken as the upgrade policy and a upgrade for Jinja2 is also suggested.