Proposal: New arguments to control pre-releases

[notatallshaw]

Summary

This proposal introduces two new flags to pip:

• --all-releases <format_control>: Allows installing all versions of a package, including pre-releases.
• --only-final <format_control>: Restricts installation to final and post-releases only.

These flags provide fine-grained control over release selection, following similar syntax and semantics of --no-binary and --only-binary.

Motivation

Currently, pip's handling of pre-releases is controlled globally via --pre, but there's no package-specific control and no way to specify disabling pre-releases.

Further, pip has historically not selected prereleases in places where the spec says it should due to bugs in packaging (pypa/packaging#872 and pypa/packaging#794) so users haven't had as much need to "turn off" prereleases as they might in the future.

Specification

--all-releases <format_control>

Allows installation of all versions of a package, including pre-releases. Can be supplied multiple times, and each time adds to the existing value.

• Accepts :all: to allow pre-releases for all packages
• Accepts a package name to enable pre-releases for specific packages

Example Usage:

pip install --all-releases foo
pip install --all-releases foo --all-releases bar
pip install --all-releases :all:

--only-final <format_control>

Restricts installation to final and post-releases only. Can be supplied multiple times, and each time adds to the existing value.

• Accepts :all: to enforce only final releases for all packages
• Accepts a package name to enforce only final releases for specific packages

Example Usage:

pip install --only-final foo
pip install --only-final foo --only-final bar
pip install --only-final :all:

Design Notes

• --pre will be the equivalent of --all-releases :all:, and could eventually be deprecated
• Like --no-binary and --only-binary more specific things override less specific things, e,g, --all-releases :all: --only-final foo does not allow pre-releases for foo.
• I have not included the :none: syntax from --no-binary and --only-binary as I don't really understand the use case, but if there is a strong use case for it I can add it
• I have not included comma separated package names in the CLI as this seems like an unneeded complexity, but I haven't fully thought through how this would work with environmental variables, so I might come back to including this

Backward Compatibility

This change is fully backward-compatible, as it introduces new optional flags without altering existing behavior.

Implementation

If there's no significant objection I'm volunteering to implement this.

However this is not being funded by anyone so work will go at the pace that I have free time, if someone else is willing to fund or work on this please let me know and we can organize something.

Bikeshedding

I'm not strongly attached to the names here, I'm happy to accept other names, I'm more interested if there are objections to the design.

[notatallshaw]

An existing workaround

Granular enabling of pre-releases is technically already possible by creating a constraints file and adding:

foo>=0.0dev

However, as far as I'm aware, it is not an intended use case for constraints, and requires creating a file (can't fully be specified by either CLI or Env Vars).

[pfmoore]

In general, I'm in favour of this, as I think that giving users finer control in the (exceptional, hopefully!) cases where they need it is a good thing. But I'm a little concerned that pip's UI is already complex, and this adds more complexity. Unfortunately, I don't know enough about UI design to have a better idea of how to expose this functionality (I thought of having a "package selection mini-language" covering this and the various --{prefer,only,no}-binary options, but that's probably more complicated than a bunch of options).

I don't want the perfect to be the enemy of the good, though, so I'm fine with this proposal as it stands.