uv_settings/

settings.rs

#[cfg(feature = "schemars")]
use std::borrow::Cow;
use std::{
    fmt::{self, Debug},
    num::NonZeroUsize,
    path::Path,
    path::PathBuf,
};

use serde::de::{Error, SeqAccess, Visitor, value::SeqAccessDeserializer};
use serde::{Deserialize, Deserializer, Serialize};

use uv_cache_info::CacheKey;
use uv_configuration::{
    AddBoundsKind, AnnotationStyle, BuildIsolation, ExcludeDependency, ExcludeNewerPackage,
    ForkStrategy, IndexStrategy, KeyringProviderType, PackageNameSpecifier, PrereleaseMode,
    PrereleasePackage, ProxyUrl, Reinstall, RequiredVersion, ResolutionMode, TargetTriple,
    TrustedHost, TrustedPublishing, Upgrade, serialize_exclude_newer_package_with_spans,
};
use uv_distribution_types::{
    ConfigSettings, ExcludeNewerOverride, ExcludeNewerSpan, ExcludeNewerValue, ExtraBuildVariables,
    Index, IndexLocations, IndexUrl, IndexUrlError, MinimumLibcVersion, Origin,
    PackageConfigSettings, PipExtraIndex, PipFindLinks, PipIndex, StaticMetadata,
};
use uv_install_wheel::LinkMode;
use uv_macros::{CombineOptions, OptionsMetadata};
use uv_normalize::{ExtraName, PackageName, PipGroupName};
use uv_pep508::Requirement;
use uv_preview::{MaybePreviewFeature, Preview};
use uv_pypi_types::{SupportedEnvironments, VerbatimParsedUrl};
use uv_python_types::{PythonDownloadMirrors, PythonDownloads, PythonPreference, PythonVersion};
use uv_redacted::DisplaySafeUrl;
use uv_torch::TorchMode;
use uv_workspace::pyproject::{
    BuildConstraintDependency, ExtraBuildDependencies, OverrideDependency,
};

use crate::{EnvironmentOptions, FilesystemOptions};

/// A `pyproject.toml` with an (optional) `[tool.uv]` section.
#[allow(dead_code)]
#[derive(Debug, Clone, Default, Deserialize)]
pub(crate) struct PyProjectToml {
    pub(crate) tool: Option<Tools>,
}

/// A `[tool]` section.
#[allow(dead_code)]
#[derive(Debug, Clone, Default, Deserialize)]
pub(crate) struct Tools {
    pub(crate) uv: Option<Options>,
}

/// A `pyproject.toml` with an (optional) `[tool.uv.required-version]`.
#[derive(Debug, Clone, Default, Deserialize)]
pub(crate) struct PyProjectRequiredVersionToml {
    pub(crate) tool: Option<RequiredVersionTools>,
}

/// A `[tool]` section containing only the fields required for `required-version` discovery.
#[derive(Debug, Clone, Default, Deserialize)]
pub(crate) struct RequiredVersionTools {
    pub(crate) uv: Option<RequiredVersionOptions>,
}

/// The minimal `[tool.uv]` subset required to enforce `required-version` before full parsing.
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub(crate) struct RequiredVersionOptions {
    pub(crate) required_version: Option<RequiredVersion>,
}

/// A `uv.toml` containing only the fields required for `required-version` discovery.
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub(crate) struct UvRequiredVersionToml {
    pub(crate) required_version: Option<RequiredVersion>,
}

/// A `[tool.uv]` section.
#[allow(dead_code)]
#[derive(Debug, Clone, Default, Deserialize, CombineOptions, OptionsMetadata)]
#[serde(try_from = "OptionsWire", rename_all = "kebab-case")]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(!try_from))]
pub struct Options {
    #[serde(flatten)]
    pub globals: GlobalOptions,

    #[serde(flatten)]
    pub top_level: ResolverInstallerSchema,

    #[serde(flatten)]
    pub install_mirrors: PythonInstallMirrors,

    #[serde(flatten)]
    pub publish: PublishOptions,

    #[serde(flatten)]
    pub add: AddOptions,

    #[option_group]
    pub audit: Option<AuditOptions>,

    #[option_group]
    pub pip: Option<PipOptions>,

    /// The keys to consider when caching builds for the project.
    ///
    /// Cache keys enable you to specify the files or directories that should trigger a rebuild when
    /// modified. By default, uv will rebuild a project whenever the `pyproject.toml`, `setup.py`,
    /// or `setup.cfg` files in the project directory are modified, or if a `src` directory is
    /// added or removed, i.e.:
    ///
    /// ```toml
    /// cache-keys = [{ file = "pyproject.toml" }, { file = "setup.py" }, { file = "setup.cfg" }, { dir = "src" }]
    /// ```
    ///
    /// As an example: if a project uses dynamic metadata to read its dependencies from a
    /// `requirements.txt` file, you can specify `cache-keys = [{ file = "requirements.txt" }, { file = "pyproject.toml" }]`
    /// to ensure that the project is rebuilt whenever the `requirements.txt` file is modified (in
    /// addition to watching the `pyproject.toml`).
    ///
    /// Globs are supported, following the syntax of the [`glob`](https://docs.rs/glob/0.3.1/glob/struct.Pattern.html)
    /// crate. For example, to invalidate the cache whenever a `.toml` file in the project directory
    /// or any of its subdirectories is modified, you can specify `cache-keys = [{ file = "**/*.toml" }]`.
    /// Note that the use of globs can be expensive, as uv may need to walk the filesystem to
    /// determine whether any files have changed.
    ///
    /// Cache keys can also include version control information. For example, if a project uses
    /// `setuptools_scm` to read its version from a Git commit, you can specify `cache-keys = [{ git = { commit = true }, { file = "pyproject.toml" }]`
    /// to include the current Git commit hash in the cache key (in addition to the
    /// `pyproject.toml`). Git tags are also supported via `cache-keys = [{ git = { commit = true, tags = true } }]`.
    ///
    /// Cache keys can also include environment variables. For example, if a project relies on
    /// `MACOSX_DEPLOYMENT_TARGET` or other environment variables to determine its behavior, you can
    /// specify `cache-keys = [{ env = "MACOSX_DEPLOYMENT_TARGET" }]` to invalidate the cache
    /// whenever the environment variable changes.
    ///
    /// Cache keys only affect the project defined by the `pyproject.toml` in which they're
    /// specified (as opposed to, e.g., affecting all members in a workspace), and all paths and
    /// globs are interpreted as relative to the project directory.
    #[option(
        default = r#"[{ file = "pyproject.toml" }, { file = "setup.py" }, { file = "setup.cfg" }]"#,
        value_type = "list[dict]",
        example = r#"
            cache-keys = [{ file = "pyproject.toml" }, { file = "requirements.txt" }, { git = { commit = true } }]
        "#
    )]
    pub cache_keys: Option<Vec<CacheKey>>,

    // NOTE(charlie): These fields are shared with `ToolUv` in
    // `crates/uv-workspace/src/pyproject.rs`. The documentation lives on that struct.
    // They're respected in both `pyproject.toml` and `uv.toml` files.
    #[cfg_attr(feature = "schemars", schemars(skip))]
    pub override_dependencies: Option<Vec<OverrideDependency>>,

    #[cfg_attr(feature = "schemars", schemars(skip))]
    pub exclude_dependencies: Option<Vec<ExcludeDependency>>,

    #[cfg_attr(feature = "schemars", schemars(skip))]
    pub constraint_dependencies: Option<Vec<Requirement<VerbatimParsedUrl>>>,

    #[cfg_attr(feature = "schemars", schemars(skip))]
    pub build_constraint_dependencies: Option<Vec<BuildConstraintDependency>>,

    #[cfg_attr(feature = "schemars", schemars(skip))]
    pub environments: Option<SupportedEnvironments>,

    #[cfg_attr(feature = "schemars", schemars(skip))]
    pub required_environments: Option<SupportedEnvironments>,

    #[cfg_attr(feature = "schemars", schemars(skip))]
    pub minimum_libc_version: Option<MinimumLibcVersion>,

    // NOTE(charlie): These fields should be kept in-sync with `ToolUv` in
    // `crates/uv-workspace/src/pyproject.rs`. The documentation lives on that struct.
    // They're only respected in `pyproject.toml` files, and should be rejected in `uv.toml` files.
    #[cfg_attr(feature = "schemars", schemars(skip))]
    pub(crate) conflicts: Option<serde::de::IgnoredAny>,

    #[cfg_attr(feature = "schemars", schemars(skip))]
    pub(crate) workspace: Option<serde::de::IgnoredAny>,

    #[cfg_attr(feature = "schemars", schemars(skip))]
    pub(crate) sources: Option<serde::de::IgnoredAny>,

    #[cfg_attr(feature = "schemars", schemars(skip))]
    pub(crate) dev_dependencies: Option<serde::de::IgnoredAny>,

    #[cfg_attr(feature = "schemars", schemars(skip))]
    pub(crate) default_groups: Option<serde::de::IgnoredAny>,

    #[cfg_attr(feature = "schemars", schemars(skip))]
    pub(crate) dependency_groups: Option<serde::de::IgnoredAny>,

    #[cfg_attr(feature = "schemars", schemars(skip))]
    pub(crate) managed: Option<serde::de::IgnoredAny>,

    #[cfg_attr(feature = "schemars", schemars(skip))]
    pub(crate) r#package: Option<serde::de::IgnoredAny>,

    #[cfg_attr(feature = "schemars", schemars(skip))]
    pub(crate) build_backend: Option<serde::de::IgnoredAny>,
}

impl Options {
    /// Construct an [`Options`] with the given global and top-level settings.
    pub fn simple(globals: GlobalOptions, top_level: ResolverInstallerSchema) -> Self {
        Self {
            globals,
            top_level,
            ..Default::default()
        }
    }

    /// Set the [`Origin`] on all indexes without an existing origin.
    #[must_use]
    pub(crate) fn with_origin(mut self, origin: Origin) -> Self {
        if let Some(indexes) = &mut self.top_level.index {
            for index in indexes {
                index.origin.get_or_insert(origin);
            }
        }
        if let Some(index_url) = &mut self.top_level.index_url {
            index_url.try_set_origin(origin);
        }
        if let Some(extra_index_urls) = &mut self.top_level.extra_index_url {
            for index_url in extra_index_urls {
                index_url.try_set_origin(origin);
            }
        }
        if let Some(pip) = &mut self.pip {
            if let Some(indexes) = &mut pip.index {
                for index in indexes {
                    index.origin.get_or_insert(origin);
                }
            }
            if let Some(index_url) = &mut pip.index_url {
                index_url.try_set_origin(origin);
            }
            if let Some(extra_index_urls) = &mut pip.extra_index_url {
                for index_url in extra_index_urls {
                    index_url.try_set_origin(origin);
                }
            }
        }
        self
    }

    /// Resolve the [`Options`] relative to the given root directory.
    pub(crate) fn relative_to(self, root_dir: &Path) -> Result<Self, IndexUrlError> {
        Ok(Self {
            top_level: self.top_level.relative_to(root_dir)?,
            pip: self.pip.map(|pip| pip.relative_to(root_dir)).transpose()?,
            ..self
        })
    }
}

/// Global settings, relevant to all invocations.
#[derive(Debug, Clone, Default, Deserialize, CombineOptions, OptionsMetadata)]
#[serde(try_from = "GlobalOptionsWire", rename_all = "kebab-case")]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(!try_from))]
pub struct GlobalOptions {
    /// Enforce a requirement on the version of uv.
    ///
    /// If the version of uv does not meet the requirement at runtime, uv will exit
    /// with an error.
    ///
    /// Accepts a [PEP 440](https://peps.python.org/pep-0440/) specifier, like `==0.5.0` or `>=0.5.0`.
    #[option(
        default = "null",
        value_type = "str",
        example = r#"
            required-version = ">=0.5.0"
        "#
    )]
    pub required_version: Option<RequiredVersion>,
    /// Whether to load TLS certificates from the platform's native certificate store.
    ///
    /// By default, uv uses bundled Mozilla root certificates. When enabled, this loads
    /// certificates from the platform's native certificate store instead.
    #[option(
        default = "false",
        value_type = "bool",
        uv_toml_only = true,
        example = r#"
            system-certs = true
        "#
    )]
    pub system_certs: Option<bool>,
    /// Whether to load TLS certificates from the platform's native certificate store.
    ///
    /// By default, uv uses bundled Mozilla root certificates. When enabled, this loads
    /// certificates from the platform's native certificate store instead.
    ///
    /// (Deprecated: use `system-certs` instead.)
    #[deprecated(note = "use `system-certs` instead")]
    #[option(
        default = "false",
        value_type = "bool",
        uv_toml_only = true,
        example = r#"
            native-tls = true
        "#
    )]
    pub native_tls: Option<bool>,
    /// Disable network access, relying only on locally cached data and locally available files.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            offline = true
        "#
    )]
    pub offline: Option<bool>,
    /// Avoid reading from or writing to the cache, instead using a temporary directory for the
    /// duration of the operation.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            no-cache = true
        "#
    )]
    pub no_cache: Option<bool>,
    /// Path to the cache directory.
    ///
    /// Defaults to `$XDG_CACHE_HOME/uv` or `$HOME/.cache/uv` on Linux and macOS, and
    /// `%LOCALAPPDATA%\uv\cache` on Windows.
    #[option(
        default = "None",
        value_type = "str",
        uv_toml_only = true,
        example = r#"
            cache-dir = "./.uv_cache"
        "#
    )]
    pub cache_dir: Option<PathBuf>,

    /// The user's preview configuration.
    #[serde(flatten)]
    pub preview: Option<PreviewOption>,

    /// Whether to prefer using Python installations that are already present on the system, or
    /// those that are downloaded and installed by uv.
    #[option(
        default = "\"managed\"",
        value_type = "str",
        example = r#"
            python-preference = "managed"
        "#,
        possible_values = true
    )]
    pub python_preference: Option<PythonPreference>,
    /// Whether to allow Python downloads.
    #[option(
        default = "\"automatic\"",
        value_type = "str",
        example = r#"
            python-downloads = "manual"
        "#,
        possible_values = true
    )]
    pub python_downloads: Option<PythonDownloads>,
    /// The maximum number of in-flight concurrent downloads that uv will perform at any given
    /// time.
    #[option(
        default = "50",
        value_type = "int",
        example = r#"
            concurrent-downloads = 4
        "#
    )]
    pub concurrent_downloads: Option<NonZeroUsize>,
    /// The maximum number of source distributions that uv will build concurrently at any given
    /// time.
    ///
    /// Defaults to the number of available CPU cores.
    #[option(
        default = "None",
        value_type = "int",
        example = r#"
            concurrent-builds = 4
        "#
    )]
    pub concurrent_builds: Option<NonZeroUsize>,
    /// The number of threads used when installing and unzipping packages.
    ///
    /// Defaults to the number of available CPU cores.
    #[option(
        default = "None",
        value_type = "int",
        example = r#"
            concurrent-installs = 4
        "#
    )]
    pub concurrent_installs: Option<NonZeroUsize>,
    /// The URL of the HTTP proxy to use.
    #[option(
        default = "None",
        value_type = "str",
        uv_toml_only = true,
        example = r#"
            http-proxy = "http://proxy.example.com"
        "#
    )]
    pub http_proxy: Option<ProxyUrl>,
    /// The URL of the HTTPS proxy to use.
    #[option(
        default = "None",
        value_type = "str",
        uv_toml_only = true,
        example = r#"
            https-proxy = "https://proxy.example.com"
        "#
    )]
    pub https_proxy: Option<ProxyUrl>,
    /// A list of hosts to exclude from proxying.
    #[option(
        default = "None",
        value_type = "list[str]",
        uv_toml_only = true,
        example = r#"
            no-proxy = ["localhost", "127.0.0.1"]
        "#
    )]
    pub no_proxy: Option<Vec<String>>,
    /// Allow insecure connections to host.
    ///
    /// Expects to receive either a hostname (e.g., `localhost`), a host-port pair (e.g.,
    /// `localhost:8080`), or a URL (e.g., `https://localhost`).
    ///
    /// WARNING: Hosts included in this list will not be verified against the system's certificate
    /// store. Only use `--allow-insecure-host` in a secure network with verified sources, as it
    /// bypasses SSL verification and could expose you to MITM attacks.
    #[option(
        default = "[]",
        value_type = "list[str]",
        example = r#"
            allow-insecure-host = ["localhost:8080"]
        "#
    )]
    pub allow_insecure_host: Option<Vec<TrustedHost>>,
}

/// Like [`GlobalOptions`], but with any `#[serde(flatten)]` fields inlined.
/// This improves line/column information in error messages.
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "kebab-case")]
struct GlobalOptionsWire {
    required_version: Option<RequiredVersion>,
    system_certs: Option<bool>,
    native_tls: Option<bool>,
    offline: Option<bool>,
    no_cache: Option<bool>,
    cache_dir: Option<PathBuf>,

    preview: Option<bool>,
    preview_features: Option<PreviewFeaturesOption>,

    python_preference: Option<PythonPreference>,
    python_downloads: Option<PythonDownloads>,
    concurrent_downloads: Option<NonZeroUsize>,
    concurrent_builds: Option<NonZeroUsize>,
    concurrent_installs: Option<NonZeroUsize>,
    http_proxy: Option<ProxyUrl>,
    https_proxy: Option<ProxyUrl>,
    no_proxy: Option<Vec<String>>,
    allow_insecure_host: Option<Vec<TrustedHost>>,
}

impl TryFrom<GlobalOptionsWire> for GlobalOptions {
    type Error = &'static str;

    #[allow(deprecated)]
    fn try_from(value: GlobalOptionsWire) -> Result<Self, Self::Error> {
        let GlobalOptionsWire {
            required_version,
            system_certs,
            native_tls,
            offline,
            no_cache,
            cache_dir,
            preview,
            preview_features,
            python_preference,
            python_downloads,
            concurrent_downloads,
            concurrent_builds,
            concurrent_installs,
            http_proxy,
            https_proxy,
            no_proxy,
            allow_insecure_host,
        } = value;

        Ok(Self {
            required_version,
            system_certs,
            native_tls,
            offline,
            no_cache,
            cache_dir,
            preview: PreviewOption::try_from(preview, preview_features)?,
            python_preference,
            python_downloads,
            concurrent_downloads,
            concurrent_builds,
            concurrent_installs,
            http_proxy,
            https_proxy,
            no_proxy,
            allow_insecure_host,
        })
    }
}

/// Resolve registry indexes and find-links relative to the given root directory.
fn rebase_indexes(
    root_dir: &Path,
    indexes: &mut Option<Vec<Index>>,
    index_url: &mut Option<PipIndex>,
    extra_index_urls: &mut Option<Vec<PipExtraIndex>>,
    find_links: &mut Option<Vec<PipFindLinks>>,
) -> Result<(), IndexUrlError> {
    *indexes = indexes
        .take()
        .map(|indexes| {
            indexes
                .into_iter()
                .map(|index| index.relative_to(root_dir))
                .collect::<Result<Vec<_>, _>>()
        })
        .transpose()?;
    *index_url = index_url
        .take()
        .map(|index| index.relative_to(root_dir))
        .transpose()?;
    *extra_index_urls = extra_index_urls
        .take()
        .map(|indexes| {
            indexes
                .into_iter()
                .map(|index| index.relative_to(root_dir))
                .collect::<Result<Vec<_>, _>>()
        })
        .transpose()?;
    *find_links = find_links
        .take()
        .map(|find_links| {
            find_links
                .into_iter()
                .map(|find_link| find_link.relative_to(root_dir))
                .collect::<Result<Vec<_>, _>>()
        })
        .transpose()?;

    Ok(())
}

/// Settings relevant to all installer operations.
#[derive(Debug, Clone, Default, CombineOptions)]
pub struct InstallerOptions {
    index: Option<Vec<Index>>,
    index_url: Option<PipIndex>,
    extra_index_url: Option<Vec<PipExtraIndex>>,
    no_index: Option<bool>,
    find_links: Option<Vec<PipFindLinks>>,
    index_strategy: Option<IndexStrategy>,
    keyring_provider: Option<KeyringProviderType>,
    config_settings: Option<ConfigSettings>,
    exclude_newer: Option<ExcludeNewerOverride>,
    link_mode: Option<LinkMode>,
    compile_bytecode: Option<bool>,
    reinstall: Option<Reinstall>,
    build_isolation: Option<BuildIsolation>,
    no_build: Option<bool>,
    no_build_package: Option<Vec<PackageName>>,
    no_binary: Option<bool>,
    no_binary_package: Option<Vec<PackageName>>,
    no_sources: Option<bool>,
    no_sources_package: Option<Vec<PackageName>>,
}

/// Settings shared by all operations that use package indexes.
#[derive(Debug, Clone, Default, CombineOptions)]
pub struct IndexOptions {
    pub index: Option<Vec<Index>>,
    pub index_url: Option<PipIndex>,
    pub extra_index_url: Option<Vec<PipExtraIndex>>,
    pub no_index: Option<bool>,
    pub find_links: Option<Vec<PipFindLinks>>,
}

impl IndexOptions {
    /// Resolve the [`IndexOptions`] relative to the given root directory.
    pub fn relative_to(mut self, root_dir: &Path) -> Result<Self, IndexUrlError> {
        rebase_indexes(
            root_dir,
            &mut self.index,
            &mut self.index_url,
            &mut self.extra_index_url,
            &mut self.find_links,
        )?;

        Ok(self)
    }
}

impl From<IndexOptions> for IndexLocations {
    fn from(value: IndexOptions) -> Self {
        let IndexOptions {
            index,
            index_url,
            extra_index_url,
            no_index,
            find_links,
        } = value;

        Self::new(
            index
                .into_iter()
                .flatten()
                .chain(extra_index_url.into_iter().flatten().map(Index::from))
                .chain(index_url.into_iter().map(Index::from))
                .collect(),
            find_links.into_iter().flatten().map(Index::from).collect(),
            no_index.unwrap_or_default(),
        )
    }
}

impl From<IndexOptions> for PipOptions {
    fn from(value: IndexOptions) -> Self {
        let IndexOptions {
            index,
            index_url,
            extra_index_url,
            no_index,
            find_links,
        } = value;

        Self {
            index,
            index_url,
            extra_index_url,
            no_index,
            find_links,
            ..Self::default()
        }
    }
}

/// Settings relevant to all resolver operations.
#[derive(Debug, Clone, Default, CombineOptions)]
pub struct ResolverOptions {
    pub indexes: IndexOptions,
    pub index_strategy: Option<IndexStrategy>,
    pub keyring_provider: Option<KeyringProviderType>,
    pub resolution: Option<ResolutionMode>,
    pub prerelease: Option<PrereleaseMode>,
    pub prerelease_package: Option<PrereleasePackage>,
    pub fork_strategy: Option<ForkStrategy>,
    pub dependency_metadata: Option<Vec<StaticMetadata>>,
    pub config_settings: Option<ConfigSettings>,
    pub config_settings_package: Option<PackageConfigSettings>,
    pub exclude_newer: Option<ExcludeNewerOverride>,
    pub exclude_newer_package: Option<ExcludeNewerPackage>,
    pub link_mode: Option<LinkMode>,
    pub torch_backend: Option<TorchMode>,
    pub upgrade: Option<Upgrade>,
    pub require_build_hashes: Option<bool>,
    pub build_isolation: Option<BuildIsolation>,
    pub no_build: Option<bool>,
    pub no_build_package: Option<Vec<PackageName>>,
    pub no_binary: Option<bool>,
    pub no_binary_package: Option<Vec<PackageName>>,
    pub extra_build_dependencies: Option<ExtraBuildDependencies>,
    pub extra_build_variables: Option<ExtraBuildVariables>,
    pub no_sources: Option<bool>,
    pub no_sources_package: Option<Vec<PackageName>>,
}

impl ResolverOptions {
    /// Resolve the [`ResolverOptions`] relative to the given root directory.
    pub fn relative_to(mut self, root_dir: &Path) -> Result<Self, IndexUrlError> {
        self.indexes = self.indexes.relative_to(root_dir)?;
        Ok(self)
    }
}

/// Shared settings, relevant to all operations that must resolve and install dependencies. The
/// union of [`InstallerOptions`] and [`ResolverOptions`].
#[derive(Debug, Clone, Default, CombineOptions)]
pub struct ResolverInstallerOptions {
    pub indexes: IndexOptions,
    pub index_strategy: Option<IndexStrategy>,
    pub keyring_provider: Option<KeyringProviderType>,
    pub resolution: Option<ResolutionMode>,
    pub prerelease: Option<PrereleaseMode>,
    pub prerelease_package: Option<PrereleasePackage>,
    pub fork_strategy: Option<ForkStrategy>,
    pub dependency_metadata: Option<Vec<StaticMetadata>>,
    pub config_settings: Option<ConfigSettings>,
    pub config_settings_package: Option<PackageConfigSettings>,
    pub require_build_hashes: Option<bool>,
    pub build_isolation: Option<BuildIsolation>,
    pub extra_build_dependencies: Option<ExtraBuildDependencies>,
    pub extra_build_variables: Option<ExtraBuildVariables>,
    pub exclude_newer: Option<ExcludeNewerOverride>,
    pub exclude_newer_package: Option<ExcludeNewerPackage>,
    pub link_mode: Option<LinkMode>,
    pub torch_backend: Option<TorchMode>,
    pub compile_bytecode: Option<bool>,
    pub no_sources: Option<bool>,
    pub no_sources_package: Option<Vec<PackageName>>,
    pub upgrade: Option<Upgrade>,
    pub reinstall: Option<Reinstall>,
    pub no_build: Option<bool>,
    pub no_build_package: Option<Vec<PackageName>>,
    pub no_binary: Option<bool>,
    pub no_binary_package: Option<Vec<PackageName>>,
}

impl ResolverInstallerOptions {
    /// Resolve the [`ResolverInstallerOptions`] relative to the given root directory.
    pub fn relative_to(mut self, root_dir: &Path) -> Result<Self, IndexUrlError> {
        self.indexes = self.indexes.relative_to(root_dir)?;
        Ok(self)
    }
}

impl From<ResolverInstallerSchema> for ResolverInstallerOptions {
    fn from(value: ResolverInstallerSchema) -> Self {
        let ResolverInstallerSchema {
            index,
            index_url,
            extra_index_url,
            no_index,
            find_links,
            index_strategy,
            keyring_provider,
            resolution,
            prerelease,
            prerelease_package,
            fork_strategy,
            dependency_metadata,
            config_settings,
            config_settings_package,
            require_build_hashes,
            no_build_isolation,
            no_build_isolation_package,
            extra_build_dependencies,
            extra_build_variables,
            exclude_newer,
            exclude_newer_package,
            link_mode,
            torch_backend,
            compile_bytecode,
            no_sources,
            no_sources_package,
            upgrade,
            upgrade_package,
            reinstall,
            reinstall_package,
            no_build,
            no_build_package,
            no_binary,
            no_binary_package,
        } = value;
        Self {
            indexes: IndexOptions {
                index,
                index_url,
                extra_index_url,
                no_index,
                find_links,
            },
            index_strategy,
            keyring_provider,
            resolution,
            prerelease,
            prerelease_package,
            fork_strategy,
            dependency_metadata,
            config_settings,
            config_settings_package,
            require_build_hashes,
            build_isolation: BuildIsolation::from_args(
                no_build_isolation,
                no_build_isolation_package.into_iter().flatten().collect(),
            ),
            extra_build_dependencies,
            extra_build_variables,
            exclude_newer,
            exclude_newer_package,
            link_mode,
            torch_backend,
            compile_bytecode,
            no_sources,
            no_sources_package,
            upgrade: Upgrade::from_args(
                upgrade,
                upgrade_package
                    .into_iter()
                    .flatten()
                    .map(Into::into)
                    .collect(),
                Vec::new(),
            ),
            reinstall: Reinstall::from_args(reinstall, reinstall_package.unwrap_or_default()),
            no_build,
            no_build_package,
            no_binary,
            no_binary_package,
        }
    }
}

impl ResolverInstallerSchema {
    /// Resolve the [`ResolverInstallerSchema`] relative to the given root directory.
    fn relative_to(mut self, root_dir: &Path) -> Result<Self, IndexUrlError> {
        rebase_indexes(
            root_dir,
            &mut self.index,
            &mut self.index_url,
            &mut self.extra_index_url,
            &mut self.find_links,
        )?;

        Ok(self)
    }
}

/// The JSON schema for the `[tool.uv]` section of a `pyproject.toml` file.
#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize, CombineOptions, OptionsMetadata)]
#[serde(rename_all = "kebab-case")]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct ResolverInstallerSchema {
    /// The package indexes to use when resolving dependencies.
    ///
    /// Accepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/)
    /// (the simple repository API), or a local directory laid out in the same format.
    ///
    /// Indexes are considered in the order in which they're defined, such that the first-defined
    /// index has the highest priority. Further, the indexes provided by this setting are given
    /// higher priority than any indexes specified via [`index_url`](#index-url) or
    /// [`extra_index_url`](#extra-index-url). uv will only consider the first index that contains
    /// a given package, unless an alternative [index strategy](#index-strategy) is specified.
    ///
    /// If an index is marked as `explicit = true`, it will be used exclusively for those
    /// dependencies that select it explicitly via `[tool.uv.sources]`, as in:
    ///
    /// ```toml
    /// [[tool.uv.index]]
    /// name = "pytorch"
    /// url = "https://download.pytorch.org/whl/cu130"
    /// explicit = true
    ///
    /// [tool.uv.sources]
    /// torch = { index = "pytorch" }
    /// ```
    ///
    /// If an index is marked as `default = true`, it will be moved to the end of the prioritized list, such that it is
    /// given the lowest priority when resolving packages. Additionally, marking an index as default will disable the
    /// PyPI default index.
    #[option(
        default = "\"[]\"",
        value_type = "dict",
        example = r#"
            [[tool.uv.index]]
            name = "pytorch"
            url = "https://download.pytorch.org/whl/cu130"
        "#
    )]
    pub index: Option<Vec<Index>>,
    /// The URL of the Python package index (by default: <https://pypi.org/simple>).
    ///
    /// Accepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/)
    /// (the simple repository API), or a local directory laid out in the same format.
    ///
    /// The index provided by this setting is given lower priority than any indexes specified via
    /// [`extra_index_url`](#extra-index-url) or [`index`](#index).
    ///
    /// (Deprecated: use `index` instead.)
    #[option(
        default = "\"https://pypi.org/simple\"",
        value_type = "str",
        example = r#"
            index-url = "https://test.pypi.org/simple"
        "#
    )]
    pub index_url: Option<PipIndex>,
    /// Extra URLs of package indexes to use, in addition to `--index-url`.
    ///
    /// Accepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/)
    /// (the simple repository API), or a local directory laid out in the same format.
    ///
    /// All indexes provided via this flag take priority over the index specified by
    /// [`index_url`](#index-url) or [`index`](#index) with `default = true`. When multiple indexes
    /// are provided, earlier values take priority.
    ///
    /// To control uv's resolution strategy when multiple indexes are present, see
    /// [`index_strategy`](#index-strategy).
    ///
    /// (Deprecated: use `index` instead.)
    #[option(
        default = "[]",
        value_type = "list[str]",
        example = r#"
            extra-index-url = ["https://download.pytorch.org/whl/cpu"]
        "#
    )]
    pub extra_index_url: Option<Vec<PipExtraIndex>>,
    /// Ignore all registry indexes (e.g., PyPI), instead relying on direct URL dependencies and
    /// those provided via `--find-links`.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            no-index = true
        "#
    )]
    pub no_index: Option<bool>,
    /// Locations to search for candidate distributions, in addition to those found in the registry
    /// indexes.
    ///
    /// If a path, the target must be a directory that contains packages as wheel files (`.whl`) or
    /// source distributions (e.g., `.tar.gz` or `.zip`) at the top level.
    ///
    /// If a URL, the page must contain a flat list of links to package files adhering to the
    /// formats described above.
    #[option(
        default = "[]",
        value_type = "list[str]",
        example = r#"
            find-links = ["https://download.pytorch.org/whl/torch_stable.html"]
        "#
    )]
    pub find_links: Option<Vec<PipFindLinks>>,
    /// The strategy to use when resolving against multiple index URLs.
    ///
    /// By default, uv will stop at the first index on which a given package is available, and
    /// limit resolutions to those present on that first index (`first-index`). This prevents
    /// "dependency confusion" attacks, whereby an attacker can upload a malicious package under the
    /// same name to an alternate index.
    #[option(
        default = "\"first-index\"",
        value_type = "str",
        example = r#"
            index-strategy = "unsafe-best-match"
        "#,
        possible_values = true
    )]
    pub index_strategy: Option<IndexStrategy>,
    /// Attempt to use `keyring` for authentication for index URLs.
    ///
    /// At present, only `--keyring-provider subprocess` is supported, which configures uv to
    /// use the `keyring` CLI to handle authentication.
    #[option(
        default = "\"disabled\"",
        value_type = "str",
        example = r#"
            keyring-provider = "subprocess"
        "#
    )]
    pub keyring_provider: Option<KeyringProviderType>,
    /// The strategy to use when selecting between the different compatible versions for a given
    /// package requirement.
    ///
    /// By default, uv will use the latest compatible version of each package (`highest`).
    #[option(
        default = "\"highest\"",
        value_type = "str",
        example = r#"
            resolution = "lowest-direct"
        "#,
        possible_values = true
    )]
    pub resolution: Option<ResolutionMode>,
    /// The strategy to use when considering pre-release versions.
    ///
    /// By default, uv will prefer stable candidates, falling back to pre-releases only after every
    /// stable candidate that satisfies the active constraints is rejected
    /// (`if-necessary`).
    #[option(
        default = "\"if-necessary\"",
        value_type = "str",
        example = r#"
            prerelease = "allow"
        "#,
        possible_values = true
    )]
    pub prerelease: Option<PrereleaseMode>,
    /// The strategy to use when considering pre-release versions for specific packages.
    ///
    /// Package-specific modes take precedence over the global [`prerelease`](#prerelease) mode.
    /// Accepts a dictionary mapping package names to any supported pre-release mode.
    #[option(
        default = "{}",
        value_type = "dict",
        example = r#"
            prerelease-package = { numpy = "allow", scipy = "disallow" }
        "#
    )]
    pub prerelease_package: Option<PrereleasePackage>,
    /// The strategy to use when selecting multiple versions of a given package across Python
    /// versions and platforms.
    ///
    /// By default, uv will optimize for selecting the latest version of each package for each
    /// supported Python version (`requires-python`), while minimizing the number of selected
    /// versions across platforms.
    ///
    /// Under `fewest`, uv will minimize the number of selected versions for each package,
    /// preferring older versions that are compatible with a wider range of supported Python
    /// versions or platforms.
    #[option(
        default = "\"requires-python\"",
        value_type = "str",
        example = r#"
            fork-strategy = "fewest"
        "#,
        possible_values = true
    )]
    pub fork_strategy: Option<ForkStrategy>,
    /// Pre-defined static metadata for dependencies of the project (direct or transitive). When
    /// provided, enables the resolver to use the specified metadata instead of querying the
    /// registry or building the relevant package from source.
    ///
    /// Metadata should be provided in adherence with the [Metadata 2.3](https://packaging.python.org/en/latest/specifications/core-metadata/)
    /// standard, though only the following fields are respected:
    ///
    /// - `name`: The name of the package.
    /// - (Optional) `version`: The version of the package. If omitted, the metadata will be applied
    ///   to all versions of the package.
    /// - (Optional) `requires-dist`: The dependencies of the package (e.g., `werkzeug>=0.14`).
    /// - (Optional) `requires-python`: The Python version required by the package (e.g., `>=3.10`).
    /// - (Optional) `provides-extra`: The extras provided by the package.
    #[option(
        default = r#"[]"#,
        value_type = "list[dict]",
        example = r#"
            dependency-metadata = [
                { name = "flask", version = "1.0.0", requires-dist = ["werkzeug"], requires-python = ">=3.6" },
            ]
        "#
    )]
    pub dependency_metadata: Option<Vec<StaticMetadata>>,
    /// Settings to pass to the [PEP 517](https://peps.python.org/pep-0517/) build backend,
    /// specified as `KEY=VALUE` pairs.
    #[option(
        default = "{}",
        value_type = "dict",
        example = r#"
            config-settings = { editable_mode = "compat" }
        "#
    )]
    pub config_settings: Option<ConfigSettings>,
    /// Settings to pass to the [PEP 517](https://peps.python.org/pep-0517/) build backend for specific packages,
    /// specified as `KEY=VALUE` pairs.
    ///
    /// Accepts a map from package names to string key-value pairs.
    #[option(
        default = "{}",
        value_type = "dict",
        example = r#"
            config-settings-package = { numpy = { editable_mode = "compat" } }
        "#
    )]
    pub config_settings_package: Option<PackageConfigSettings>,
    /// Disable isolation when building source distributions.
    ///
    /// Assumes that build dependencies specified by [PEP 518](https://peps.python.org/pep-0518/)
    /// are already installed.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            no-build-isolation = true
        "#
    )]
    pub no_build_isolation: Option<bool>,

    /// Require hashes for all build dependencies.
    ///
    /// uv checks hashes provided in `build-constraint-dependencies` when downloading build
    /// dependencies. Enable this setting to require a hash for every build dependency, including
    /// transitive dependencies. You can also provide hashes as URL fragments in
    /// `build-system.requires`. Hashes returned by a build backend do not count.
    ///
    /// Hashes are not required for the `uv_build` backend bundled in uv. When build isolation is
    /// disabled, build dependencies must already be installed and their hashes are not checked.
    /// Already-installed packages and previously built wheels are not checked.
    ///
    /// This setting also applies to `uv pip` commands, where it can be overridden in `[tool.uv.pip]`.
    #[option(
        default = "false",
        value_type = "bool",
        example = "require-build-hashes = true"
    )]
    pub require_build_hashes: Option<bool>,

    /// Disable isolation when building source distributions for a specific package.
    ///
    /// Assumes that the packages' build dependencies specified by [PEP 518](https://peps.python.org/pep-0518/)
    /// are already installed.
    #[option(
        default = "[]",
        value_type = "list[str]",
        example = r#"
        no-build-isolation-package = ["package1", "package2"]
    "#
    )]
    pub no_build_isolation_package: Option<Vec<PackageName>>,
    /// Additional build dependencies for packages.
    ///
    /// This allows extending the PEP 517 build environment for the project's dependencies with
    /// additional packages. This is useful for packages that assume the presence of packages like
    /// `pip`, and do not declare them as build dependencies.
    #[option(
        default = "[]",
        value_type = "dict",
        example = r#"
            extra-build-dependencies = { pytest = ["setuptools"] }
        "#
    )]
    pub extra_build_dependencies: Option<ExtraBuildDependencies>,
    /// Extra environment variables to set when building certain packages.
    ///
    /// Environment variables will be added to the environment when building the
    /// specified packages.
    #[option(
        default = r#"{}"#,
        value_type = r#"dict[str, dict[str, str]]"#,
        example = r#"
            extra-build-variables = { flash-attn = { FLASH_ATTENTION_SKIP_CUDA_BUILD = "TRUE" } }
        "#
    )]
    pub extra_build_variables: Option<ExtraBuildVariables>,
    /// Limit candidate packages to those that were uploaded prior to the given date.
    ///
    /// The date is compared against the upload time of each individual distribution artifact
    /// (i.e., when each file was uploaded to the package index), not the release date of the
    /// package version.
    ///
    /// Accepts RFC 3339 timestamps (e.g., `2006-12-02T02:07:43Z`), a "friendly" duration (e.g.,
    /// `24 hours`, `1 week`, `30 days`), or an ISO 8601 duration (e.g., `PT24H`, `P7D`, `P30D`).
    ///
    /// Durations do not respect semantics of the local time zone and are always resolved to a fixed
    /// number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored).
    /// Calendar units such as months and years are not allowed.
    ///
    /// Set to `false` to disable `exclude-newer`.
    #[option(
        default = "None",
        value_type = "str | false",
        example = r#"
            exclude-newer = "2006-12-02T02:07:43Z"
        "#
    )]
    pub exclude_newer: Option<ExcludeNewerOverride>,
    /// Limit candidate packages for specific packages to those that were uploaded prior to the
    /// given date.
    ///
    /// Accepts a dictionary format of `PACKAGE = "DATE"` pairs, where `DATE` is an RFC 3339
    /// timestamp (e.g., `2006-12-02T02:07:43Z`), a "friendly" duration (e.g., `24 hours`, `1 week`,
    /// `30 days`), or a ISO 8601 duration (e.g., `PT24H`, `P7D`, `P30D`).
    ///
    /// Durations do not respect semantics of the local time zone and are always resolved to a fixed
    /// number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored).
    /// Calendar units such as months and years are not allowed.
    ///
    /// Set a package to `false` to exempt it from the global [`exclude-newer`](#exclude-newer)
    /// constraint entirely.
    #[option(
        default = "None",
        value_type = "dict",
        example = r#"
            exclude-newer-package = { tqdm = "2022-04-04T00:00:00Z", markupsafe = false }
        "#
    )]
    pub exclude_newer_package: Option<ExcludeNewerPackage>,
    /// The method to use when installing packages from the global cache.
    ///
    /// Defaults to `clone` (also known as Copy-on-Write) on macOS and Linux, and `hardlink` on
    /// Windows.
    ///
    /// WARNING: The use of symlink link mode is discouraged, as they create tight coupling between
    /// the cache and the target environment. For example, clearing the cache (`uv cache clean`)
    /// will break all installed packages by way of removing the underlying source files. Use
    /// symlinks with caution.
    #[option(
        default = "\"clone\" (macOS, Linux) or \"hardlink\" (Windows)",
        value_type = "str",
        example = r#"
            link-mode = "copy"
        "#,
        possible_values = true
    )]
    pub link_mode: Option<LinkMode>,
    /// Compile Python files to bytecode after installation.
    ///
    /// By default, uv does not compile Python (`.py`) files to bytecode (`__pycache__/*.pyc`);
    /// instead, compilation is performed lazily the first time a module is imported. For use-cases
    /// in which start time is critical, such as CLI applications and Docker containers, this option
    /// can be enabled to trade longer installation times for faster start times.
    ///
    /// When enabled, uv will process the entire site-packages directory (including packages that
    /// are not being modified by the current operation) for consistency. Like pip, it will also
    /// ignore errors.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            compile-bytecode = true
        "#
    )]
    pub compile_bytecode: Option<bool>,
    /// Ignore the `tool.uv.sources` table when resolving dependencies. Used to lock against the
    /// standards-compliant, publishable package metadata, as opposed to using any local or Git
    /// sources.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            no-sources = true
        "#
    )]
    pub no_sources: Option<bool>,
    /// Ignore `tool.uv.sources` for the specified packages.
    #[option(
        default = "[]",
        value_type = "list[str]",
        example = r#"
            no-sources-package = ["ruff"]
        "#
    )]
    pub no_sources_package: Option<Vec<PackageName>>,
    /// Allow package upgrades, ignoring pinned versions in any existing output file.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            upgrade = true
        "#
    )]
    pub upgrade: Option<bool>,
    /// Allow upgrades for a specific package, ignoring pinned versions in any existing output
    /// file.
    ///
    /// Accepts both standalone package names (`ruff`) and version specifiers (`ruff<0.5.0`).
    #[option(
        default = "[]",
        value_type = "list[str]",
        example = r#"
            upgrade-package = ["ruff"]
        "#
    )]
    pub upgrade_package: Option<Vec<Requirement<VerbatimParsedUrl>>>,
    /// Reinstall all packages, regardless of whether they're already installed. Implies `refresh`.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            reinstall = true
        "#
    )]
    pub reinstall: Option<bool>,
    /// Reinstall a specific package, regardless of whether it's already installed. Implies
    /// `refresh-package`.
    #[option(
        default = "[]",
        value_type = "list[str]",
        example = r#"
            reinstall-package = ["ruff"]
        "#
    )]
    pub reinstall_package: Option<Vec<PackageName>>,
    /// Don't build source distributions.
    ///
    /// When enabled, uv will reuse cached wheels from previously built source distributions, but
    /// operations that require building a source distribution will exit with an error. First-party
    /// packages, such as projects in the workspace, will still be built. uv will also still build
    /// editable requirements, and their build backends may run arbitrary Python code.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            no-build = true
        "#
    )]
    pub no_build: Option<bool>,
    /// Don't build source distributions for a specific package.
    ///
    /// First-party packages, such as projects in the workspace, will still be built.
    #[option(
        default = "[]",
        value_type = "list[str]",
        example = r#"
            no-build-package = ["ruff"]
        "#
    )]
    pub no_build_package: Option<Vec<PackageName>>,
    /// Don't install pre-built wheels.
    ///
    /// The given packages will be built and installed from source. The resolver will still use
    /// pre-built wheels to extract package metadata, if available.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            no-binary = true
        "#
    )]
    pub no_binary: Option<bool>,
    /// Don't install pre-built wheels for a specific package.
    #[option(
        default = "[]",
        value_type = "list[str]",
        example = r#"
            no-binary-package = ["ruff"]
        "#
    )]
    pub no_binary_package: Option<Vec<PackageName>>,
    /// The backend to use when fetching packages in the PyTorch ecosystem.
    ///
    /// When set, uv will ignore the configured index URLs for packages in the PyTorch ecosystem,
    /// and will instead use the defined backend.
    ///
    /// For example, when set to `cpu`, uv will use the CPU-only PyTorch index; when set to `cu126`,
    /// uv will use the PyTorch index for CUDA 12.6.
    ///
    /// The `auto` mode will attempt to detect the appropriate PyTorch index based on the currently
    /// installed CUDA drivers.
    ///
    /// This setting is only respected by `uv pip` commands.
    ///
    /// This option is in preview and may change in any future release.
    #[option(
        default = "null",
        value_type = "str",
        example = r#"
            torch-backend = "auto"
        "#
    )]
    pub torch_backend: Option<TorchMode>,
}

/// Shared settings, relevant to all operations that might create managed python installations.
#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize, CombineOptions, OptionsMetadata)]
#[serde(rename_all = "kebab-case")]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct PythonInstallMirrors {
    /// Mirror URL for downloading managed Python installations.
    ///
    /// By default, managed Python installations are downloaded from [`python-build-standalone`](https://github.com/astral-sh/python-build-standalone).
    /// This variable can be set to a mirror URL to use a different source for Python installations.
    /// The provided URL will replace `https://github.com/astral-sh/python-build-standalone/releases/download` in, e.g., `https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz`.
    ///
    /// Distributions can be read from a local directory by using the `file://` URL scheme.
    #[option(
        default = "None",
        value_type = "str",
        uv_toml_only = true,
        example = r#"
            python-install-mirror = "https://github.com/astral-sh/python-build-standalone/releases/download"
        "#
    )]
    pub python_install_mirror: Option<String>,
    /// Mirror URL to use for downloading managed PyPy installations.
    ///
    /// By default, managed PyPy installations are downloaded from [downloads.python.org](https://downloads.python.org/).
    /// This variable can be set to a mirror URL to use a different source for PyPy installations.
    /// The provided URL will replace `https://downloads.python.org/pypy` in, e.g., `https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2`.
    ///
    /// Distributions can be read from a
    /// local directory by using the `file://` URL scheme.
    #[option(
        default = "None",
        value_type = "str",
        uv_toml_only = true,
        example = r#"
            pypy-install-mirror = "https://downloads.python.org/pypy"
        "#
    )]
    pub pypy_install_mirror: Option<String>,
    /// Mirror URL to use for downloading managed GraalPy installations.
    ///
    /// By default, managed GraalPy installations are downloaded from [GitHub](https://github.com/oracle/graalpython/releases).
    /// This variable can be set to a mirror URL to use a different source for GraalPy installations.
    /// The provided URL will replace `https://github.com/oracle/graalpython/releases/download` in, e.g., `https://github.com/oracle/graalpython/releases/download/graal-24.2.2/graalpy-24.2.2-macos-aarch64.tar.gz`.
    ///
    /// Distributions can be read from a local directory by using the `file://` URL scheme.
    #[option(
        default = "None",
        value_type = "str",
        uv_toml_only = true,
        example = r#"
            graalpy-install-mirror = "https://github.com/oracle/graalpython/releases/download"
        "#
    )]
    pub graalpy_install_mirror: Option<String>,
    /// Mirror URL to use for downloading managed Pyodide installations.
    ///
    /// By default, managed Pyodide installations are downloaded from [GitHub](https://github.com/pyodide/pyodide/releases).
    /// This variable can be set to a mirror URL to use a different source for Pyodide installations.
    /// The provided URL will replace `https://github.com/pyodide/pyodide/releases/download` in, e.g., `https://github.com/pyodide/pyodide/releases/download/0.29.5/xbuildenv-0.29.5.tar.gz`.
    ///
    /// Distributions can be read from a local directory by using the `file://` URL scheme.
    #[option(
        default = "None",
        value_type = "str",
        uv_toml_only = true,
        example = r#"
            pyodide-install-mirror = "https://github.com/pyodide/pyodide/releases/download"
        "#
    )]
    pub pyodide_install_mirror: Option<String>,

    /// URL pointing to JSON of custom Python installations.
    #[option(
        default = "None",
        value_type = "str",
        uv_toml_only = true,
        example = r#"
            python-downloads-json-url = "/etc/uv/python-downloads.json"
        "#
    )]
    pub python_downloads_json_url: Option<String>,
}

impl PythonInstallMirrors {
    /// Return the mirrors to use for managed Python downloads.
    pub fn mirrors(&self) -> PythonDownloadMirrors<'_> {
        PythonDownloadMirrors {
            cpython: self.python_install_mirror.as_deref(),
            pypy: self.pypy_install_mirror.as_deref(),
            graalpy: self.graalpy_install_mirror.as_deref(),
            pyodide: self.pyodide_install_mirror.as_deref(),
        }
    }

    #[must_use]
    pub fn combine(self, other: Self) -> Self {
        Self {
            python_install_mirror: self.python_install_mirror.or(other.python_install_mirror),
            pypy_install_mirror: self.pypy_install_mirror.or(other.pypy_install_mirror),
            graalpy_install_mirror: self.graalpy_install_mirror.or(other.graalpy_install_mirror),
            pyodide_install_mirror: self.pyodide_install_mirror.or(other.pyodide_install_mirror),
            python_downloads_json_url: self
                .python_downloads_json_url
                .or(other.python_downloads_json_url),
        }
    }
}

/// Settings that are specific to the `uv pip` command-line interface.
///
/// These values will be ignored when running commands outside the `uv pip` namespace (e.g.,
/// `uv lock`, `uvx`).
#[derive(Debug, Clone, Default, Deserialize, CombineOptions, OptionsMetadata)]
#[serde(deny_unknown_fields, rename_all = "kebab-case")]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct PipOptions {
    /// The Python interpreter into which packages should be installed.
    ///
    /// By default, uv installs into the virtual environment in the current working directory or
    /// any parent directory. The `--python` option allows you to specify a different interpreter,
    /// which is intended for use in continuous integration (CI) environments or other automated
    /// workflows.
    ///
    /// Supported formats:
    /// - `3.10` looks for an installed Python 3.10 in the registry on Windows (see
    ///   `py --list-paths`), or `python3.10` on Linux and macOS.
    /// - `python3.10` or `python.exe` looks for a binary with the given name in `PATH`.
    /// - `/home/ferris/.local/bin/python3.10` uses the exact Python at the given path.
    #[option(
        default = "None",
        value_type = "str",
        example = r#"
            python = "3.10"
        "#
    )]
    pub python: Option<String>,
    /// Install packages into the system Python environment.
    ///
    /// By default, uv installs into the virtual environment in the current working directory or
    /// any parent directory. The `--system` option instructs uv to instead use the first Python
    /// found in the system `PATH`.
    ///
    /// WARNING: `--system` is intended for use in continuous integration (CI) environments and
    /// should be used with caution, as it can modify the system Python installation.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            system = true
        "#
    )]
    pub system: Option<bool>,
    /// Allow uv to modify an `EXTERNALLY-MANAGED` Python installation.
    ///
    /// WARNING: `--break-system-packages` is intended for use in continuous integration (CI)
    /// environments, when installing into Python installations that are managed by an external
    /// package manager, like `apt`. It should be used with caution, as such Python installations
    /// explicitly recommend against modifications by other package managers (like uv or pip).
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            break-system-packages = true
        "#
    )]
    pub break_system_packages: Option<bool>,
    /// Install packages into the specified directory, rather than into the virtual or system Python
    /// environment. The packages will be installed at the top-level of the directory.
    #[option(
        default = "None",
        value_type = "str",
        example = r#"
            target = "./target"
        "#
    )]
    pub target: Option<PathBuf>,
    /// Install packages into `lib`, `bin`, and other top-level folders under the specified
    /// directory, as if a virtual environment were present at that location.
    ///
    /// In general, prefer the use of `--python` to install into an alternate environment, as
    /// scripts and other artifacts installed via `--prefix` will reference the installing
    /// interpreter, rather than any interpreter added to the `--prefix` directory, rendering them
    /// non-portable.
    #[option(
        default = "None",
        value_type = "str",
        example = r#"
            prefix = "./prefix"
        "#
    )]
    pub prefix: Option<PathBuf>,
    #[serde(skip)]
    #[cfg_attr(feature = "schemars", schemars(skip))]
    pub index: Option<Vec<Index>>,
    /// The URL of the Python package index (by default: <https://pypi.org/simple>).
    ///
    /// Accepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/)
    /// (the simple repository API), or a local directory laid out in the same format.
    ///
    /// The index provided by this setting is given lower priority than any indexes specified via
    /// [`extra_index_url`](#extra-index-url).
    #[option(
        default = "\"https://pypi.org/simple\"",
        value_type = "str",
        example = r#"
            index-url = "https://test.pypi.org/simple"
        "#
    )]
    pub index_url: Option<PipIndex>,
    /// Extra URLs of package indexes to use, in addition to `--index-url`.
    ///
    /// Accepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/)
    /// (the simple repository API), or a local directory laid out in the same format.
    ///
    /// All indexes provided via this flag take priority over the index specified by
    /// [`index_url`](#index-url). When multiple indexes are provided, earlier values take priority.
    ///
    /// To control uv's resolution strategy when multiple indexes are present, see
    /// [`index_strategy`](#index-strategy).
    #[option(
        default = "[]",
        value_type = "list[str]",
        example = r#"
            extra-index-url = ["https://download.pytorch.org/whl/cpu"]
        "#
    )]
    pub extra_index_url: Option<Vec<PipExtraIndex>>,
    /// Ignore all registry indexes (e.g., PyPI), instead relying on direct URL dependencies and
    /// those provided via `--find-links`.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            no-index = true
        "#
    )]
    pub no_index: Option<bool>,
    /// Locations to search for candidate distributions, in addition to those found in the registry
    /// indexes.
    ///
    /// If a path, the target must be a directory that contains packages as wheel files (`.whl`) or
    /// source distributions (e.g., `.tar.gz` or `.zip`) at the top level.
    ///
    /// If a URL, the page must contain a flat list of links to package files adhering to the
    /// formats described above.
    #[option(
        default = "[]",
        value_type = "list[str]",
        example = r#"
            find-links = ["https://download.pytorch.org/whl/torch_stable.html"]
        "#
    )]
    pub find_links: Option<Vec<PipFindLinks>>,
    /// The strategy to use when resolving against multiple index URLs.
    ///
    /// By default, uv will stop at the first index on which a given package is available, and
    /// limit resolutions to those present on that first index (`first-index`). This prevents
    /// "dependency confusion" attacks, whereby an attacker can upload a malicious package under the
    /// same name to an alternate index.
    #[option(
        default = "\"first-index\"",
        value_type = "str",
        example = r#"
            index-strategy = "unsafe-best-match"
        "#,
        possible_values = true
    )]
    pub index_strategy: Option<IndexStrategy>,
    /// Attempt to use `keyring` for authentication for index URLs.
    ///
    /// At present, only `--keyring-provider subprocess` is supported, which configures uv to
    /// use the `keyring` CLI to handle authentication.
    #[option(
        default = "disabled",
        value_type = "str",
        example = r#"
            keyring-provider = "subprocess"
        "#
    )]
    pub keyring_provider: Option<KeyringProviderType>,
    /// Don't build source distributions.
    ///
    /// When enabled, uv will reuse cached wheels from previously built source distributions, but
    /// operations that require building a source distribution will exit with an error. uv may
    /// still build editable requirements, and their build backends may run arbitrary Python code.
    ///
    /// Alias for `--only-binary :all:`.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            no-build = true
        "#
    )]
    pub no_build: Option<bool>,
    /// Don't install pre-built wheels.
    ///
    /// The given packages will be built and installed from source. The resolver will still use
    /// pre-built wheels to extract package metadata, if available.
    ///
    /// Multiple packages may be provided. Disable binaries for all packages with `:all:`.
    /// Clear previously specified packages with `:none:`.
    #[option(
        default = "[]",
        value_type = "list[str]",
        example = r#"
            no-binary = ["ruff"]
        "#
    )]
    pub no_binary: Option<Vec<PackageNameSpecifier>>,
    /// Only use pre-built wheels; don't build source distributions.
    ///
    /// When enabled, uv will reuse cached wheels from previously built source distributions, but
    /// operations that require building a source distribution for the given packages will exit
    /// with an error. uv may still build editable requirements, and their build backends may run
    /// arbitrary Python code.
    ///
    /// Multiple packages may be provided. Disable binaries for all packages with `:all:`.
    /// Clear previously specified packages with `:none:`.
    #[option(
        default = "[]",
        value_type = "list[str]",
        example = r#"
            only-binary = ["ruff"]
        "#
    )]
    pub only_binary: Option<Vec<PackageNameSpecifier>>,
    /// Disable isolation when building source distributions.
    ///
    /// Assumes that build dependencies specified by [PEP 518](https://peps.python.org/pep-0518/)
    /// are already installed.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            no-build-isolation = true
        "#
    )]
    pub no_build_isolation: Option<bool>,
    /// Require hashes for all build dependencies in `uv pip` commands.
    ///
    /// Overrides `require-build-hashes` in `[tool.uv]`. This does not require hashes for runtime
    /// dependencies; use `require-hashes` for those.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            require-build-hashes = true
        "#
    )]
    pub require_build_hashes: Option<bool>,
    /// Disable isolation when building source distributions for a specific package.
    ///
    /// Assumes that the packages' build dependencies specified by [PEP 518](https://peps.python.org/pep-0518/)
    /// are already installed.
    #[option(
        default = "[]",
        value_type = "list[str]",
        example = r#"
            no-build-isolation-package = ["package1", "package2"]
        "#
    )]
    pub no_build_isolation_package: Option<Vec<PackageName>>,
    /// Additional build dependencies for packages.
    ///
    /// This allows extending the PEP 517 build environment for the project's dependencies with
    /// additional packages. This is useful for packages that assume the presence of packages like
    /// `pip`, and do not declare them as build dependencies.
    #[option(
        default = "[]",
        value_type = "dict",
        example = r#"
            extra-build-dependencies = { pytest = ["setuptools"] }
        "#
    )]
    pub extra_build_dependencies: Option<ExtraBuildDependencies>,
    /// Extra environment variables to set when building certain packages.
    ///
    /// Environment variables will be added to the environment when building the
    /// specified packages.
    #[option(
        default = r#"{}"#,
        value_type = r#"dict[str, dict[str, str]]"#,
        example = r#"
            extra-build-variables = { flash-attn = { FLASH_ATTENTION_SKIP_CUDA_BUILD = "TRUE" } }
        "#
    )]
    pub extra_build_variables: Option<ExtraBuildVariables>,
    /// Validate the Python environment, to detect packages with missing dependencies and other
    /// issues.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            strict = true
        "#
    )]
    pub strict: Option<bool>,
    /// Include optional dependencies from the specified extra; may be provided more than once.
    ///
    /// Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources.
    #[option(
        default = "[]",
        value_type = "list[str]",
        example = r#"
            extra = ["dev", "docs"]
        "#
    )]
    pub extra: Option<Vec<ExtraName>>,
    /// Include all optional dependencies.
    ///
    /// Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            all-extras = true
        "#
    )]
    pub all_extras: Option<bool>,
    /// Exclude the specified optional dependencies if `all-extras` is supplied.
    #[option(
        default = "[]",
        value_type = "list[str]",
        example = r#"
            all-extras = true
            no-extra = ["dev", "docs"]
        "#
    )]
    pub no_extra: Option<Vec<ExtraName>>,
    /// Ignore package dependencies, instead only add those packages explicitly listed
    /// on the command line to the resulting requirements file.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            no-deps = true
        "#
    )]
    pub no_deps: Option<bool>,
    /// Include the following dependency groups.
    #[option(
        default = "None",
        value_type = "list[str]",
        example = r#"
            group = ["dev", "docs"]
        "#
    )]
    pub group: Option<Vec<PipGroupName>>,
    /// Allow `uv pip sync` with empty requirements, which will clear the environment of all
    /// packages.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            allow-empty-requirements = true
        "#
    )]
    pub allow_empty_requirements: Option<bool>,
    /// The strategy to use when selecting between the different compatible versions for a given
    /// package requirement.
    ///
    /// By default, uv will use the latest compatible version of each package (`highest`).
    #[option(
        default = "\"highest\"",
        value_type = "str",
        example = r#"
            resolution = "lowest-direct"
        "#,
        possible_values = true
    )]
    pub resolution: Option<ResolutionMode>,
    /// The strategy to use when considering pre-release versions.
    ///
    /// By default, uv will prefer stable candidates, falling back to pre-releases only after every
    /// stable candidate that satisfies the active constraints is rejected
    /// (`if-necessary`).
    #[option(
        default = "\"if-necessary\"",
        value_type = "str",
        example = r#"
            prerelease = "allow"
        "#,
        possible_values = true
    )]
    pub prerelease: Option<PrereleaseMode>,
    #[serde(skip)]
    #[cfg_attr(feature = "schemars", schemars(skip))]
    pub prerelease_package: Option<PrereleasePackage>,
    /// The strategy to use when selecting multiple versions of a given package across Python
    /// versions and platforms.
    ///
    /// By default, uv will optimize for selecting the latest version of each package for each
    /// supported Python version (`requires-python`), while minimizing the number of selected
    /// versions across platforms.
    ///
    /// Under `fewest`, uv will minimize the number of selected versions for each package,
    /// preferring older versions that are compatible with a wider range of supported Python
    /// versions or platforms.
    #[option(
        default = "\"requires-python\"",
        value_type = "str",
        example = r#"
            fork-strategy = "fewest"
        "#,
        possible_values = true
    )]
    pub fork_strategy: Option<ForkStrategy>,
    /// Pre-defined static metadata for dependencies of the project (direct or transitive). When
    /// provided, enables the resolver to use the specified metadata instead of querying the
    /// registry or building the relevant package from source.
    ///
    /// Metadata should be provided in adherence with the [Metadata 2.3](https://packaging.python.org/en/latest/specifications/core-metadata/)
    /// standard, though only the following fields are respected:
    ///
    /// - `name`: The name of the package.
    /// - (Optional) `version`: The version of the package. If omitted, the metadata will be applied
    ///   to all versions of the package.
    /// - (Optional) `requires-dist`: The dependencies of the package (e.g., `werkzeug>=0.14`).
    /// - (Optional) `requires-python`: The Python version required by the package (e.g., `>=3.10`).
    /// - (Optional) `provides-extra`: The extras provided by the package.
    #[option(
        default = r#"[]"#,
        value_type = "list[dict]",
        example = r#"
            dependency-metadata = [
                { name = "flask", version = "1.0.0", requires-dist = ["werkzeug"], requires-python = ">=3.6" },
            ]
        "#
    )]
    pub dependency_metadata: Option<Vec<StaticMetadata>>,
    /// Write the requirements generated by `uv pip compile` to the given `requirements.txt` file.
    ///
    /// If the file already exists, the existing versions will be preferred when resolving
    /// dependencies, unless `--upgrade` is also specified.
    #[option(
        default = "None",
        value_type = "str",
        example = r#"
            output-file = "requirements.txt"
        "#
    )]
    pub output_file: Option<PathBuf>,
    /// Include extras in the output file.
    ///
    /// By default, uv strips extras, as any packages pulled in by the extras are already included
    /// as dependencies in the output file directly. Further, output files generated with
    /// `--no-strip-extras` cannot be used as constraints files in `install` and `sync` invocations.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            no-strip-extras = true
        "#
    )]
    pub no_strip_extras: Option<bool>,
    /// Include environment markers in the output file generated by `uv pip compile`.
    ///
    /// By default, uv strips environment markers, as the resolution generated by `compile` is
    /// only guaranteed to be correct for the target environment.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            no-strip-markers = true
        "#
    )]
    pub no_strip_markers: Option<bool>,
    /// Exclude comment annotations indicating the source of each package from the output file
    /// generated by `uv pip compile`.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            no-annotate = true
        "#
    )]
    pub no_annotate: Option<bool>,
    /// Exclude the comment header at the top of output file generated by `uv pip compile`.
    #[option(
        default = r#"false"#,
        value_type = "bool",
        example = r#"
            no-header = true
        "#
    )]
    pub no_header: Option<bool>,
    /// The header comment to include at the top of the output file generated by `uv pip compile`.
    ///
    /// Used to reflect custom build scripts and commands that wrap `uv pip compile`.
    #[option(
        default = "None",
        value_type = "str",
        example = r#"
            custom-compile-command = "./custom-uv-compile.sh"
        "#
    )]
    pub custom_compile_command: Option<String>,
    /// Include distribution hashes in the output file.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            generate-hashes = true
        "#
    )]
    pub generate_hashes: Option<bool>,
    /// Settings to pass to the [PEP 517](https://peps.python.org/pep-0517/) build backend,
    /// specified as `KEY=VALUE` pairs.
    #[option(
        default = "{}",
        value_type = "dict",
        example = r#"
            config-settings = { editable_mode = "compat" }
        "#
    )]
    pub config_settings: Option<ConfigSettings>,
    /// Settings to pass to the [PEP 517](https://peps.python.org/pep-0517/) build backend for specific packages,
    /// specified as `KEY=VALUE` pairs.
    #[option(
        default = "{}",
        value_type = "dict",
        example = r#"
            config-settings-package = { numpy = { editable_mode = "compat" } }
        "#
    )]
    pub config_settings_package: Option<PackageConfigSettings>,
    /// The minimum Python version that should be supported by the resolved requirements (e.g.,
    /// `3.8` or `3.8.17`).
    ///
    /// If a patch version is omitted, the minimum patch version is assumed. For example, `3.8` is
    /// mapped to `3.8.0`.
    #[option(
        default = "None",
        value_type = "str",
        example = r#"
            python-version = "3.8"
        "#
    )]
    pub python_version: Option<PythonVersion>,
    /// The platform for which requirements should be resolved.
    ///
    /// Represented as a "target triple", a string that describes the target platform in terms of
    /// its CPU, vendor, and operating system name, like `x86_64-unknown-linux-gnu` or
    /// `aarch64-apple-darwin`.
    #[option(
        default = "None",
        value_type = "str",
        example = r#"
            python-platform = "x86_64-unknown-linux-gnu"
        "#
    )]
    pub python_platform: Option<TargetTriple>,
    /// Perform a universal resolution, attempting to generate a single `requirements.txt` output
    /// file that is compatible with all operating systems, architectures, and Python
    /// implementations.
    ///
    /// In universal mode, the current Python version (or user-provided `--python-version`) will be
    /// treated as a lower bound. For example, `--universal --python-version 3.7` would produce a
    /// universal resolution for Python 3.7 and later.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            universal = true
        "#
    )]
    pub universal: Option<bool>,
    /// Limit candidate packages to those that were uploaded prior to a given point in time.
    ///
    /// The date is compared against the upload time of each individual distribution artifact
    /// (i.e., when each file was uploaded to the package index), not the release date of the
    /// package version.
    ///
    /// Accepts RFC 3339 timestamps (e.g., `2006-12-02T02:07:43Z`), a "friendly" duration (e.g.,
    /// `24 hours`, `1 week`, `30 days`), or an ISO 8601 duration (e.g., `PT24H`, `P7D`, `P30D`).
    ///
    /// Durations do not respect semantics of the local time zone and are always resolved to a fixed
    /// number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored).
    /// Calendar units such as months and years are not allowed.
    ///
    /// Set to `false` to disable `exclude-newer`.
    #[option(
        default = "None",
        value_type = "str | false",
        example = r#"
            exclude-newer = "2006-12-02T02:07:43Z"
        "#
    )]
    pub exclude_newer: Option<ExcludeNewerOverride>,
    /// Limit candidate packages for specific packages to those that were uploaded prior to the given date.
    ///
    /// Accepts a dictionary format of `PACKAGE = "DATE"` pairs, where `DATE` is an RFC 3339
    /// timestamp (e.g., `2006-12-02T02:07:43Z`), a "friendly" duration (e.g., `24 hours`, `1 week`,
    /// `30 days`), or a ISO 8601 duration (e.g., `PT24H`, `P7D`, `P30D`).
    ///
    /// Durations do not respect semantics of the local time zone and are always resolved to a fixed
    /// number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored).
    /// Calendar units such as months and years are not allowed.
    ///
    /// Set a package to `false` to exempt it from the global [`exclude-newer`](#exclude-newer)
    /// constraint entirely.
    #[option(
        default = "None",
        value_type = "dict",
        example = r#"
            exclude-newer-package = { tqdm = "2022-04-04T00:00:00Z", markupsafe = false }
        "#
    )]
    pub exclude_newer_package: Option<ExcludeNewerPackage>,
    /// Specify a package to omit from the output resolution. Its dependencies will still be
    /// included in the resolution. Equivalent to pip-compile's `--unsafe-package` option.
    #[option(
        default = "[]",
        value_type = "list[str]",
        example = r#"
            no-emit-package = ["ruff"]
        "#
    )]
    pub no_emit_package: Option<Vec<PackageName>>,
    /// Include `--index-url` and `--extra-index-url` entries in the output file generated by `uv pip compile`.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            emit-index-url = true
        "#
    )]
    pub emit_index_url: Option<bool>,
    /// Include `--find-links` entries in the output file generated by `uv pip compile`.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            emit-find-links = true
        "#
    )]
    pub emit_find_links: Option<bool>,
    /// Include `--no-binary` and `--only-binary` entries in the output file generated by `uv pip compile`.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            emit-build-options = true
        "#
    )]
    pub emit_build_options: Option<bool>,
    /// Whether to emit a marker string indicating the conditions under which the set of pinned
    /// dependencies is valid.
    ///
    /// The pinned dependencies may be valid even when the marker expression is
    /// false, but when the expression is true, the requirements are known to
    /// be correct.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            emit-marker-expression = true
        "#
    )]
    pub emit_marker_expression: Option<bool>,
    /// Include comment annotations indicating the index used to resolve each package (e.g.,
    /// `# from https://pypi.org/simple`).
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            emit-index-annotation = true
        "#
    )]
    pub emit_index_annotation: Option<bool>,
    /// The style of the annotation comments included in the output file, used to indicate the
    /// source of each package.
    #[option(
        default = "\"split\"",
        value_type = "str",
        example = r#"
            annotation-style = "line"
        "#,
        possible_values = true
    )]
    pub annotation_style: Option<AnnotationStyle>,
    /// The method to use when installing packages from the global cache.
    ///
    /// Defaults to `clone` (also known as Copy-on-Write) on macOS and Linux, and `hardlink` on
    /// Windows.
    ///
    /// WARNING: The use of symlink link mode is discouraged, as they create tight coupling between
    /// the cache and the target environment. For example, clearing the cache (`uv cache clean`)
    /// will break all installed packages by way of removing the underlying source files. Use
    /// symlinks with caution.
    #[option(
        default = "\"clone\" (macOS, Linux) or \"hardlink\" (Windows)",
        value_type = "str",
        example = r#"
            link-mode = "copy"
        "#,
        possible_values = true
    )]
    pub link_mode: Option<LinkMode>,
    /// Compile Python files to bytecode after installation.
    ///
    /// By default, uv does not compile Python (`.py`) files to bytecode (`__pycache__/*.pyc`);
    /// instead, compilation is performed lazily the first time a module is imported. For use-cases
    /// in which start time is critical, such as CLI applications and Docker containers, this option
    /// can be enabled to trade longer installation times for faster start times.
    ///
    /// When enabled, uv will process the entire site-packages directory (including packages that
    /// are not being modified by the current operation) for consistency. Like pip, it will also
    /// ignore errors.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            compile-bytecode = true
        "#
    )]
    pub compile_bytecode: Option<bool>,
    /// Require a matching hash for each requirement.
    ///
    /// Hash-checking mode is all or nothing. If enabled, _all_ requirements must be provided
    /// with a corresponding hash or set of hashes. Additionally, if enabled, _all_ requirements
    /// must either be pinned to exact versions (e.g., `==1.0.0`), or be specified via direct URL.
    ///
    /// Hash-checking mode introduces a number of additional constraints:
    ///
    /// - Git dependencies are not supported.
    /// - Editable installations are not supported.
    /// - Local dependencies are not supported, unless they point to a specific wheel (`.whl`) or
    ///   source archive (`.zip`, `.tar.gz`), as opposed to a directory.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            require-hashes = true
        "#
    )]
    pub require_hashes: Option<bool>,
    /// Validate any hashes provided in the requirements file.
    ///
    /// Unlike `--require-hashes`, `--verify-hashes` does not require that all requirements have
    /// hashes; instead, it will limit itself to verifying the hashes of those requirements that do
    /// include them.
    #[option(
        default = "true",
        value_type = "bool",
        example = r#"
            verify-hashes = true
        "#
    )]
    pub verify_hashes: Option<bool>,
    /// Ignore the `tool.uv.sources` table when resolving dependencies. Used to lock against the
    /// standards-compliant, publishable package metadata, as opposed to using any local or Git
    /// sources.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            no-sources = true
        "#
    )]
    pub no_sources: Option<bool>,
    /// Ignore `tool.uv.sources` for the specified packages.
    #[option(
        default = "[]",
        value_type = "list[str]",
        example = r#"
            no-sources-package = ["ruff"]
        "#
    )]
    pub no_sources_package: Option<Vec<PackageName>>,
    /// Allow package upgrades, ignoring pinned versions in any existing output file.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            upgrade = true
        "#
    )]
    pub upgrade: Option<bool>,
    /// Allow upgrades for a specific package, ignoring pinned versions in any existing output
    /// file.
    ///
    /// Accepts both standalone package names (`ruff`) and version specifiers (`ruff<0.5.0`).
    #[option(
        default = "[]",
        value_type = "list[str]",
        example = r#"
            upgrade-package = ["ruff"]
        "#
    )]
    pub upgrade_package: Option<Vec<Requirement<VerbatimParsedUrl>>>,
    /// Reinstall all packages, regardless of whether they're already installed. Implies `refresh`.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            reinstall = true
        "#
    )]
    pub reinstall: Option<bool>,
    /// Reinstall a specific package, regardless of whether it's already installed. Implies
    /// `refresh-package`.
    #[option(
        default = "[]",
        value_type = "list[str]",
        example = r#"
            reinstall-package = ["ruff"]
        "#
    )]
    pub reinstall_package: Option<Vec<PackageName>>,
    /// The backend to use when fetching packages in the PyTorch ecosystem.
    ///
    /// When set, uv will ignore the configured index URLs for packages in the PyTorch ecosystem,
    /// and will instead use the defined backend.
    ///
    /// For example, when set to `cpu`, uv will use the CPU-only PyTorch index; when set to `cu126`,
    /// uv will use the PyTorch index for CUDA 12.6.
    ///
    /// The `auto` mode will attempt to detect the appropriate PyTorch index based on the currently
    /// installed CUDA drivers.
    ///
    /// This setting is only respected by `uv pip` commands.
    ///
    /// This option is in preview and may change in any future release.
    #[option(
        default = "null",
        value_type = "str",
        example = r#"
            torch-backend = "auto"
        "#
    )]
    pub torch_backend: Option<TorchMode>,
}

impl PipOptions {
    /// Resolve the [`PipOptions`] relative to the given root directory.
    fn relative_to(mut self, root_dir: &Path) -> Result<Self, IndexUrlError> {
        rebase_indexes(
            root_dir,
            &mut self.index,
            &mut self.index_url,
            &mut self.extra_index_url,
            &mut self.find_links,
        )?;

        Ok(self)
    }
}

impl From<ResolverInstallerSchema> for ResolverOptions {
    fn from(value: ResolverInstallerSchema) -> Self {
        Self {
            indexes: IndexOptions {
                index: value.index,
                index_url: value.index_url,
                extra_index_url: value.extra_index_url,
                no_index: value.no_index,
                find_links: value.find_links,
            },
            index_strategy: value.index_strategy,
            keyring_provider: value.keyring_provider,
            resolution: value.resolution,
            prerelease: value.prerelease,
            prerelease_package: value.prerelease_package,
            fork_strategy: value.fork_strategy,
            dependency_metadata: value.dependency_metadata,
            config_settings: value.config_settings,
            config_settings_package: value.config_settings_package,
            require_build_hashes: value.require_build_hashes,
            exclude_newer: value.exclude_newer,
            exclude_newer_package: value.exclude_newer_package,
            link_mode: value.link_mode,
            upgrade: Upgrade::from_args(
                value.upgrade,
                value
                    .upgrade_package
                    .into_iter()
                    .flatten()
                    .map(Into::into)
                    .collect(),
                Vec::new(),
            ),
            no_build: value.no_build,
            no_build_package: value.no_build_package,
            no_binary: value.no_binary,
            no_binary_package: value.no_binary_package,
            build_isolation: BuildIsolation::from_args(
                value.no_build_isolation,
                value.no_build_isolation_package.unwrap_or_default(),
            ),
            extra_build_dependencies: value.extra_build_dependencies,
            extra_build_variables: value.extra_build_variables,
            no_sources: value.no_sources,
            no_sources_package: value.no_sources_package,
            torch_backend: value.torch_backend,
        }
    }
}

impl From<ResolverInstallerSchema> for InstallerOptions {
    fn from(value: ResolverInstallerSchema) -> Self {
        Self {
            index: value.index,
            index_url: value.index_url,
            extra_index_url: value.extra_index_url,
            no_index: value.no_index,
            find_links: value.find_links,
            index_strategy: value.index_strategy,
            keyring_provider: value.keyring_provider,
            config_settings: value.config_settings,
            exclude_newer: value.exclude_newer,
            link_mode: value.link_mode,
            compile_bytecode: value.compile_bytecode,
            reinstall: Reinstall::from_args(
                value.reinstall,
                value.reinstall_package.unwrap_or_default(),
            ),
            build_isolation: BuildIsolation::from_args(
                value.no_build_isolation,
                value.no_build_isolation_package.unwrap_or_default(),
            ),
            no_build: value.no_build,
            no_build_package: value.no_build_package,
            no_binary: value.no_binary,
            no_binary_package: value.no_binary_package,
            no_sources: value.no_sources,
            no_sources_package: value.no_sources_package,
        }
    }
}

/// The options persisted alongside an installed tool.
///
/// A mirror of [`ResolverInstallerSchema`], without upgrades and reinstalls, which shouldn't be
/// persisted in a tool receipt.
#[derive(
    Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, CombineOptions, OptionsMetadata,
)]
#[serde(deny_unknown_fields, rename_all = "kebab-case")]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct ToolOptions {
    index: Option<Vec<Index>>,
    index_url: Option<PipIndex>,
    extra_index_url: Option<Vec<PipExtraIndex>>,
    no_index: Option<bool>,
    find_links: Option<Vec<PipFindLinks>>,
    index_strategy: Option<IndexStrategy>,
    keyring_provider: Option<KeyringProviderType>,
    resolution: Option<ResolutionMode>,
    prerelease: Option<PrereleaseMode>,
    prerelease_package: Option<PrereleasePackage>,
    fork_strategy: Option<ForkStrategy>,
    dependency_metadata: Option<Vec<StaticMetadata>>,
    config_settings: Option<ConfigSettings>,
    config_settings_package: Option<PackageConfigSettings>,
    build_isolation: Option<BuildIsolation>,
    require_build_hashes: Option<bool>,
    extra_build_dependencies: Option<ExtraBuildDependencies>,
    extra_build_variables: Option<ExtraBuildVariables>,
    exclude_newer: Option<ExcludeNewerOverride>,
    exclude_newer_package: Option<ExcludeNewerPackage>,
    link_mode: Option<LinkMode>,
    compile_bytecode: Option<bool>,
    no_sources: Option<bool>,
    no_sources_package: Option<Vec<PackageName>>,
    no_build: Option<bool>,
    no_build_package: Option<Vec<PackageName>>,
    no_binary: Option<bool>,
    no_binary_package: Option<Vec<PackageName>>,
    torch_backend: Option<TorchMode>,
}

/// The on-disk representation of [`ToolOptions`] in a tool receipt.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(deny_unknown_fields, rename_all = "kebab-case")]
pub struct ToolOptionsWire {
    index: Option<Vec<Index>>,
    index_url: Option<PipIndex>,
    extra_index_url: Option<Vec<PipExtraIndex>>,
    no_index: Option<bool>,
    find_links: Option<Vec<PipFindLinks>>,
    index_strategy: Option<IndexStrategy>,
    keyring_provider: Option<KeyringProviderType>,
    resolution: Option<ResolutionMode>,
    prerelease: Option<PrereleaseMode>,
    prerelease_package: Option<PrereleasePackage>,
    fork_strategy: Option<ForkStrategy>,
    dependency_metadata: Option<Vec<StaticMetadata>>,
    config_settings: Option<ConfigSettings>,
    config_settings_package: Option<PackageConfigSettings>,
    build_isolation: Option<BuildIsolation>,
    require_build_hashes: Option<bool>,
    extra_build_dependencies: Option<ExtraBuildDependencies>,
    extra_build_variables: Option<ExtraBuildVariables>,
    exclude_newer: Option<ExcludeNewerOverride>,
    exclude_newer_span: Option<ExcludeNewerSpan>,
    #[serde(serialize_with = "serialize_exclude_newer_package_with_spans")]
    exclude_newer_package: Option<ExcludeNewerPackage>,
    link_mode: Option<LinkMode>,
    compile_bytecode: Option<bool>,
    no_sources: Option<bool>,
    no_sources_package: Option<Vec<PackageName>>,
    no_build: Option<bool>,
    no_build_package: Option<Vec<PackageName>>,
    no_binary: Option<bool>,
    no_binary_package: Option<Vec<PackageName>>,
    torch_backend: Option<TorchMode>,
}

impl From<ResolverInstallerOptions> for ToolOptions {
    fn from(value: ResolverInstallerOptions) -> Self {
        Self {
            index: value.indexes.index.map(|indexes| {
                indexes
                    .into_iter()
                    .map(Index::with_promoted_auth_policy)
                    .collect()
            }),
            index_url: value.indexes.index_url,
            extra_index_url: value.indexes.extra_index_url,
            no_index: value.indexes.no_index,
            find_links: value.indexes.find_links,
            index_strategy: value.index_strategy,
            keyring_provider: value.keyring_provider,
            resolution: value.resolution,
            prerelease: value.prerelease,
            prerelease_package: value.prerelease_package,
            fork_strategy: value.fork_strategy,
            dependency_metadata: value.dependency_metadata,
            config_settings: value.config_settings,
            config_settings_package: value.config_settings_package,
            build_isolation: value.build_isolation,
            require_build_hashes: value.require_build_hashes,
            extra_build_dependencies: value.extra_build_dependencies,
            extra_build_variables: value.extra_build_variables,
            exclude_newer: value.exclude_newer,
            exclude_newer_package: value.exclude_newer_package,
            link_mode: value.link_mode,
            compile_bytecode: value.compile_bytecode,
            no_sources: value.no_sources,
            no_sources_package: value.no_sources_package,
            no_build: value.no_build,
            no_build_package: value.no_build_package,
            no_binary: value.no_binary,
            no_binary_package: value.no_binary_package,
            torch_backend: value.torch_backend,
        }
    }
}

impl From<ToolOptionsWire> for ToolOptions {
    fn from(value: ToolOptionsWire) -> Self {
        let exclude_newer = value
            .exclude_newer
            .map(|exclude_newer| match exclude_newer {
                ExcludeNewerOverride::Disabled => ExcludeNewerOverride::Disabled,
                ExcludeNewerOverride::Enabled(exclude_newer) => {
                    let exclude_newer = *exclude_newer;
                    if let Some(span) = value.exclude_newer_span
                        && exclude_newer.span().is_none()
                    {
                        ExcludeNewerValue::relative(span).into()
                    } else {
                        exclude_newer.into()
                    }
                }
            });

        Self {
            index: value.index,
            index_url: value.index_url,
            extra_index_url: value.extra_index_url,
            no_index: value.no_index,
            find_links: value.find_links,
            index_strategy: value.index_strategy,
            keyring_provider: value.keyring_provider,
            resolution: value.resolution,
            prerelease: value.prerelease,
            prerelease_package: value.prerelease_package,
            fork_strategy: value.fork_strategy,
            dependency_metadata: value.dependency_metadata,
            config_settings: value.config_settings,
            config_settings_package: value.config_settings_package,
            build_isolation: value.build_isolation,
            require_build_hashes: value.require_build_hashes,
            extra_build_dependencies: value.extra_build_dependencies,
            extra_build_variables: value.extra_build_variables,
            exclude_newer,
            exclude_newer_package: value.exclude_newer_package,
            link_mode: value.link_mode,
            compile_bytecode: value.compile_bytecode,
            no_sources: value.no_sources,
            no_sources_package: value.no_sources_package,
            no_build: value.no_build,
            no_build_package: value.no_build_package,
            no_binary: value.no_binary,
            no_binary_package: value.no_binary_package,
            torch_backend: value.torch_backend,
        }
    }
}

impl From<ToolOptions> for ToolOptionsWire {
    fn from(value: ToolOptions) -> Self {
        let (exclude_newer, exclude_newer_span) = match &value.exclude_newer {
            Some(ExcludeNewerOverride::Disabled) => (Some(ExcludeNewerOverride::Disabled), None),
            Some(ExcludeNewerOverride::Enabled(value)) => match value.as_ref() {
                ExcludeNewerValue::Absolute(_) => {
                    (Some(ExcludeNewerOverride::Enabled(value.clone())), None)
                }
                ExcludeNewerValue::Relative(span) => (
                    Some(ExcludeNewerValue::absolute(value.timestamp()).into()),
                    Some(*span),
                ),
            },
            None => (None, None),
        };

        Self {
            index: value.index,
            index_url: value.index_url,
            extra_index_url: value.extra_index_url,
            no_index: value.no_index,
            find_links: value.find_links,
            index_strategy: value.index_strategy,
            keyring_provider: value.keyring_provider,
            resolution: value.resolution,
            prerelease: value.prerelease,
            prerelease_package: value.prerelease_package,
            fork_strategy: value.fork_strategy,
            dependency_metadata: value.dependency_metadata,
            config_settings: value.config_settings,
            config_settings_package: value.config_settings_package,
            build_isolation: value.build_isolation,
            require_build_hashes: value.require_build_hashes,
            extra_build_dependencies: value.extra_build_dependencies,
            extra_build_variables: value.extra_build_variables,
            exclude_newer,
            exclude_newer_span,
            exclude_newer_package: value.exclude_newer_package,
            link_mode: value.link_mode,
            compile_bytecode: value.compile_bytecode,
            no_sources: value.no_sources,
            no_sources_package: value.no_sources_package,
            no_build: value.no_build,
            no_build_package: value.no_build_package,
            no_binary: value.no_binary,
            no_binary_package: value.no_binary_package,
            torch_backend: value.torch_backend,
        }
    }
}

impl From<ToolOptions> for ResolverInstallerOptions {
    fn from(value: ToolOptions) -> Self {
        Self {
            indexes: IndexOptions {
                index: value.index,
                index_url: value.index_url,
                extra_index_url: value.extra_index_url,
                no_index: value.no_index,
                find_links: value.find_links,
            },
            index_strategy: value.index_strategy,
            keyring_provider: value.keyring_provider,
            resolution: value.resolution,
            prerelease: value.prerelease,
            prerelease_package: value.prerelease_package,
            fork_strategy: value.fork_strategy,
            dependency_metadata: value.dependency_metadata,
            config_settings: value.config_settings,
            config_settings_package: value.config_settings_package,
            build_isolation: value.build_isolation,
            require_build_hashes: value.require_build_hashes,
            extra_build_dependencies: value.extra_build_dependencies,
            extra_build_variables: value.extra_build_variables,
            exclude_newer: value.exclude_newer,
            exclude_newer_package: value.exclude_newer_package,
            link_mode: value.link_mode,
            compile_bytecode: value.compile_bytecode,
            no_sources: value.no_sources,
            no_sources_package: value.no_sources_package,
            upgrade: None,
            reinstall: None,
            no_build: value.no_build,
            no_build_package: value.no_build_package,
            no_binary: value.no_binary,
            no_binary_package: value.no_binary_package,
            torch_backend: value.torch_backend,
        }
    }
}

/// Like [`Options]`, but with any `#[serde(flatten)]` fields inlined. This leads to far, far
/// better error messages when deserializing.
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
struct OptionsWire {
    // #[serde(flatten)]
    // globals: GlobalOptions
    required_version: Option<RequiredVersion>,
    system_certs: Option<bool>,
    native_tls: Option<bool>,
    offline: Option<bool>,
    no_cache: Option<bool>,
    cache_dir: Option<PathBuf>,
    preview: Option<bool>,
    preview_features: Option<PreviewFeaturesOption>,
    python_preference: Option<PythonPreference>,
    python_downloads: Option<PythonDownloads>,
    concurrent_downloads: Option<NonZeroUsize>,
    concurrent_builds: Option<NonZeroUsize>,
    concurrent_installs: Option<NonZeroUsize>,

    // #[serde(flatten)]
    // top_level: ResolverInstallerOptions
    index: Option<Vec<Index>>,
    index_url: Option<PipIndex>,
    extra_index_url: Option<Vec<PipExtraIndex>>,
    no_index: Option<bool>,
    find_links: Option<Vec<PipFindLinks>>,
    index_strategy: Option<IndexStrategy>,
    keyring_provider: Option<KeyringProviderType>,
    http_proxy: Option<ProxyUrl>,
    https_proxy: Option<ProxyUrl>,
    no_proxy: Option<Vec<String>>,
    allow_insecure_host: Option<Vec<TrustedHost>>,
    resolution: Option<ResolutionMode>,
    prerelease: Option<PrereleaseMode>,
    prerelease_package: Option<PrereleasePackage>,
    fork_strategy: Option<ForkStrategy>,
    dependency_metadata: Option<Vec<StaticMetadata>>,
    config_settings: Option<ConfigSettings>,
    config_settings_package: Option<PackageConfigSettings>,
    no_build_isolation: Option<bool>,
    require_build_hashes: Option<bool>,
    no_build_isolation_package: Option<Vec<PackageName>>,
    extra_build_dependencies: Option<ExtraBuildDependencies>,
    extra_build_variables: Option<ExtraBuildVariables>,
    exclude_newer: Option<ExcludeNewerOverride>,
    exclude_newer_package: Option<ExcludeNewerPackage>,
    link_mode: Option<LinkMode>,
    compile_bytecode: Option<bool>,
    no_sources: Option<bool>,
    no_sources_package: Option<Vec<PackageName>>,
    upgrade: Option<bool>,
    upgrade_package: Option<Vec<Requirement<VerbatimParsedUrl>>>,
    reinstall: Option<bool>,
    reinstall_package: Option<Vec<PackageName>>,
    no_build: Option<bool>,
    no_build_package: Option<Vec<PackageName>>,
    no_binary: Option<bool>,
    no_binary_package: Option<Vec<PackageName>>,
    torch_backend: Option<TorchMode>,

    // #[serde(flatten)]
    // install_mirror: PythonInstallMirrors,
    python_install_mirror: Option<String>,
    pypy_install_mirror: Option<String>,
    graalpy_install_mirror: Option<String>,
    pyodide_install_mirror: Option<String>,
    python_downloads_json_url: Option<String>,

    // #[serde(flatten)]
    // publish: PublishOptions
    publish_url: Option<DisplaySafeUrl>,
    trusted_publishing: Option<TrustedPublishing>,
    check_url: Option<IndexUrl>,

    // #[serde(flatten)]
    // add: AddOptions
    add_bounds: Option<AddBoundsKind>,

    audit: Option<AuditOptions>,
    pip: Option<PipOptions>,
    cache_keys: Option<Vec<CacheKey>>,

    // NOTE(charlie): These fields are shared with `ToolUv` in
    // `crates/uv-workspace/src/pyproject.rs`. The documentation lives on that struct.
    // They're respected in both `pyproject.toml` and `uv.toml` files.
    override_dependencies: Option<Vec<OverrideDependency>>,
    exclude_dependencies: Option<Vec<ExcludeDependency>>,
    constraint_dependencies: Option<Vec<Requirement<VerbatimParsedUrl>>>,
    build_constraint_dependencies: Option<Vec<BuildConstraintDependency>>,
    environments: Option<SupportedEnvironments>,
    required_environments: Option<SupportedEnvironments>,
    minimum_libc_version: Option<MinimumLibcVersion>,

    // NOTE(charlie): These fields should be kept in-sync with `ToolUv` in
    // `crates/uv-workspace/src/pyproject.rs`. The documentation lives on that struct.
    // They're only respected in `pyproject.toml` files, and should be rejected in `uv.toml` files.
    conflicts: Option<serde::de::IgnoredAny>,
    workspace: Option<serde::de::IgnoredAny>,
    sources: Option<serde::de::IgnoredAny>,
    managed: Option<serde::de::IgnoredAny>,
    r#package: Option<serde::de::IgnoredAny>,
    default_groups: Option<serde::de::IgnoredAny>,
    dependency_groups: Option<serde::de::IgnoredAny>,
    dev_dependencies: Option<serde::de::IgnoredAny>,

    // Build backend
    build_backend: Option<serde::de::IgnoredAny>,
}

impl TryFrom<OptionsWire> for Options {
    type Error = &'static str;

    #[allow(deprecated)]
    fn try_from(value: OptionsWire) -> Result<Self, Self::Error> {
        let OptionsWire {
            required_version,
            system_certs,
            native_tls,
            offline,
            no_cache,
            cache_dir,
            preview,
            preview_features,
            python_preference,
            python_downloads,
            python_install_mirror,
            pypy_install_mirror,
            graalpy_install_mirror,
            pyodide_install_mirror,
            python_downloads_json_url,
            concurrent_downloads,
            concurrent_builds,
            concurrent_installs,
            index,
            index_url,
            extra_index_url,
            no_index,
            find_links,
            index_strategy,
            keyring_provider,
            http_proxy,
            https_proxy,
            no_proxy,
            allow_insecure_host,
            resolution,
            prerelease,
            prerelease_package,
            fork_strategy,
            dependency_metadata,
            config_settings,
            config_settings_package,
            no_build_isolation,
            require_build_hashes,
            no_build_isolation_package,
            exclude_newer,
            exclude_newer_package,
            link_mode,
            compile_bytecode,
            no_sources,
            no_sources_package,
            upgrade,
            upgrade_package,
            reinstall,
            reinstall_package,
            no_build,
            no_build_package,
            no_binary,
            no_binary_package,
            torch_backend,
            audit,
            pip,
            cache_keys,
            override_dependencies,
            exclude_dependencies,
            constraint_dependencies,
            build_constraint_dependencies,
            environments,
            required_environments,
            minimum_libc_version,
            conflicts,
            publish_url,
            trusted_publishing,
            check_url,
            workspace,
            sources,
            default_groups,
            dependency_groups,
            extra_build_dependencies,
            extra_build_variables,
            dev_dependencies,
            managed,
            package,
            add_bounds: bounds,
            // Used by the build backend
            build_backend,
        } = value;

        Ok(Self {
            globals: GlobalOptions {
                required_version,
                system_certs,
                native_tls,
                offline,
                no_cache,
                cache_dir,
                preview: PreviewOption::try_from(preview, preview_features)?,
                python_preference,
                python_downloads,
                concurrent_downloads,
                concurrent_builds,
                concurrent_installs,
                http_proxy,
                https_proxy,
                no_proxy,
                // Used twice for backwards compatibility
                allow_insecure_host: allow_insecure_host.clone(),
            },
            top_level: ResolverInstallerSchema {
                index,
                index_url,
                extra_index_url,
                no_index,
                find_links,
                index_strategy,
                keyring_provider,
                resolution,
                prerelease,
                prerelease_package,
                fork_strategy,
                dependency_metadata,
                config_settings,
                config_settings_package,
                no_build_isolation,
                require_build_hashes,
                no_build_isolation_package,
                extra_build_dependencies,
                extra_build_variables,
                exclude_newer,
                exclude_newer_package,
                link_mode,
                compile_bytecode,
                no_sources,
                no_sources_package,
                upgrade,
                upgrade_package,
                reinstall,
                reinstall_package,
                no_build,
                no_build_package,
                no_binary,
                no_binary_package,
                torch_backend,
            },
            pip,
            cache_keys,
            build_backend,
            override_dependencies,
            exclude_dependencies,
            constraint_dependencies,
            build_constraint_dependencies,
            environments,
            required_environments,
            minimum_libc_version,
            install_mirrors: PythonInstallMirrors {
                python_install_mirror,
                pypy_install_mirror,
                graalpy_install_mirror,
                pyodide_install_mirror,
                python_downloads_json_url,
            },
            conflicts,
            publish: PublishOptions {
                publish_url,
                trusted_publishing,
                check_url,
            },
            add: AddOptions { add_bounds: bounds },
            audit,
            workspace,
            sources,
            dev_dependencies,
            default_groups,
            dependency_groups,
            managed,
            package,
        })
    }
}

#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize, CombineOptions, OptionsMetadata)]
#[serde(rename_all = "kebab-case")]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct PublishOptions {
    /// The URL for publishing packages to the Python package index (by default:
    /// <https://upload.pypi.org/legacy/>).
    #[option(
        default = "\"https://upload.pypi.org/legacy/\"",
        value_type = "str",
        example = r#"
            publish-url = "https://test.pypi.org/legacy/"
        "#
    )]
    pub publish_url: Option<DisplaySafeUrl>,

    /// Configure trusted publishing.
    ///
    /// By default, uv checks for trusted publishing when running in a supported environment, but
    /// ignores it if it isn't configured.
    ///
    /// uv's supported environments for trusted publishing include GitHub Actions and GitLab CI/CD.
    #[option(
        default = "automatic",
        value_type = "str",
        example = r#"
            trusted-publishing = "always"
        "#
    )]
    pub trusted_publishing: Option<TrustedPublishing>,

    /// Check an index URL for existing files to skip duplicate uploads.
    ///
    /// This option allows retrying publishing that failed after only some, but not all files have
    /// been uploaded, and handles error due to parallel uploads of the same file.
    ///
    /// Before uploading, the index is checked. If the exact same file already exists in the index,
    /// the file will not be uploaded. If an error occurred during the upload, the index is checked
    /// again, to handle cases where the identical file was uploaded twice in parallel.
    ///
    /// The exact behavior will vary based on the index. When uploading to PyPI, uploading the same
    /// file succeeds even without `--check-url`, while most other indexes error.
    ///
    /// The index must provide one of the supported hashes (SHA-256, SHA-384, or SHA-512).
    #[option(
        default = "None",
        value_type = "str",
        example = r#"
            check-url = "https://test.pypi.org/simple"
        "#
    )]
    pub check_url: Option<IndexUrl>,
}

#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize, CombineOptions, OptionsMetadata)]
#[serde(rename_all = "kebab-case")]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct AddOptions {
    /// The default version specifier when adding a dependency.
    ///
    /// When adding a dependency to the project, if no constraint or URL is provided, a constraint
    /// is added based on the latest compatible version of the package. By default, a lower bound
    /// constraint is used, e.g., `>=1.2.3`.
    ///
    /// When `--frozen` is provided, no resolution is performed, and dependencies are always added
    /// without constraints.
    ///
    /// This option is in preview and may change in any future release.
    #[option(
        default = "\"lower\"",
        value_type = "str",
        example = r#"
            add-bounds = "major"
        "#,
        possible_values = true
    )]
    pub add_bounds: Option<AddBoundsKind>,
}

#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize, CombineOptions, OptionsMetadata)]
#[serde(rename_all = "kebab-case")]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct AuditOptions {
    /// Whether to run the automatic malware check during sync operations.
    #[option(
        default = "false",
        value_type = "bool",
        example = r#"
            malware-check = true
        "#
    )]
    pub malware_check: Option<bool>,

    /// The vulnerability service URL to use for automatic malware checks.
    #[option(
        default = "\"https://api.osv.dev/\"",
        value_type = "str",
        example = r#"
            malware-check-url = "https://example.com"
        "#
    )]
    pub malware_check_url: Option<DisplaySafeUrl>,

    /// A list of vulnerability IDs to ignore during auditing.
    ///
    /// Vulnerabilities matching any of the provided IDs (including aliases) will be excluded from
    /// the audit results.
    #[option(
        default = "[]",
        value_type = "list[str]",
        example = r#"
            ignore = ["PYSEC-2022-43017", "GHSA-5239-wwwm-4pmq"]
        "#
    )]
    pub ignore: Option<Vec<String>>,

    /// A list of vulnerability IDs to ignore during auditing, but only while no fix is available.
    ///
    /// Vulnerabilities matching any of the provided IDs (including aliases) will be excluded from
    /// the audit results as long as they have no known fix versions. Once a fix version becomes
    /// available, the vulnerability will be reported again.
    #[option(
        default = "[]",
        value_type = "list[str]",
        example = r#"
            ignore-until-fixed = ["PYSEC-2022-43017"]
        "#
    )]
    pub ignore_until_fixed: Option<Vec<String>>,
}

#[derive(Debug, Clone)]
pub struct MalwareCheckSettings {
    /// Whether the malware check is enabled.
    pub enabled: bool,
    /// The OSV-shaped service URL to use for malware checks.
    pub malware_check_url: Option<DisplaySafeUrl>,
}

impl MalwareCheckSettings {
    pub fn resolve(
        filesystem: Option<&FilesystemOptions>,
        environment: &EnvironmentOptions,
    ) -> Self {
        let audit = filesystem.and_then(|options| options.audit.as_ref());

        Self {
            enabled: environment
                .malware_check
                .value
                .or(audit.and_then(|audit| audit.malware_check))
                .unwrap_or_default(),
            malware_check_url: environment
                .malware_check_url
                .clone()
                .or_else(|| audit.and_then(|audit| audit.malware_check_url.clone())),
        }
    }
}

/// Represents the `preview-features` configuration option.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(untagged))]
pub enum PreviewFeaturesOption {
    Toggle(bool),
    Features(Vec<MaybePreviewFeature>),
}

// Dispatch by input type so invalid list elements retain their detailed diagnostics.
struct PreviewFeaturesVisitor;

impl<'de> Visitor<'de> for PreviewFeaturesVisitor {
    type Value = PreviewFeaturesOption;

    fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str("a boolean or a list of preview feature names")
    }

    fn visit_bool<E>(self, value: bool) -> Result<Self::Value, E>
    where
        E: Error,
    {
        Ok(PreviewFeaturesOption::Toggle(value))
    }

    fn visit_seq<S>(self, sequence: S) -> Result<Self::Value, S::Error>
    where
        S: SeqAccess<'de>,
    {
        Vec::deserialize(SeqAccessDeserializer::new(sequence)).map(PreviewFeaturesOption::Features)
    }
}

impl<'de> Deserialize<'de> for PreviewFeaturesOption {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        deserializer.deserialize_any(PreviewFeaturesVisitor)
    }
}

#[expect(
    dead_code,
    reason = "Fields are only used by the OptionsMetadata and JsonSchema derives"
)]
#[derive(OptionsMetadata)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(rename_all = "kebab-case"))]
struct PreviewOptionsDefinition {
    // This legacy setting remains supported and included in the JSON schema, but is omitted from
    // option metadata so the generated settings reference documents only `preview-features`.
    /// Whether to enable all experimental, preview features.
    ///
    /// Use `preview-features` instead.
    #[deprecated(note = "use `preview-features` instead")]
    preview: Option<bool>,
    /// Whether to enable specific or all experimental preview features.
    ///
    /// Unknown feature names are ignored with a warning.
    #[option(
        default = "false",
        value_type = "bool | list[str]",
        example = r#"
            preview-features = true
            # or
            preview-features = ["json-output"]
        "#
    )]
    preview_features: Option<PreviewFeaturesOption>,
}

/// Represents the user's preview configuration from either `preview` or `preview-features`.
#[derive(Debug, Clone)]
pub enum PreviewOption {
    /// Whether to enable all experimental, preview features.
    Preview(bool),
    /// Whether to enable specific or all experimental preview features.
    PreviewFeatures(PreviewFeaturesOption),
}

impl uv_options_metadata::OptionsMetadata for PreviewOption {
    fn record(visit: &mut dyn uv_options_metadata::Visit) {
        <PreviewOptionsDefinition as uv_options_metadata::OptionsMetadata>::record(visit);
    }
}

#[cfg(feature = "schemars")]
struct ConflictingPreviewOptions;

#[cfg(feature = "schemars")]
impl schemars::JsonSchema for ConflictingPreviewOptions {
    fn schema_name() -> Cow<'static, str> {
        Cow::Borrowed("ConflictingPreviewOptions")
    }

    fn json_schema(_generator: &mut schemars::SchemaGenerator) -> schemars::Schema {
        schemars::json_schema!({
            "type": "object",
            "properties": {
                "preview": {},
                "preview-features": {},
            },
            "required": ["preview", "preview-features"],
        })
    }
}

#[cfg(feature = "schemars")]
impl schemars::JsonSchema for PreviewOption {
    fn schema_name() -> Cow<'static, str> {
        Cow::Borrowed("PreviewOption")
    }

    fn json_schema(generator: &mut schemars::SchemaGenerator) -> schemars::Schema {
        let mut schema = <PreviewOptionsDefinition as schemars::JsonSchema>::json_schema(generator);
        // Keep this constraint in a referenced schema to avoid a fastjsonschema code-generation
        // bug. See: https://github.com/astral-sh/uv/pull/20547.
        schema.insert(
            "not".to_string(),
            generator
                .subschema_for::<ConflictingPreviewOptions>()
                .into(),
        );
        schema
    }
}

impl PreviewOption {
    fn try_from(
        preview: Option<bool>,
        preview_features: Option<PreviewFeaturesOption>,
    ) -> Result<Option<Self>, &'static str> {
        match (preview, preview_features) {
            (Some(_), Some(_)) => Err("cannot specify both `preview` and `preview-features`"),
            (Some(b), None) => Ok(Some(Self::Preview(b))),
            (None, Some(features)) => Ok(Some(Self::PreviewFeatures(features))),
            (None, None) => Ok(None),
        }
    }

    /// Resolve the preview configuration, warning and ignoring unknown feature names.
    pub fn resolve(&self) -> Preview {
        use PreviewFeaturesOption::{Features, Toggle};

        match self {
            Self::Preview(false) | Self::PreviewFeatures(Toggle(false)) => Preview::default(),
            Self::Preview(true) | Self::PreviewFeatures(Toggle(true)) => Preview::all(),
            Self::PreviewFeatures(Features(features)) => Preview::from_feature_names(features),
        }
    }
}