uv_types/

traits.rs

use std::fmt::{Debug, Display, Formatter};
use std::future::Future;
use std::ops::Deref;
use std::path::{Path, PathBuf};

use anyhow::Result;
use rustc_hash::FxHashSet;

use uv_cache::Cache;
use uv_configuration::{BuildKind, BuildOptions, BuildOutput, NoSources};
use uv_distribution_filename::DistFilename;
use uv_distribution_types::{
    CachedDist, ConfigSettings, DependencyMetadata, DistributionId, ExtraBuildRequires,
    ExtraBuildVariables, IndexCapabilities, IndexLocations, InstalledDist, IsBuildBackendError,
    PackageConfigSettings, Requirement, SourceDist,
};
use uv_git::GitResolver;
use uv_normalize::PackageName;
use uv_python_interpreter::{Interpreter, PythonEnvironment};
use uv_static::TarBackend;
use uv_workspace::WorkspaceCache;

use crate::{BuildArena, BuildIsolation, HashStrategy, ResolvedRequirements};

/// Controls how source tree requirements influence workspace-member editability during lowering.
#[derive(Debug, Clone, Copy, Default, Eq, PartialEq)]
pub enum SourceTreeEditablePolicy {
    /// Use project-style semantics when lowering workspace members.
    ///
    /// Explicit source-tree editable settings are ignored, preserving the existing implicit
    /// editable default for workspace members.
    #[default]
    Project,

    /// Use tool-style semantics when lowering workspace members.
    ///
    /// Explicit source-tree editable settings are preserved, while implicit workspace members
    /// default to non-editable.
    Tool,
}

impl SourceTreeEditablePolicy {
    /// Return the default editable mode for workspace members lowered under this policy.
    ///
    /// `explicit` is the explicit editable choice on the source tree being lowered, if any. In
    /// `Tool` mode it propagates to workspace siblings; in `Project` mode it is ignored.
    pub fn workspace_member_editable(self, explicit: Option<bool>) -> bool {
        match self {
            Self::Project => true,
            Self::Tool => explicit.unwrap_or(false),
        }
    }
}

///  Avoids cyclic crate dependencies between resolver, installer and builder.
///
/// To resolve the dependencies of a packages, we may need to build one or more source
/// distributions. To building a source distribution, we need to create a virtual environment from
/// the same base python as we use for the root resolution, resolve the build requirements
/// (potentially which nested source distributions, recursing a level deeper), installing
/// them and then build. The installer, the resolver and the source distribution builder are each in
/// their own crate. To avoid circular crate dependencies, this type dispatches between the three
/// crates with its three main methods ([`BuildContext::resolve`], [`BuildContext::install`] and
/// [`BuildContext::setup_build`]).
///
/// The overall main crate structure looks like this:
///
/// ```text
///                    ┌────────────────┐
///                    │       uv       │
///                    └───────▲────────┘
///                            │
///                            │
///                    ┌───────┴────────┐
///         ┌─────────►│  uv-dispatch   │◄─────────┐
///         │          └───────▲────────┘          │
///         │                  │                   │
///         │                  │                   │
/// ┌───────┴────────┐ ┌───────┴────────┐ ┌────────┴────────────────┐
/// │  uv-resolver   │ │  uv-installer  │ │    uv-build-frontend    │
/// └───────▲────────┘ └───────▲────────┘ └────────▲────────────────┘
///         │                  │                   │
///         └─────────────┐    │    ┌──────────────┘
///                    ┌──┴────┴────┴───┐
///                    │    uv-types    │
///                    └────────────────┘
/// ```
///
/// Put in a different way, the types here allow `uv-resolver` to depend on `uv-build-frontend` and
/// `uv-build-frontend` to depend on `uv-resolver` without having actual crate dependencies between
/// them.
pub trait BuildContext {
    type SourceDistBuilder: SourceBuildTrait;

    /// The tar implementation used for source archives.
    fn tar_backend(&self) -> TarBackend;

    // Note: this function is async deliberately, because downstream code may need to
    // run async code to get the interpreter, to resolve the Python version.
    /// Return a reference to the interpreter.
    fn interpreter(&self) -> impl Future<Output = &Interpreter> + '_;

    /// Return a reference to the cache.
    fn cache(&self) -> &Cache;

    /// Return a reference to the Git resolver.
    fn git(&self) -> &GitResolver;

    /// Return a reference to the build arena.
    fn build_arena(&self) -> &BuildArena<Self::SourceDistBuilder>;

    /// Return a reference to the discovered registry capabilities.
    fn capabilities(&self) -> &IndexCapabilities;

    /// Return a reference to any pre-defined static metadata.
    fn dependency_metadata(&self) -> &DependencyMetadata;

    /// Whether building source distributions or installing pre-built wheels is disabled.
    ///
    /// This method exists to avoid fetching source distributions if we know we can't build them.
    fn build_options(&self) -> &BuildOptions;

    /// The isolation mode used for building source distributions.
    fn build_isolation(&self) -> BuildIsolation<'_>;

    /// The [`ConfigSettings`] used to build distributions.
    fn config_settings(&self) -> &ConfigSettings;

    /// The [`ConfigSettings`] used to build a specific package.
    fn config_settings_package(&self) -> &PackageConfigSettings;

    /// Whether to incorporate `tool.uv.sources` when resolving requirements.
    fn sources(&self) -> &NoSources;

    /// How source tree requirements should influence workspace-member editability.
    fn source_tree_editable_policy(&self) -> SourceTreeEditablePolicy {
        SourceTreeEditablePolicy::Project
    }

    /// The index locations being searched.
    fn locations(&self) -> &IndexLocations;

    /// Workspace discovery caching.
    fn workspace_cache(&self) -> &WorkspaceCache;

    /// Get the extra build requirements.
    fn extra_build_requires(&self) -> &ExtraBuildRequires;

    /// Get the extra build variables.
    fn extra_build_variables(&self) -> &ExtraBuildVariables;

    /// Resolve build requirements.
    ///
    /// Pass `None` for the initial requirements, such as `build-system.requires`. When adding
    /// requirements returned by a build backend, pass the previous resolution's [`HashStrategy`]
    /// to preserve the hashes already collected. When build dependency hashes are required,
    /// backend output cannot add hashes to this set.
    fn resolve<'a>(
        &'a self,
        requirements: &'a [Requirement],
        hash_override: Option<&'a HashStrategy>,
        build_stack: &'a BuildStack,
    ) -> impl Future<Output = Result<ResolvedRequirements, impl IsBuildBackendError>> + 'a;

    /// Install the given set of package versions into the virtual environment. The environment must
    /// use the same base Python as [`BuildContext::interpreter`]
    fn install<'a>(
        &'a self,
        requirements: &'a ResolvedRequirements,
        venv: &'a PythonEnvironment,
        build_stack: &'a BuildStack,
    ) -> impl Future<Output = Result<Vec<CachedDist>, impl IsBuildBackendError>> + 'a;

    /// Set up a source distribution build by installing the required dependencies. A wrapper for
    /// `uv_build_frontend::SourceBuild::setup`.
    ///
    /// For PEP 517 builds, this calls `get_requires_for_build_wheel`.
    ///
    /// Callers are responsible for enforcing [`BuildOptions`] for the source distribution itself.
    /// Build dependencies are still resolved and installed using [`Self::build_options`].
    ///
    /// `version_id` is for error reporting only.
    /// `dist` is for safety checks and may be null for editable builds.
    fn setup_build<'a>(
        &'a self,
        source: &'a Path,
        subdirectory: Option<&'a Path>,
        install_path: &'a Path,
        stop_discovery_at: Option<&'a Path>,
        version_id: Option<&'a str>,
        dist: Option<&'a SourceDist>,
        sources: &'a NoSources,
        build_kind: BuildKind,
        build_output: BuildOutput,
        build_stack: BuildStack,
    ) -> impl Future<Output = Result<Self::SourceDistBuilder, impl IsBuildBackendError>> + 'a;

    /// Build by calling directly into the uv build backend without PEP 517, if possible.
    ///
    /// Checks if the source tree uses uv as build backend. If not, it returns `Ok(None)`, otherwise
    /// it builds and returns the name of the built file.
    ///
    /// `version_id` is for error reporting only.
    fn direct_build<'a>(
        &'a self,
        source: &'a Path,
        subdirectory: Option<&'a Path>,
        output_dir: &'a Path,
        sources: NoSources,
        build_kind: BuildKind,
        version_id: Option<&'a str>,
    ) -> impl Future<Output = Result<Option<DistFilename>, impl IsBuildBackendError>> + 'a;
}

/// A wrapper for `uv_build_frontend::SourceBuild` to avoid cyclical crate dependencies.
///
/// You can call [`Self::wheel`] to build the wheel directly, call [`Self::metadata`] to get
/// the metadata without building the wheel, or call [`Self::metadata`] before [`Self::wheel`].
pub trait SourceBuildTrait {
    /// A wrapper for `uv_build_frontend::SourceBuild::get_metadata_without_build`.
    ///
    /// For PEP 517 builds, this calls `prepare_metadata_for_build_wheel`
    ///
    /// Returns the metadata directory if we're having a PEP 517 build and the
    /// `prepare_metadata_for_build_wheel` hook exists
    fn metadata(&mut self) -> impl Future<Output = Result<Option<PathBuf>, AnyErrorBuild>>;

    /// A wrapper for `uv_build_frontend::SourceBuild::build`.
    ///
    /// For PEP 517 builds, this calls `build_wheel`.
    ///
    /// Returns the filename of the built wheel inside the given `wheel_dir`. The filename is a
    /// string and not a `WheelFilename` because the on disk filename might not be normalized in the
    /// same way as uv would.
    fn wheel<'a>(
        &'a self,
        wheel_dir: &'a Path,
    ) -> impl Future<Output = Result<String, AnyErrorBuild>> + 'a;
}

/// Provides access to installed distributions during resolution.
pub trait InstalledPackagesProvider: Clone + Send + Sync + 'static {
    fn iter(&self) -> impl Iterator<Item = &InstalledDist>;
    fn get_packages(&self, name: &PackageName) -> Vec<&InstalledDist>;
}

impl<Provider: InstalledPackagesProvider> InstalledPackagesProvider for Option<Provider> {
    fn iter(&self) -> impl Iterator<Item = &InstalledDist> {
        self.as_ref().into_iter().flat_map(Provider::iter)
    }

    fn get_packages(&self, name: &PackageName) -> Vec<&InstalledDist> {
        self.as_ref()
            .map_or_else(Vec::new, |provider| provider.get_packages(name))
    }
}

/// An [`InstalledPackagesProvider`] with no packages in it.
#[derive(Clone)]
pub struct EmptyInstalledPackages;

impl InstalledPackagesProvider for EmptyInstalledPackages {
    fn iter(&self) -> impl Iterator<Item = &InstalledDist> {
        std::iter::empty()
    }

    fn get_packages(&self, _name: &PackageName) -> Vec<&InstalledDist> {
        Vec::new()
    }
}

/// An [`anyhow::Error`]-like wrapper for [`SourceBuildTrait`] method return values that supports
/// [`IsBuildBackendError`] as a [`thiserror`] `#[source]`.
///
/// The `uv-resolver`, `uv-installer`, and `uv-build-frontend` crates need to propagate each other's
/// errors without introducing cyclic dependencies.
/// Resolution and installation may need to build packages, while the build frontend needs to
/// resolve and install for the PEP 517 build environment.
///
/// Usually, [`anyhow::Error`] is the opaque error type of choice. Here, the error type must also
/// classify user failures and build backend failures through [`IsBuildBackendError`], and
/// [`anyhow::Error`] does not allow attaching more traits. The next choice would be
/// `Box<dyn IsBuildBackendError>`, but [`thiserror`]
/// complains about the internal `AsDynError` not being implemented when being used as `#[source]`.
/// This struct is an otherwise transparent error wrapper that thiserror recognizes.
pub struct AnyErrorBuild(Box<dyn IsBuildBackendError>);

impl Debug for AnyErrorBuild {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        Debug::fmt(&self.0, f)
    }
}

impl Display for AnyErrorBuild {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        Display::fmt(&self.0, f)
    }
}

impl std::error::Error for AnyErrorBuild {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        self.0.source()
    }

    #[allow(deprecated)]
    fn description(&self) -> &str {
        self.0.description()
    }

    #[allow(deprecated)]
    fn cause(&self) -> Option<&dyn std::error::Error> {
        self.0.cause()
    }
}

impl uv_errors::Hinted for AnyErrorBuild {
    fn hints(&self) -> uv_errors::Hints<'_> {
        self.0.hints()
    }
}

impl<T: IsBuildBackendError> From<T> for AnyErrorBuild {
    fn from(err: T) -> Self {
        Self(Box::new(err))
    }
}

impl Deref for AnyErrorBuild {
    type Target = dyn IsBuildBackendError;

    fn deref(&self) -> &Self::Target {
        &*self.0
    }
}

/// The stack of packages being built.
#[derive(Debug, Clone, Default)]
pub struct BuildStack(FxHashSet<DistributionId>);

impl BuildStack {
    pub fn contains(&self, id: &DistributionId) -> bool {
        self.0.contains(id)
    }

    /// Push a package onto the stack.
    pub fn insert(&mut self, id: DistributionId) -> bool {
        self.0.insert(id)
    }
}