Use separate struct

crates/uv-interpreter/src/interpreter.rs

@@ -18,8 +18,8 @@ use uv_cache::{Cache, CacheBucket, CachedByTimestamp, Freshness, Timestamp};
 use uv_fs::{write_atomic_sync, PythonExt, Simplified};
 use uv_toolchain::PythonVersion;
 
-use crate::Error;
 use crate::Virtualenv;
+use crate::{Error, Target};
 
 /// A Python executable and its associated platform markers.
 #[derive(Debug, Clone)]
@@ -35,7 +35,7 @@ pub struct Interpreter {
     sys_executable: PathBuf,
     stdlib: PathBuf,
     tags: OnceCell<Tags>,
-    target: Option<PathBuf>,
+    target: Option<Target>,
     gil_disabled: bool,
 }
 
@@ -112,16 +112,12 @@ impl Interpreter {
     /// Return a new [`Interpreter`] to install into the given `--target` directory.
     ///
     /// Initializes the `--target` directory with the expected layout.
-    pub fn with_target(self, target: PathBuf) -> Result<Self, Error> {
-        // Create the `--target` directory layout.
-        fs_err::create_dir_all(&target)?;
-        fs_err::create_dir_all(target.join("bin"))?;
-        fs_err::create_dir_all(target.join("include"))?;
-
-        Ok(Self {
+    #[must_use]
+    pub fn with_target(self, target: Target) -> Self {
+        Self {
             target: Some(target),
             ..self
-        })
+        }
     }
 
     /// Returns the path to the Python virtual environment.
@@ -333,8 +329,8 @@ impl Interpreter {
     }
 
     /// Return the `--target` directory for this interpreter, if any.
-    pub fn target(&self) -> Option<&Path> {
-        self.target.as_deref()
+    pub fn target(&self) -> Option<&Target> {
+        self.target.as_ref()
     }
 
     /// Return the [`Layout`] environment used to install wheels into this interpreter.
@@ -343,14 +339,8 @@ impl Interpreter {
             python_version: self.python_tuple(),
             sys_executable: self.sys_executable().to_path_buf(),
             os_name: self.markers.os_name.clone(),
-            scheme: if let Some(target) = self.target.as_deref() {
-                Scheme {
-                    purelib: target.to_path_buf(),
-                    platlib: target.to_path_buf(),
-                    scripts: target.join("bin"),
-                    data: target.to_path_buf(),
-                    include: target.join("include"),
-                }
+            scheme: if let Some(target) = self.target.as_ref() {
+                target.scheme()
             } else {
                 Scheme {
                     purelib: self.purelib().to_path_buf(),

crates/uv-interpreter/src/lib.rs

@@ -19,12 +19,14 @@ pub use crate::find_python::{find_best_python, find_default_python, find_request
 pub use crate::interpreter::Interpreter;
 use crate::interpreter::InterpreterInfoError;
 pub use crate::python_environment::PythonEnvironment;
+pub use crate::target::Target;
 pub use crate::virtualenv::Virtualenv;
 
 mod cfg;
 mod find_python;
 mod interpreter;
 mod python_environment;
+mod target;
 mod virtualenv;
 
 #[derive(Debug, Error)]

crates/uv-interpreter/src/python_environment.rs

@@ -9,7 +9,7 @@ use uv_cache::Cache;
 use uv_fs::{LockedFile, Simplified};
 
 use crate::cfg::PyVenvConfiguration;
-use crate::{find_default_python, find_requested_python, Error, Interpreter};
+use crate::{find_default_python, find_requested_python, Error, Interpreter, Target};
 
 /// A Python environment, consisting of a Python [`Interpreter`] and its associated paths.
 #[derive(Debug, Clone)]
@@ -70,11 +70,12 @@ impl PythonEnvironment {
     }
 
     /// Create a [`PythonEnvironment`] from an existing [`Interpreter`] and `--target` directory.
-    pub fn with_target(self, target: PathBuf) -> Result<Self, Error> {
-        Ok(Self {
-            interpreter: self.interpreter.with_target(target)?,
+    #[must_use]
+    pub fn with_target(self, target: Target) -> Self {
+        Self {
+            interpreter: self.interpreter.with_target(target),
             ..self
-        })
+        }
     }
 
     /// Returns the root (i.e., `prefix`) of the Python interpreter.
@@ -107,7 +108,7 @@ impl PythonEnvironment {
     /// still deduplicate the entries, returning a single path.
     pub fn site_packages(&self) -> impl Iterator<Item = &Path> {
         if let Some(target) = self.interpreter.target() {
-            Either::Left(std::iter::once(target))
+            Either::Left(std::iter::once(target.root()))
         } else {
             let purelib = self.interpreter.purelib();
             let platlib = self.interpreter.platlib();
@@ -130,7 +131,10 @@ impl PythonEnvironment {
     pub fn lock(&self) -> Result<LockedFile, std::io::Error> {
         if let Some(target) = self.interpreter.target() {
             // If we're installing into a `--target`, use a target-specific lock file.
-            LockedFile::acquire(target.join(".lock"), target.simplified_display())
+            LockedFile::acquire(
+                target.root().join(".lock"),
+                target.root().simplified_display(),
+            )
         } else if self.interpreter.is_virtualenv() {
             // If the environment a virtualenv, use a virtualenv-specific lock file.
             LockedFile::acquire(self.root.join(".lock"), self.root.simplified_display())

crates/uv-interpreter/src/target.rs

@@ -0,0 +1,40 @@
+use std::path::{Path, PathBuf};
+
+use pypi_types::Scheme;
+
+/// A `--target` directory into which packages can be installed, separate from a virtual environment
+/// or system Python interpreter.
+#[derive(Debug, Clone)]
+pub struct Target(PathBuf);
+
+impl Target {
+    /// Return the [`Scheme`] for the `--target` directory.
+    pub fn scheme(&self) -> Scheme {
+        Scheme {
+            purelib: self.0.clone(),
+            platlib: self.0.clone(),
+            scripts: self.0.join("bin"),
+            data: self.0.clone(),
+            include: self.0.join("include"),
+        }
+    }
+
+    /// Initialize the `--target` directory.
+    pub fn init(&self) -> std::io::Result<()> {
+        fs_err::create_dir_all(&self.0)?;
+        fs_err::create_dir_all(self.0.join("bin"))?;
+        fs_err::create_dir_all(self.0.join("include"))?;
+        Ok(())
+    }
+
+    /// Return the path to the `--target` directory.
+    pub fn root(&self) -> &Path {
+        &self.0
+    }
+}
+
+impl From<PathBuf> for Target {
+    fn from(path: PathBuf) -> Self {
+        Self(path)
+    }
+}

crates/uv/src/commands/pip_install.rs

@@ -1,11 +1,9 @@
 use std::borrow::Cow;
 use std::fmt::Write;
-
-use std::path::{Path, PathBuf};
+use std::path::Path;
 
 use anstream::eprint;
 use anyhow::{anyhow, Context, Result};
-
 use itertools::Itertools;
 use owo_colors::OwoColorize;
 use tempfile::tempdir_in;
@@ -33,7 +31,7 @@ use uv_configuration::{KeyringProviderType, TargetTriple};
 use uv_dispatch::BuildDispatch;
 use uv_fs::Simplified;
 use uv_installer::{BuiltEditable, Downloader, Plan, Planner, ResolvedEditable, SitePackages};
-use uv_interpreter::{Interpreter, PythonEnvironment};
+use uv_interpreter::{Interpreter, PythonEnvironment, Target};
 use uv_normalize::PackageName;
 use uv_requirements::{
     ExtrasSpecification, LookaheadResolver, NamedRequirementsResolver, RequirementsSource,
@@ -84,7 +82,7 @@ pub(crate) async fn pip_install(
     python: Option<String>,
     system: bool,
     break_system_packages: bool,
-    target: Option<PathBuf>,
+    target: Option<Target>,
     native_tls: bool,
     cache: Cache,
     dry_run: bool,
@@ -137,7 +135,8 @@ pub(crate) async fn pip_install(
 
     // Apply any `--target` directory.
     let venv = if let Some(target) = target {
-        venv.with_target(target)?
+        target.init()?;
+        venv.with_target(target)
     } else {
         venv
     };

crates/uv/src/commands/pip_sync.rs

@@ -1,6 +1,5 @@
 use std::borrow::Cow;
 use std::fmt::Write;
-use std::path::PathBuf;
 
 use anstream::eprint;
 use anyhow::{anyhow, Context, Result};
@@ -27,7 +26,7 @@ use uv_configuration::{KeyringProviderType, TargetTriple};
 use uv_dispatch::BuildDispatch;
 use uv_fs::Simplified;
 use uv_installer::{is_dynamic, Downloader, Plan, Planner, ResolvedEditable, SitePackages};
-use uv_interpreter::{Interpreter, PythonEnvironment};
+use uv_interpreter::{Interpreter, PythonEnvironment, Target};
 use uv_requirements::{
     ExtrasSpecification, NamedRequirementsResolver, RequirementsSource, RequirementsSpecification,
     SourceTreeResolver,
@@ -64,7 +63,7 @@ pub(crate) async fn pip_sync(
     python: Option<String>,
     system: bool,
     break_system_packages: bool,
-    target: Option<PathBuf>,
+    target: Option<Target>,
     native_tls: bool,
     cache: Cache,
     printer: Printer,
@@ -116,7 +115,8 @@ pub(crate) async fn pip_sync(
 
     // Apply any `--target` directory.
     let venv = if let Some(target) = target {
-        venv.with_target(target)?
+        target.init()?;
+        venv.with_target(target)
     } else {
         venv
     };

crates/uv/src/commands/pip_uninstall.rs

@@ -1,5 +1,4 @@
 use std::fmt::Write;
-use std::path::PathBuf;
 
 use anyhow::Result;
 use itertools::{Either, Itertools};
@@ -13,11 +12,11 @@ use uv_cache::Cache;
 use uv_client::{BaseClientBuilder, Connectivity};
 use uv_configuration::KeyringProviderType;
 use uv_fs::Simplified;
-use uv_interpreter::PythonEnvironment;
+use uv_interpreter::{PythonEnvironment, Target};
+use uv_requirements::{RequirementsSource, RequirementsSpecification};
 
 use crate::commands::{elapsed, ExitStatus};
 use crate::printer::Printer;
-use uv_requirements::{RequirementsSource, RequirementsSpecification};
 
 /// Uninstall packages from the current environment.
 #[allow(clippy::too_many_arguments)]
@@ -26,7 +25,7 @@ pub(crate) async fn pip_uninstall(
     python: Option<String>,
     system: bool,
     break_system_packages: bool,
-    target: Option<PathBuf>,
+    target: Option<Target>,
     cache: Cache,
     connectivity: Connectivity,
     native_tls: bool,
@@ -58,7 +57,8 @@ pub(crate) async fn pip_uninstall(
 
     // Apply any `--target` directory.
     let venv = if let Some(target) = target {
-        venv.with_target(target)?
+        target.init()?;
+        venv.with_target(target)
     } else {
         venv
     };

crates/uv/src/settings.rs

@@ -9,6 +9,7 @@ use uv_configuration::{
     ConfigSettings, IndexStrategy, KeyringProviderType, NoBinary, NoBuild, PreviewMode, Reinstall,
     SetupPyStrategy, TargetTriple, Upgrade,
 };
+use uv_interpreter::Target;
 use uv_normalize::PackageName;
 use uv_requirements::ExtrasSpecification;
 use uv_resolver::{AnnotationStyle, DependencyMode, ExcludeNewer, PreReleaseMode, ResolutionMode};
@@ -807,7 +808,7 @@ pub(crate) struct PipSharedSettings {
     pub(crate) system: bool,
     pub(crate) extras: ExtrasSpecification,
     pub(crate) break_system_packages: bool,
-    pub(crate) target: Option<PathBuf>,
+    pub(crate) target: Option<Target>,
     pub(crate) connectivity: Connectivity,
     pub(crate) index_strategy: IndexStrategy,
     pub(crate) keyring_provider: KeyringProviderType,
@@ -963,7 +964,7 @@ impl PipSharedSettings {
                 .break_system_packages
                 .or(break_system_packages)
                 .unwrap_or_default(),
-            target: args.target.or(target),
+            target: args.target.or(target).map(Target::from),
             no_binary: NoBinary::from_args(args.no_binary.or(no_binary).unwrap_or_default()),
             compile_bytecode: args
                 .compile_bytecode

crates/uv/tests/pip_sync.rs

@@ -4820,9 +4820,9 @@ fn require_hashes_registry_invalid_hash() -> Result<()> {
 fn target() -> Result<()> {
     let context = TestContext::new("3.12");
 
-    // Install `anyio` to the target directory.
+    // Install `iniconfig` to the target directory.
     let requirements_in = context.temp_dir.child("requirements.in");
-    requirements_in.write_str("anyio==4.1.0")?;
+    requirements_in.write_str("iniconfig==2.0.0")?;
 
     uv_snapshot!(command(&context)
         .arg("requirements.in")
@@ -4836,12 +4836,28 @@ fn target() -> Result<()> {
     Resolved 1 package in [TIME]
     Downloaded 1 package in [TIME]
     Installed 1 package in [TIME]
-     + anyio==4.1.0
+     + iniconfig==2.0.0
     "###);
 
+    // Ensure that the package is present in the target directory.
+    assert!(context.temp_dir.child("target").child("iniconfig").is_dir());
+
+    // Ensure that we can't import the package.
+    context.assert_command("import iniconfig").failure();
+
+    // Ensure that we can import the package by augmenting the `PYTHONPATH`.
+    Command::new(venv_to_interpreter(&context.venv))
+        .arg("-B")
+        .arg("-c")
+        .arg("import iniconfig")
+        .env("PYTHONPATH", context.temp_dir.child("target").path())
+        .current_dir(&context.temp_dir)
+        .assert()
+        .success();
+
     // Upgrade it.
     let requirements_in = context.temp_dir.child("requirements.in");
-    requirements_in.write_str("anyio==4.2.0")?;
+    requirements_in.write_str("iniconfig==1.1.1")?;
 
     uv_snapshot!(command(&context)
         .arg("requirements.in")
@@ -4856,8 +4872,8 @@ fn target() -> Result<()> {
     Downloaded 1 package in [TIME]
     Uninstalled 1 package in [TIME]
     Installed 1 package in [TIME]
-     - anyio==4.1.0
-     + anyio==4.2.0
+     - iniconfig==2.0.0
+     + iniconfig==1.1.1
     "###);
 
     // Remove it, and replace with `flask`, which includes a binary.
@@ -4877,9 +4893,17 @@ fn target() -> Result<()> {
     Downloaded 1 package in [TIME]
     Uninstalled 1 package in [TIME]
     Installed 1 package in [TIME]
-     - anyio==4.2.0
      + flask==3.0.3
+     - iniconfig==1.1.1
     "###);
 
+    // Ensure that the binary is present in the target directory.
+    assert!(context
+        .temp_dir
+        .child("target")
+        .child("bin")
+        .child("flask")
+        .is_file());
+
     Ok(())
 }