Serialize Python requests for tools as canonicalized strings (#14109)

When working on support for reading global Python pins in tool
operations, I noticed that we weren't using the canonicalized Python
request in receipts — we were using the raw string provided by the user.
Since we'll need to compare these values, we should be using the
canonicalized string.

The `Tool` and `ToolReceipt` types have been updated to hold a
`PythonRequest` instead of a `String`, and `Serialize` was implemented
for `PythonRequest` so canonicalization can happen at the edge instead
of being the caller's responsibility.

crates/uv-python/src/discovery.rs

@@ -67,6 +67,26 @@ pub enum PythonRequest {
     Key(PythonDownloadRequest),
 }
 
+impl<'a> serde::Deserialize<'a> for PythonRequest {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'a>,
+    {
+        let s = String::deserialize(deserializer)?;
+        Ok(PythonRequest::parse(&s))
+    }
+}
+
+impl serde::Serialize for PythonRequest {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        let s = self.to_canonical_string();
+        serializer.serialize_str(&s)
+    }
+}
+
 #[derive(Debug, Default, Clone, Copy, PartialEq, Eq, serde::Deserialize)]
 #[serde(deny_unknown_fields, rename_all = "kebab-case")]
 #[cfg_attr(feature = "clap", derive(clap::ValueEnum))]

crates/uv-tool/src/tool.rs

@@ -7,6 +7,7 @@ use toml_edit::{Array, Item, Table, Value, value};
 use uv_distribution_types::Requirement;
 use uv_fs::{PortablePath, Simplified};
 use uv_pypi_types::VerbatimParsedUrl;
+use uv_python::PythonRequest;
 use uv_settings::ToolOptions;
 
 /// A tool entry.
@@ -22,7 +23,7 @@ pub struct Tool {
     /// The build constraints requested by the user during installation.
     build_constraints: Vec<Requirement>,
     /// The Python requested by the user during installation.
-    python: Option<String>,
+    python: Option<PythonRequest>,
     /// A mapping of entry point names to their metadata.
     entrypoints: Vec<ToolEntrypoint>,
     /// The [`ToolOptions`] used to install this tool.
@@ -40,7 +41,7 @@ struct ToolWire {
     overrides: Vec<Requirement>,
     #[serde(default)]
     build_constraint_dependencies: Vec<Requirement>,
-    python: Option<String>,
+    python: Option<PythonRequest>,
     entrypoints: Vec<ToolEntrypoint>,
     #[serde(default)]
     options: ToolOptions,
@@ -164,7 +165,7 @@ impl Tool {
         constraints: Vec<Requirement>,
         overrides: Vec<Requirement>,
         build_constraints: Vec<Requirement>,
-        python: Option<String>,
+        python: Option<PythonRequest>,
         entrypoints: impl Iterator<Item = ToolEntrypoint>,
         options: ToolOptions,
     ) -> Self {
@@ -280,7 +281,13 @@ impl Tool {
         }
 
         if let Some(ref python) = self.python {
-            table.insert("python", value(python));
+            table.insert(
+                "python",
+                value(serde::Serialize::serialize(
+                    &python,
+                    toml_edit::ser::ValueSerializer::new(),
+                )?),
+            );
         }
 
         table.insert("entrypoints", {
@@ -327,7 +334,7 @@ impl Tool {
         &self.build_constraints
     }
 
-    pub fn python(&self) -> &Option<String> {
+    pub fn python(&self) -> &Option<PythonRequest> {
         &self.python
     }
 

crates/uv/src/commands/tool/common.rs

@@ -158,14 +158,18 @@ pub(crate) async fn refine_interpreter(
     Ok(Some(interpreter))
 }
 
-/// Installs tool executables for a given package and handles any conflicts.
+/// Finalizes a tool installation, after creation of an environment.
-pub(crate) fn install_executables(
+///
+/// Installs tool executables for a given package, handling any conflicts.
+///
+/// Adds a receipt for the tool.
+pub(crate) fn finalize_tool_install(
     environment: &PythonEnvironment,
     name: &PackageName,
     installed_tools: &InstalledTools,
     options: ToolOptions,
     force: bool,
-    python: Option<String>,
+    python: Option<PythonRequest>,
     requirements: Vec<Requirement>,
     constraints: Vec<Requirement>,
     overrides: Vec<Requirement>,

crates/uv/src/commands/tool/install.rs

@@ -33,7 +33,9 @@ use crate::commands::project::{
     EnvironmentSpecification, PlatformState, ProjectError, resolve_environment, resolve_names,
     sync_environment, update_environment,
 };
-use crate::commands::tool::common::{install_executables, refine_interpreter, remove_entrypoints};
+use crate::commands::tool::common::{
+    finalize_tool_install, refine_interpreter, remove_entrypoints,
+};
 use crate::commands::tool::{Target, ToolRequest};
 use crate::commands::{diagnostics, reporters::PythonDownloadReporter};
 use crate::printer::Printer;
@@ -592,13 +594,13 @@ pub(crate) async fn install(
         }
     };
 
-    install_executables(
+    finalize_tool_install(
         &environment,
         &from.name,
         &installed_tools,
         options,
         force || invalid_tool_receipt,
-        python,
+        python_request,
         requirements,
         constraints,
         overrides,

crates/uv/src/commands/tool/upgrade.rs

@@ -29,7 +29,7 @@ use crate::commands::project::{
 };
 use crate::commands::reporters::PythonDownloadReporter;
 use crate::commands::tool::common::remove_entrypoints;
-use crate::commands::{ExitStatus, conjunction, tool::common::install_executables};
+use crate::commands::{ExitStatus, conjunction, tool::common::finalize_tool_install};
 use crate::printer::Printer;
 use crate::settings::{NetworkSettings, ResolverInstallerSettings};
 
@@ -375,7 +375,7 @@ async fn upgrade_tool(
         remove_entrypoints(&existing_tool_receipt);
 
         // If we modified the target tool, reinstall the entrypoints.
-        install_executables(
+        finalize_tool_install(
             &environment,
             name,
             installed_tools,