Add --python-platform to sync and install commands

[charliermarsh]

Summary

pip supports providing a --platform to pip install, which can be used to seed an environment (e.g., for use in a container or otherwise). This PR adds --python-platform to our commands to support a similar workflow. It has some caveats, which are documented on the CLI.

Closes #2079.

[BurntSushi]

I was having deja vu here, because I thought I had reviewed a change like this already. I did some digging and:

• Add a --platform argument to enable resolving against a target platform #3111 added initial support. It added it as --platform to only uv pip compile.
• Rename --platform to --python-platform #3146 renamed the flag from --platform to --python-platform, since pip also has a --platform flag and it doesn't match how ours behaves.
• Add --python-platform to configuration #3147 adds --python-platform to the configuration.
• This PR adds --python-platform to the uv pip sync and uv pip install commands.

So with all that context, I think this change makes sense, but:

• Can we add a test covering this flag for the uv pip sync and uv pip install commands? I think we have a test for uv pip compile, but it would be good to cover the other two as well.
• I mentioned this in a review comment, but what is the difference between pip's --platform and this --python-platform flag? And does there need to be a difference? Can we match what pip does instead?

[zanieb]

Can we add a test covering this flag for the uv pip sync and uv pip install commands? I think we have a test for uv pip compile, but it would be good to cover the other two as well.

Fwiw we've been intentionally not covering flags across every command. No comment on whether or not that's best.

[charliermarsh]

(I'll answer your other question after goal setting, it's a good one to record in GitHub.)

[charliermarsh]

...but what is the difference between pip's --platform and this --python-platform flag? And does there need to be a difference? Can we match what pip does instead?

Okay, so pip supports --platform, --abi, and --python-version. When provided, it basically takes those, and generates all the compatible target tags by generating combinations of the tree. If you provide --platform, you must either run with --no-deps or --only-binary :all:. And as far as I can tell, pip's --platform does not affect resolution (i.e., it does not change the markers; only the wheel tags).

So our --python-platform argument is slightly different. It's "higher-level", in that you describe a platform and then we generate the relevant wheel tags and markers. And we ship with fewer limitations, but with the risk that users may misuse the flag and create broken environments.

[danielhollas]

This last sentence is confusing given the preceding paragraph, perhaps you meant

Suggested change

	/// platform. This option is intended for cross-compilation and other advanced use cases.
	/// platform. This option is not intended for cross-compilation and other advanced use cases.

?

[charliermarsh]

I think "cross-compilation" is the wrong term. It is intended for advanced use-cases, but "cross-compilation" emphasizes building from source in the wrong way.

[danielhollas]

Ah, okay. Yeah, I was definitely also mislead by the preceding sentence that specifically talks about building from source.