Add internal options for managing toolchain discovery preferences (#4416)

Adds support for the toolchain discovery preferences outlined in
https://github.com/astral-sh/uv/issues/4198 but we don't expose this to
users yet, I'll do that next to make it easier to review.

I've made some refactors in the toolchain discovery implementation to
enable this behavior and move us towards clearer abstractions. There's
still remaining work here, but I'd prefer tackle things in follow-ups
instead of expanding this pull request. I plan on opening a couple
before merging this.

I'd like to shift the public toolchain API to focus on discovering
either an **environment** or a **toolchain**. The first would be used by
commands that operate on an environment, while the latter would be used
by commands that just need an interpreter to create environments. I
haven't changed this here, but some of the refactors are in preparation
for supporting this idea.

In brief:

- We now allow different ordering of installed toolchain discovery based
on a `ToolchainPreference` type. This is the type we will expose to
users.
- `SystemPython` was changed into an `EnvironmentPreference` which is
used to determine if we should prefer virtual or system Python
environments.
- We drop the whole `ToolchainSources` selection concept, it was
confusing and the error messages from it were awkward. Most of the
functionality is now captured by the preference enums, but you can't do
things like "only find a toolchain from the parent interpreter" as
easily anymore.

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::Toolchain;
+use uv_toolchain::{EnvironmentPreference, Toolchain, ToolchainPreference};
 use uv_types::{BuildContext, BuildIsolation, InFlight};
 
 #[derive(Parser)]
@@ -65,7 +65,12 @@ 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_virtualenv(&cache)?;
+    let toolchain = Toolchain::find(
+        None,
+        EnvironmentPreference::OnlyVirtual,
+        ToolchainPreference::default(),
+        &cache,
+    )?;
     let build_options = BuildOptions::default();
 
     let build_dispatch = BuildDispatch::new(

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::Toolchain;
+use uv_toolchain::{EnvironmentPreference, Toolchain, ToolchainPreference};
 
 #[derive(Parser)]
 pub(crate) struct CompileArgs {
@@ -20,7 +20,13 @@ pub(crate) async fn compile(args: CompileArgs) -> anyhow::Result<()> {
     let interpreter = if let Some(python) = args.python {
         python
     } else {
-        let interpreter = Toolchain::find_virtualenv(&cache)?.into_interpreter();
+        let interpreter = Toolchain::find(
+            None,
+            EnvironmentPreference::OnlyVirtual,
+            ToolchainPreference::default(),
+            &cache,
+        )?
+        .into_interpreter();
         interpreter.sys_executable().to_path_buf()
     };