Add PythonEnvironment::find API (astral-sh#4423)

Restores the `PythonEnvironment::find` API which was removed a while
back in favor of `Toolchain::find`. As mentioned in astral-sh#4416, I'm
attempting to separate the case where you want an active environment
from the case where you want an installed toolchain in order to create
environments.

I wanted to drop `EnvironmentPreference` from `Toolchain::find` and just
have us consistently consider (or not consider) virtual environments
when discovering toolchains for creating environments. Unfortunately
this caused a few things to break so I reverted that change and will
explore it separately. Because I was exploring that change, there are
some minor changes to the `Toolchain` API here.

crates/uv-dev/src/build.rs

@@ -16,7 +16,7 @@ use uv_configuration::{
 use uv_dispatch::BuildDispatch;
 use uv_git::GitResolver;
 use uv_resolver::{FlatIndex, InMemoryIndex};
-use uv_toolchain::{EnvironmentPreference, Toolchain, ToolchainPreference};
+use uv_toolchain::{EnvironmentPreference, PythonEnvironment, ToolchainRequest};
 use uv_types::{BuildContext, BuildIsolation, InFlight};
 
 #[derive(Parser)]
@@ -65,10 +65,9 @@ pub(crate) async fn build(args: BuildArgs) -> Result<PathBuf> {
     let index = InMemoryIndex::default();
     let index_urls = IndexLocations::default();
     let setup_py = SetupPyStrategy::default();
-    let toolchain = Toolchain::find(
-        None,
+    let toolchain = PythonEnvironment::find(
+        &ToolchainRequest::default(),
         EnvironmentPreference::OnlyVirtual,
-        ToolchainPreference::default(),
         &cache,
     )?;
     let build_options = BuildOptions::default();

crates/uv-dev/src/compile.rs

@@ -3,7 +3,7 @@ use std::path::PathBuf;
 use clap::Parser;
 use tracing::info;
 use uv_cache::{Cache, CacheArgs};
-use uv_toolchain::{EnvironmentPreference, Toolchain, ToolchainPreference};
+use uv_toolchain::{EnvironmentPreference, PythonEnvironment, ToolchainRequest};
 
 #[derive(Parser)]
 pub(crate) struct CompileArgs {
@@ -20,10 +20,9 @@ pub(crate) async fn compile(args: CompileArgs) -> anyhow::Result<()> {
     let interpreter = if let Some(python) = args.python {
         python
     } else {
-        let interpreter = Toolchain::find(
-            None,
+        let interpreter = PythonEnvironment::find(
+            &ToolchainRequest::default(),
             EnvironmentPreference::OnlyVirtual,
-            ToolchainPreference::default(),
             &cache,
         )?
         .into_interpreter();

crates/uv-toolchain/src/environment.rs

@@ -6,9 +6,13 @@ use std::sync::Arc;
 use uv_cache::Cache;
 use uv_fs::{LockedFile, Simplified};
 
+use crate::discovery::find_toolchain;
 use crate::toolchain::Toolchain;
 use crate::virtualenv::{virtualenv_python_executable, PyVenvConfiguration};
-use crate::{Error, Interpreter, Prefix, Target};
+use crate::{
+    EnvironmentPreference, Error, Interpreter, Prefix, Target, ToolchainPreference,
+    ToolchainRequest,
+};
 
 /// A Python environment, consisting of a Python [`Interpreter`] and its associated paths.
 #[derive(Debug, Clone)]
@@ -21,6 +25,25 @@ struct PythonEnvironmentShared {
 }
 
 impl PythonEnvironment {
+    /// Find a [`PythonEnvironment`] matching the given request and preference.
+    ///
+    /// If looking for a Python toolchain to create a new environment, use [`Toolchain::find`]
+    /// instead.
+    pub fn find(
+        request: &ToolchainRequest,
+        preference: EnvironmentPreference,
+        cache: &Cache,
+    ) -> Result<Self, Error> {
+        let toolchain = find_toolchain(
+            request,
+            preference,
+            // Ignore managed toolchains when looking for environments
+            ToolchainPreference::OnlySystem,
+            cache,
+        )??;
+        Ok(Self::from_toolchain(toolchain))
+    }
+
     /// Create a [`PythonEnvironment`] from the virtual environment at the given root.
     pub fn from_root(root: impl AsRef<Path>, cache: &Cache) -> Result<Self, Error> {
         let venv = match fs_err::canonicalize(root.as_ref()) {