Rename --no-binary as --no-download-binary so that --no-binary can emit a warning

[paugier]

What's the problem this feature will solve?

I try to split issue #12954 in smaller and more tractable issues.

As discussed in detailed in #12954, the option --no-binary was used in particular for HPC to rebuild a package from source with different build arguments, environment variables or different libraries (for example hdf5 sequential/parallel, or openMPI/MPICH). Another similar application is about build options used for some projects, for example pydantic is sensible to SKIP_CYTHON and Mercurial can be built with or without Rust extensions.

However, since 23.1 (https://pip.pypa.io/en/stable/news/#v23-1), "--no-binary does not disable the cache of locally built wheels anymore. It only means “don’t download wheels”. (#11453)".

We have an option called --no-binary which previously meant "no wheels" (name was fine) and which now means “don’t download wheels” (which is very different).

As pointed out #12954 (comment), web documentation and supercomputer tutorials still use --no-binary to ask for rebuild because of the old behavior (before 23.1), the misleading name of this option and most pip users do not usually read pip release notes.

Since the difference is subtle (sometimes, depending on the cache, --no-binary works as expected), as long as --no-binary does not emit a clear warning, some pip users will continue to use it for what it was used before 23.1, i.e. to ask for a rebuild. But it does not work any longer like that and people will sometimes get the wrong behavior. Sometimes, they will notice but if they are not careful enough, they will just use wrong wheels, with various bad consequences.

Describe the solution you'd like

Therefore, --no-binary should be renamed as --no-download-binary (or something similar) so that --no-binary can emit a clear warning, something like:

"--no-binary now only discard downloaded wheels. Use --no-download-binary to avoid this warning."

When we have pip install --rebuild (#13088), we should also mention this different option in the warning.

Alternative Solutions

• We could have something else than --no-download-binary for the new name.

• --no-binary could also be properly deprecated (i.e. completely replaced in the long term by --no-download-binary) but I guess it won't be accepted and I agree that it is not strictly necessary.

Additional context

See #12954

Code of Conduct

• I agree to follow the PSF Code of Conduct.

[sbidoul]

Anyone considering this, please don't forget about the --prefer-binary, --only-binary. It might also be worth looking into the uv tracker to see if the options they copied from pip (with better docs) cause confusion to uv users or not.

[pfmoore]

IMO, --no-binary is still the correct way to describe this option. If it's specified, pip will use a source distribution. Yes, we cache the results of building from source (in the form of a wheel, but that's an implementation detail) but we cache various things, and I don't think this particular form of caching is that much different. See my comment on the --rebuild issue for further details.