Reduce uv-toolchain discovery API to Toolchain (#4148)

Drops `find_toolchain`, `find_best_toolchain`, etc. in favor of
`Toolchain::find_...`

We can change this in the future, but there should only be one "right"
way to do it not two redundant ways in the public interface.

crates/uv-toolchain/src/discovery.rs

@@ -445,7 +445,7 @@ fn should_stop_discovery(err: &Error) -> bool {
 ///
 /// If an error is encountered while locating or inspecting a candidate toolchain,
 /// the error will raised instead of attempting further candidates.
-pub fn find_toolchain(
+pub(crate) fn find_toolchain(
     request: &ToolchainRequest,
     system: SystemPython,
     sources: &ToolchainSources,
@@ -627,7 +627,7 @@ pub fn find_toolchain(
 /// Virtual environments are not included in discovery.
 ///
 /// See [`find_toolchain`] for more details on toolchain discovery.
-pub fn find_default_toolchain(
+pub(crate) fn find_default_toolchain(
     preview: PreviewMode,
     cache: &Cache,
 ) -> Result<ToolchainResult, Error> {

crates/uv-toolchain/src/lib.rs

@@ -2,9 +2,8 @@
 use thiserror::Error;
 
 pub use crate::discovery::{
-    find_best_toolchain, find_default_toolchain, find_toolchain, Error as DiscoveryError,
-    SystemPython, ToolchainNotFound, ToolchainRequest, ToolchainSource, ToolchainSources,
-    VersionRequest,
+    Error as DiscoveryError, SystemPython, ToolchainNotFound, ToolchainRequest, ToolchainSource,
+    ToolchainSources, VersionRequest,
 };
 pub use crate::environment::PythonEnvironment;
 pub use crate::interpreter::Interpreter;
@@ -81,9 +80,9 @@ mod tests {
     use uv_cache::Cache;
     use uv_configuration::PreviewMode;
 
+    use crate::discovery::{find_default_toolchain, find_toolchain};
     use crate::{
-        find_default_toolchain, find_toolchain, implementation::ImplementationName,
-        managed::InstalledToolchains, toolchain::Toolchain,
+        implementation::ImplementationName, managed::InstalledToolchains, toolchain::Toolchain,
         virtualenv::virtualenv_python_executable, Error, PythonVersion, SystemPython,
         ToolchainNotFound, ToolchainRequest, ToolchainSource, ToolchainSources, VersionRequest,
     };

crates/uv-toolchain/src/toolchain.rs

@@ -2,11 +2,11 @@ use uv_configuration::PreviewMode;
 
 use uv_cache::Cache;
 
-use crate::discovery::{SystemPython, ToolchainRequest, ToolchainSources};
-use crate::{
-    find_best_toolchain, find_default_toolchain, find_toolchain, Error, Interpreter,
-    ToolchainSource,
+use crate::discovery::{
+    find_best_toolchain, find_default_toolchain, find_toolchain, SystemPython, ToolchainRequest,
+    ToolchainSources,
 };
+use crate::{Error, Interpreter, ToolchainSource};
 
 /// A Python interpreter and accompanying tools.
 #[derive(Clone, Debug)]

crates/uv/tests/common/mod.rs

@@ -18,9 +18,7 @@ use uv_configuration::PreviewMode;
 use uv_cache::Cache;
 use uv_fs::Simplified;
 use uv_toolchain::managed::InstalledToolchains;
-use uv_toolchain::{
-    find_toolchain, PythonVersion, ToolchainRequest, ToolchainSources, VersionRequest,
-};
+use uv_toolchain::{PythonVersion, Toolchain};
 
 // Exclude any packages uploaded after this date.
 pub static EXCLUDE_NEWER: &str = "2024-03-25T00:00:00Z";
@@ -476,22 +474,15 @@ pub fn python_path_with_versions(
                 .unwrap_or_default();
             if inner.is_empty() {
                 // Fallback to a system lookup if we failed to find one in the toolchain directory
-                let request = ToolchainRequest::Version(
-                    VersionRequest::from_str(python_version)
-                        .expect("The test version request must be valid"),
-                );
-                let sources = ToolchainSources::All(PreviewMode::Enabled);
-                if let Ok(found) = find_toolchain(
-                    &request,
+                if let Ok(toolchain) = Toolchain::find(
+                    Some(python_version),
                     // Without required, we could pick the current venv here and the test fails
                     // because the venv subcommand requires a system interpreter.
                     uv_toolchain::SystemPython::Required,
-                    &sources,
+                    PreviewMode::Enabled,
                     &cache,
-                )
-                .unwrap()
-                {
-                    vec![found
+                ) {
+                    vec![toolchain
                         .into_interpreter()
                         .sys_executable()
                         .parent()