Add uv python pin

[zanieb]

Adds a uv python pin command to write to a .python-version file.

We support all of our Python version request formats. We also support a --resolved flag to pin to a specific interpreter instead of the provided version. We canonicalize the request with #4949, it's not just printed verbatim. We always attempt to find the interpreter so we can warn if it's not available. With --resolved, if we can't find the interpreter we fail. If no arguments are provided, we'll attempt to display the current pin.

In the future:

• We should confirm that this satisfies the Requires-Python metadata if a pyproject.toml is present
• We should support writing to a uv.python-version field if pyproject.toml or uv.toml are present
• We should support finding and updating the "nearest" Python version file (looking in ancestors)
• We should support finding version files in workspaces
• We should support some sort of global pin

[charliermarsh]

Is .python-version parsed by other tools, though?

[zanieb]

I believe some tools will parse it, yes, but I'm not sure which. For most uses, we'll be writing a simple version. It may be fair to say if you go outside that it'll only be supported by us. We could also consider only supporting writing simple versions until we have pyproject.toml support, but we already support reading it so... idk.

[zanieb]

I'll do some research, but this might just be a caveat in the documentation?

[zanieb]

A brief Google search makes it look like just pyenv.

[charliermarsh]

Mise also parses it and Rye does too IIRC.

[zanieb]

So what are you thinking? What does mise do if it's not in the format it expects?

[charliermarsh]

I'm not certain, I can test it out.

[charliermarsh]

Actually, it looks like mise uses .tool-versions which is generic (not just for Python).

[charliermarsh]

It looks like if Rye doesn't recognize it, it just gets ignored.

[charliermarsh]

It just uses this:

/// Return the [`PythonVersionRequest`] from a `.python-version` file.
fn read_python_version(contents: &str) -> Option<PythonVersionRequest> {
    // Skip empty lines and comments.
    let ver = contents.lines().find(|line| {
        let trimmed = line.trim();
        !(trimmed.is_empty() || trimmed.starts_with('#'))
    })?;

    // Parse the version.
    let ver = ver.parse().ok()?;

    Some(ver)
}

[zanieb]

Thanks for checking!

I think I'd prefer to support the full syntax of Python requests we support (e.g., it makes sense to allow pinning to [email protected] if that's what your project needs) and just clearly document that other tools may not support those complex requests? We could prioritize pyproject.toml support and only allow the extended syntax there but then people who aren't working in "projects" don't have a way to pin local Python versions consistent with the rest of our interface.