uv_settings/
lib.rs

1use std::num::NonZeroUsize;
2use std::ops::Deref;
3use std::path::{Path, PathBuf};
4use std::str::FromStr;
5use std::time::Duration;
6use tracing::info_span;
7use uv_client::{DEFAULT_CONNECT_TIMEOUT, DEFAULT_READ_TIMEOUT, DEFAULT_READ_TIMEOUT_UPLOAD};
8use uv_configuration::RequiredVersion;
9use uv_dirs::{system_config_file, user_config_dir};
10use uv_distribution_types::{IndexUrlError, Origin};
11use uv_flags::EnvironmentFlags;
12use uv_fs::Simplified;
13use uv_normalize::{GroupName, PackageName};
14use uv_pep440::Version;
15use uv_redacted::DisplaySafeUrl;
16use uv_static::{EnvVars, InvalidEnvironmentVariable, parse_boolish_environment_variable};
17use uv_torch::AmdGpuArchitecture;
18use uv_warnings::warn_user;
19
20pub use crate::combine::*;
21pub use crate::settings::*;
22
23mod combine;
24mod settings;
25
26/// The [`Options`] as loaded from a configuration file on disk.
27#[derive(Debug, Clone)]
28pub struct FilesystemOptions(Options);
29
30impl FilesystemOptions {
31    /// Convert the [`FilesystemOptions`] into [`Options`].
32    pub fn into_options(self) -> Options {
33        self.0
34    }
35
36    /// Resolve the [`FilesystemOptions`] relative to the given root directory.
37    pub fn relative_to(self, root_dir: &Path) -> Result<Self, IndexUrlError> {
38        Ok(Self(self.0.relative_to(root_dir)?))
39    }
40}
41
42impl Deref for FilesystemOptions {
43    type Target = Options;
44
45    fn deref(&self) -> &Self::Target {
46        &self.0
47    }
48}
49
50impl FilesystemOptions {
51    /// Load the user [`FilesystemOptions`].
52    pub fn user() -> Result<Option<Self>, Error> {
53        let Some(dir) = user_config_dir() else {
54            return Ok(None);
55        };
56        let root = dir.join("uv");
57        let file = root.join("uv.toml");
58
59        tracing::debug!("Searching for user configuration in: `{}`", file.display());
60        match read_file(&file) {
61            Ok(options) => {
62                tracing::debug!("Found user configuration in: `{}`", file.display());
63                validate_uv_toml(&file, &options)?;
64                Ok(Some(Self(options.with_origin(Origin::User))))
65            }
66            Err(Error::Io(err))
67                if matches!(
68                    err.kind(),
69                    std::io::ErrorKind::NotFound
70                        | std::io::ErrorKind::NotADirectory
71                        | std::io::ErrorKind::PermissionDenied
72                ) =>
73            {
74                Ok(None)
75            }
76            Err(err) => Err(err),
77        }
78    }
79
80    pub fn system() -> Result<Option<Self>, Error> {
81        if parse_boolish_environment_variable(EnvVars::UV_NO_SYSTEM_CONFIG)? == Some(true) {
82            return Ok(None);
83        }
84
85        let Some(file) = system_config_file() else {
86            return Ok(None);
87        };
88
89        tracing::debug!("Found system configuration in: `{}`", file.display());
90        let options = read_file(&file)?;
91        validate_uv_toml(&file, &options)?;
92        Ok(Some(Self(options.with_origin(Origin::System))))
93    }
94
95    /// Find the [`FilesystemOptions`] for the given path.
96    ///
97    /// The search starts at the given path and goes up the directory tree until a `uv.toml` file or
98    /// `pyproject.toml` file is found.
99    pub fn find(path: &Path) -> Result<Option<Self>, Error> {
100        for ancestor in path.ancestors() {
101            match Self::from_directory(ancestor) {
102                Ok(Some(options)) => {
103                    return Ok(Some(options));
104                }
105                Ok(None) => {
106                    // Continue traversing the directory tree.
107                }
108                Err(Error::PyprojectToml(path, err)) => {
109                    // If we see an invalid `pyproject.toml`, warn but continue.
110                    warn_user!(
111                        "Failed to parse `{}` during settings discovery:\n{}",
112                        path.user_display().cyan(),
113                        textwrap::indent(&err.to_string(), "  ")
114                    );
115                }
116                Err(err) => {
117                    // Otherwise, warn and stop.
118                    return Err(err);
119                }
120            }
121        }
122        Ok(None)
123    }
124
125    /// Load a [`FilesystemOptions`] from a directory, preferring a `uv.toml` file over a
126    /// `pyproject.toml` file.
127    fn from_directory(dir: &Path) -> Result<Option<Self>, Error> {
128        // Read a `uv.toml` file in the current directory.
129        let path = dir.join("uv.toml");
130        match fs_err::read_to_string(&path) {
131            Ok(content) => {
132                let options =
133                    info_span!("toml::from_str filesystem options uv.toml", path = %path.display())
134                        .in_scope(|| toml::from_str::<Options>(&content))
135                        .map_err(|err| {
136                            check_uv_toml_required_version(
137                                &path,
138                                &content,
139                                Error::UvToml(path.clone(), Box::new(err)),
140                            )
141                        })?
142                        .relative_to(&std::path::absolute(dir)?)?;
143
144                // If the directory also contains a `[tool.uv]` table in a `pyproject.toml` file,
145                // warn.
146                let pyproject = dir.join("pyproject.toml");
147                if let Ok(content) = fs_err::read_to_string(&pyproject) {
148                    let result = info_span!("toml::from_str filesystem options pyproject.toml", path = %pyproject.display())
149                        .in_scope(|| toml::from_str::<PyProjectToml>(&content)).ok();
150                    if let Some(options) =
151                        result.and_then(|pyproject| pyproject.tool.and_then(|tool| tool.uv))
152                    {
153                        warn_uv_toml_masked_fields(&options);
154                    }
155                }
156
157                tracing::debug!("Found workspace configuration at `{}`", path.display());
158                validate_uv_toml(&path, &options)?;
159                return Ok(Some(Self(options.with_origin(Origin::Project))));
160            }
161            Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
162            Err(err) => return Err(err.into()),
163        }
164
165        // Read a `pyproject.toml` file in the current directory.
166        let path = dir.join("pyproject.toml");
167        match fs_err::read_to_string(&path) {
168            Ok(content) => {
169                // Parse, but skip any `pyproject.toml` that doesn't have a `[tool.uv]` section.
170                let pyproject =
171                    info_span!("toml::from_str filesystem options pyproject.toml", path = %path.display())
172                        .in_scope(|| toml::from_str::<PyProjectToml>(&content))
173                        .map_err(|err| {
174                            check_pyproject_required_version(&path, &content, err)
175                        })?;
176                let Some(tool) = pyproject.tool else {
177                    tracing::debug!(
178                        "Skipping `pyproject.toml` in `{}` (no `[tool]` section)",
179                        dir.display()
180                    );
181                    return Ok(None);
182                };
183                let Some(options) = tool.uv else {
184                    tracing::debug!(
185                        "Skipping `pyproject.toml` in `{}` (no `[tool.uv]` section)",
186                        dir.display()
187                    );
188                    return Ok(None);
189                };
190
191                let options = options.relative_to(&std::path::absolute(dir)?)?;
192
193                tracing::debug!("Found workspace configuration at `{}`", path.display());
194                return Ok(Some(Self(options)));
195            }
196            Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
197            Err(err) => return Err(err.into()),
198        }
199
200        Ok(None)
201    }
202
203    /// Load a [`FilesystemOptions`] from a `uv.toml` file.
204    pub fn from_file(path: impl AsRef<Path>) -> Result<Self, Error> {
205        let path = path.as_ref();
206        tracing::debug!("Reading user configuration from: `{}`", path.display());
207
208        let options = read_file(path)?;
209        validate_uv_toml(path, &options)?;
210        Ok(Self(options))
211    }
212}
213
214impl From<Options> for FilesystemOptions {
215    fn from(options: Options) -> Self {
216        Self(options)
217    }
218}
219
220/// Load [`Options`] from a `uv.toml` file.
221fn read_file(path: &Path) -> Result<Options, Error> {
222    let content = fs_err::read_to_string(path)?;
223    let options = info_span!("toml::from_str filesystem options uv.toml", path = %path.display())
224        .in_scope(|| toml::from_str::<Options>(&content))
225        .map_err(|err| {
226            check_uv_toml_required_version(
227                path,
228                &content,
229                Error::UvToml(path.to_path_buf(), Box::new(err)),
230            )
231        })?;
232    let options = if let Some(parent) = std::path::absolute(path)?.parent() {
233        options.relative_to(parent)?
234    } else {
235        options
236    };
237    Ok(options)
238}
239
240/// If `required_version` is set and incompatible with the running uv, return the corresponding
241/// [`Error::RequiredVersion`].
242fn required_version_mismatch(required_version: Option<RequiredVersion>) -> Option<Error> {
243    let required_version = required_version?;
244    let package_version = Version::from_str(uv_version::version())
245        .expect("uv crate version to be a valid PEP 440 version");
246    if required_version.contains(&package_version) {
247        None
248    } else {
249        Some(Error::RequiredVersion {
250            required_version,
251            package_version,
252        })
253    }
254}
255
256/// On a `pyproject.toml` settings parse error, check whether `tool.uv.required-version` should
257/// take precedence over that error.
258fn check_pyproject_required_version(path: &Path, content: &str, source: toml::de::Error) -> Error {
259    let fallback = || Error::PyprojectToml(path.to_path_buf(), Box::new(source));
260    let Ok(pyproject) = info_span!(
261        "toml::from_str filesystem required-version pyproject.toml",
262        path = %path.display()
263    )
264    .in_scope(|| toml::from_str::<PyProjectRequiredVersionToml>(content)) else {
265        return fallback();
266    };
267
268    let required_version = pyproject
269        .tool
270        .and_then(|tool| tool.uv)
271        .and_then(|uv| uv.required_version);
272    required_version_mismatch(required_version).unwrap_or_else(fallback)
273}
274
275/// On a `uv.toml` settings parse or schema error, check whether top-level `required-version`
276/// should take precedence over that error.
277fn check_uv_toml_required_version(path: &Path, content: &str, source: Error) -> Error {
278    let Ok(uv_toml) = info_span!(
279        "toml::from_str filesystem required-version uv.toml",
280        path = %path.display()
281    )
282    .in_scope(|| toml::from_str::<UvRequiredVersionToml>(content)) else {
283        return source;
284    };
285    required_version_mismatch(uv_toml.required_version).unwrap_or(source)
286}
287
288/// Validate that an [`Options`] schema is compatible with `uv.toml`.
289fn validate_uv_toml(path: &Path, options: &Options) -> Result<(), Error> {
290    // A `required-version` mismatch takes precedence over a schema error.
291    if let Some(err) = required_version_mismatch(options.globals.required_version.clone()) {
292        return Err(err);
293    }
294    let Options {
295        globals: _,
296        top_level: _,
297        install_mirrors: _,
298        publish: _,
299        add: _,
300        audit: _,
301        pip: _,
302        cache_keys: _,
303        override_dependencies: _,
304        exclude_dependencies: _,
305        constraint_dependencies: _,
306        build_constraint_dependencies: _,
307        environments,
308        required_environments,
309        minimum_libc_version,
310        conflicts,
311        workspace,
312        sources,
313        dev_dependencies,
314        default_groups,
315        dependency_groups,
316        managed,
317        package,
318        build_backend,
319    } = options;
320    // The `uv.toml` format is not allowed to include any of the following, which are
321    // permitted by the schema since they _can_ be included in `pyproject.toml` files
322    // (and we want to use `deny_unknown_fields`).
323    if conflicts.is_some() {
324        return Err(Error::PyprojectOnlyField(path.to_path_buf(), "conflicts"));
325    }
326    if workspace.is_some() {
327        return Err(Error::PyprojectOnlyField(path.to_path_buf(), "workspace"));
328    }
329    if sources.is_some() {
330        return Err(Error::PyprojectOnlyField(path.to_path_buf(), "sources"));
331    }
332    if dev_dependencies.is_some() {
333        return Err(Error::PyprojectOnlyField(
334            path.to_path_buf(),
335            "dev-dependencies",
336        ));
337    }
338    if default_groups.is_some() {
339        return Err(Error::PyprojectOnlyField(
340            path.to_path_buf(),
341            "default-groups",
342        ));
343    }
344    if dependency_groups.is_some() {
345        return Err(Error::PyprojectOnlyField(
346            path.to_path_buf(),
347            "dependency-groups",
348        ));
349    }
350    if managed.is_some() {
351        return Err(Error::PyprojectOnlyField(path.to_path_buf(), "managed"));
352    }
353    if package.is_some() {
354        return Err(Error::PyprojectOnlyField(path.to_path_buf(), "package"));
355    }
356    if build_backend.is_some() {
357        return Err(Error::PyprojectOnlyField(
358            path.to_path_buf(),
359            "build-backend",
360        ));
361    }
362    if environments.is_some() {
363        return Err(Error::PyprojectOnlyField(
364            path.to_path_buf(),
365            "environments",
366        ));
367    }
368    if required_environments.is_some() {
369        return Err(Error::PyprojectOnlyField(
370            path.to_path_buf(),
371            "required-environments",
372        ));
373    }
374    if minimum_libc_version.is_some() {
375        return Err(Error::PyprojectOnlyField(
376            path.to_path_buf(),
377            "minimum-libc-version",
378        ));
379    }
380    Ok(())
381}
382
383/// Validate that an [`Options`] contains no fields that `uv.toml` would mask
384///
385/// This is essentially the inverse of [`validate_uv_toml`].
386#[allow(deprecated)]
387fn warn_uv_toml_masked_fields(options: &Options) {
388    let Options {
389        globals:
390            GlobalOptions {
391                required_version,
392                system_certs,
393                native_tls,
394                offline,
395                no_cache,
396                cache_dir,
397                preview,
398                python_preference,
399                python_downloads,
400                concurrent_downloads,
401                concurrent_builds,
402                concurrent_installs,
403                allow_insecure_host,
404                http_proxy,
405                https_proxy,
406                no_proxy,
407            },
408        top_level:
409            ResolverInstallerSchema {
410                index,
411                index_url,
412                extra_index_url,
413                no_index,
414                find_links,
415                index_strategy,
416                keyring_provider,
417                resolution,
418                prerelease,
419                prerelease_package,
420                fork_strategy,
421                dependency_metadata,
422                config_settings,
423                config_settings_package,
424                no_build_isolation,
425                no_build_isolation_package,
426                extra_build_dependencies,
427                extra_build_variables,
428                exclude_newer,
429                exclude_newer_package,
430                link_mode,
431                compile_bytecode,
432                no_sources,
433                no_sources_package: _,
434                upgrade,
435                upgrade_package,
436                reinstall,
437                reinstall_package,
438                no_build,
439                no_build_package,
440                no_binary,
441                no_binary_package,
442                torch_backend,
443            },
444        install_mirrors:
445            PythonInstallMirrors {
446                python_install_mirror,
447                pypy_install_mirror,
448                python_downloads_json_url,
449            },
450        publish:
451            PublishOptions {
452                publish_url,
453                trusted_publishing,
454                check_url,
455            },
456        add: AddOptions { add_bounds },
457        audit: _,
458        pip,
459        cache_keys,
460        override_dependencies,
461        exclude_dependencies,
462        constraint_dependencies,
463        build_constraint_dependencies,
464        environments: _,
465        required_environments: _,
466        minimum_libc_version: _,
467        conflicts: _,
468        workspace: _,
469        sources: _,
470        dev_dependencies: _,
471        default_groups: _,
472        dependency_groups: _,
473        managed: _,
474        package: _,
475        build_backend: _,
476    } = options;
477
478    let mut masked_fields = vec![];
479
480    if required_version.is_some() {
481        masked_fields.push("required-version");
482    }
483    if system_certs.is_some() {
484        masked_fields.push("system-certs");
485    }
486    if native_tls.is_some() {
487        masked_fields.push("native-tls");
488    }
489    if offline.is_some() {
490        masked_fields.push("offline");
491    }
492    if no_cache.is_some() {
493        masked_fields.push("no-cache");
494    }
495    if cache_dir.is_some() {
496        masked_fields.push("cache-dir");
497    }
498    match preview {
499        Some(PreviewOption::Preview(_)) => masked_fields.push("preview"),
500        Some(PreviewOption::PreviewFeatures(_)) => masked_fields.push("preview-features"),
501        None => (),
502    }
503    if python_preference.is_some() {
504        masked_fields.push("python-preference");
505    }
506    if python_downloads.is_some() {
507        masked_fields.push("python-downloads");
508    }
509    if concurrent_downloads.is_some() {
510        masked_fields.push("concurrent-downloads");
511    }
512    if concurrent_builds.is_some() {
513        masked_fields.push("concurrent-builds");
514    }
515    if concurrent_installs.is_some() {
516        masked_fields.push("concurrent-installs");
517    }
518    if allow_insecure_host.is_some() {
519        masked_fields.push("allow-insecure-host");
520    }
521    if http_proxy.is_some() {
522        masked_fields.push("http-proxy");
523    }
524    if https_proxy.is_some() {
525        masked_fields.push("https-proxy");
526    }
527    if no_proxy.is_some() {
528        masked_fields.push("no-proxy");
529    }
530    if index.is_some() {
531        masked_fields.push("index");
532    }
533    if index_url.is_some() {
534        masked_fields.push("index-url");
535    }
536    if extra_index_url.is_some() {
537        masked_fields.push("extra-index-url");
538    }
539    if no_index.is_some() {
540        masked_fields.push("no-index");
541    }
542    if find_links.is_some() {
543        masked_fields.push("find-links");
544    }
545    if index_strategy.is_some() {
546        masked_fields.push("index-strategy");
547    }
548    if keyring_provider.is_some() {
549        masked_fields.push("keyring-provider");
550    }
551    if resolution.is_some() {
552        masked_fields.push("resolution");
553    }
554    if prerelease.is_some() {
555        masked_fields.push("prerelease");
556    }
557    if prerelease_package.is_some() {
558        masked_fields.push("prerelease-package");
559    }
560    if fork_strategy.is_some() {
561        masked_fields.push("fork-strategy");
562    }
563    if dependency_metadata.is_some() {
564        masked_fields.push("dependency-metadata");
565    }
566    if config_settings.is_some() {
567        masked_fields.push("config-settings");
568    }
569    if config_settings_package.is_some() {
570        masked_fields.push("config-settings-package");
571    }
572    if no_build_isolation.is_some() {
573        masked_fields.push("no-build-isolation");
574    }
575    if no_build_isolation_package.is_some() {
576        masked_fields.push("no-build-isolation-package");
577    }
578    if extra_build_dependencies.is_some() {
579        masked_fields.push("extra-build-dependencies");
580    }
581    if extra_build_variables.is_some() {
582        masked_fields.push("extra-build-variables");
583    }
584    if exclude_newer.is_some() {
585        masked_fields.push("exclude-newer");
586    }
587    if exclude_newer_package.is_some() {
588        masked_fields.push("exclude-newer-package");
589    }
590    if link_mode.is_some() {
591        masked_fields.push("link-mode");
592    }
593    if compile_bytecode.is_some() {
594        masked_fields.push("compile-bytecode");
595    }
596    if no_sources.is_some() {
597        masked_fields.push("no-sources");
598    }
599    if upgrade.is_some() {
600        masked_fields.push("upgrade");
601    }
602    if upgrade_package.is_some() {
603        masked_fields.push("upgrade-package");
604    }
605    if reinstall.is_some() {
606        masked_fields.push("reinstall");
607    }
608    if reinstall_package.is_some() {
609        masked_fields.push("reinstall-package");
610    }
611    if no_build.is_some() {
612        masked_fields.push("no-build");
613    }
614    if no_build_package.is_some() {
615        masked_fields.push("no-build-package");
616    }
617    if no_binary.is_some() {
618        masked_fields.push("no-binary");
619    }
620    if no_binary_package.is_some() {
621        masked_fields.push("no-binary-package");
622    }
623    if torch_backend.is_some() {
624        masked_fields.push("torch-backend");
625    }
626    if python_install_mirror.is_some() {
627        masked_fields.push("python-install-mirror");
628    }
629    if pypy_install_mirror.is_some() {
630        masked_fields.push("pypy-install-mirror");
631    }
632    if python_downloads_json_url.is_some() {
633        masked_fields.push("python-downloads-json-url");
634    }
635    if publish_url.is_some() {
636        masked_fields.push("publish-url");
637    }
638    if trusted_publishing.is_some() {
639        masked_fields.push("trusted-publishing");
640    }
641    if check_url.is_some() {
642        masked_fields.push("check-url");
643    }
644    if add_bounds.is_some() {
645        masked_fields.push("add-bounds");
646    }
647    if pip.is_some() {
648        masked_fields.push("pip");
649    }
650    if cache_keys.is_some() {
651        masked_fields.push("cache_keys");
652    }
653    if override_dependencies.is_some() {
654        masked_fields.push("override-dependencies");
655    }
656    if exclude_dependencies.is_some() {
657        masked_fields.push("exclude-dependencies");
658    }
659    if constraint_dependencies.is_some() {
660        masked_fields.push("constraint-dependencies");
661    }
662    if build_constraint_dependencies.is_some() {
663        masked_fields.push("build-constraint-dependencies");
664    }
665    if !masked_fields.is_empty() {
666        let field_listing = masked_fields.join("\n- ");
667        warn_user!(
668            "Found both a `uv.toml` file and a `[tool.uv]` section in an adjacent `pyproject.toml`. The following fields from `[tool.uv]` will be ignored in favor of the `uv.toml` file:\n- {}",
669            field_listing,
670        );
671    }
672}
673
674#[derive(thiserror::Error, Debug)]
675pub enum Error {
676    #[error(transparent)]
677    Io(#[from] std::io::Error),
678
679    #[error(transparent)]
680    Index(#[from] uv_distribution_types::IndexUrlError),
681
682    #[error("Failed to parse: `{}`", _0.user_display())]
683    PyprojectToml(PathBuf, #[source] Box<toml::de::Error>),
684
685    #[error("Failed to parse: `{}`", _0.user_display())]
686    UvToml(PathBuf, #[source] Box<toml::de::Error>),
687
688    #[error("Failed to parse: `{}`. The `{}` field is not allowed in a `uv.toml` file. `{}` is only applicable in the context of a project, and should be placed in a `pyproject.toml` file instead.", _0.user_display(), _1, _1
689    )]
690    PyprojectOnlyField(PathBuf, &'static str),
691
692    #[error(
693        "Required uv version `{required_version}` does not match the running version `{package_version}`"
694    )]
695    RequiredVersion {
696        required_version: RequiredVersion,
697        package_version: Version,
698    },
699
700    #[error(transparent)]
701    InvalidEnvironmentVariable(#[from] InvalidEnvironmentVariable),
702}
703
704#[derive(Copy, Clone, Debug)]
705pub struct Concurrency {
706    pub downloads: Option<NonZeroUsize>,
707    pub builds: Option<NonZeroUsize>,
708    pub installs: Option<NonZeroUsize>,
709    pub cache_reads: Option<NonZeroUsize>,
710}
711
712/// A boolean flag parsed from an environment variable.
713///
714/// Stores both the value and the environment variable name for use in error messages.
715#[derive(Debug, Clone, Copy)]
716pub struct EnvFlag {
717    pub value: Option<bool>,
718    pub env_var: &'static str,
719}
720
721impl EnvFlag {
722    /// Create a new [`EnvFlag`] by parsing the given environment variable.
723    fn new(env_var: &'static str) -> Result<Self, Error> {
724        Ok(Self {
725            value: parse_boolish_environment_variable(env_var)?,
726            env_var,
727        })
728    }
729}
730
731/// Options loaded from environment variables.
732///
733/// This is currently a subset of all respected environment variables, most are parsed via Clap at
734/// the CLI level, however there are limited semantics in that context.
735#[derive(Debug, Clone)]
736pub struct EnvironmentOptions {
737    pub ruff_path: Option<PathBuf>,
738    pub ty_path: Option<PathBuf>,
739    pub skip_wheel_filename_check: Option<bool>,
740    pub require_metadata_range_requests: Option<bool>,
741    pub hide_build_output: Option<bool>,
742    pub python_install_bin: Option<bool>,
743    pub python_install_registry: Option<bool>,
744    pub python_no_registry: EnvFlag,
745    pub install_mirrors: PythonInstallMirrors,
746    pub log_context: Option<bool>,
747    pub lfs: Option<bool>,
748    pub cuda_driver_version: Option<Version>,
749    pub amd_gpu_architecture: Option<AmdGpuArchitecture>,
750    pub http_connect_timeout: Duration,
751    pub http_read_timeout: Duration,
752    /// There's no upload timeout in reqwest, instead we have to use a read timeout as upload
753    /// timeout.
754    pub http_read_timeout_upload: Duration,
755    pub http_retries: u32,
756    pub concurrency: Concurrency,
757    #[cfg(feature = "tracing-durations-export")]
758    pub tracing_durations_file: Option<PathBuf>,
759    pub frozen: EnvFlag,
760    pub locked: EnvFlag,
761    pub offline: EnvFlag,
762    pub no_sync: EnvFlag,
763    pub managed_python: EnvFlag,
764    pub no_managed_python: EnvFlag,
765    pub native_tls: EnvFlag,
766    pub system_certs: EnvFlag,
767    pub preview: EnvFlag,
768    pub isolated: EnvFlag,
769    pub no_progress: EnvFlag,
770    pub no_installer_metadata: EnvFlag,
771    pub dev: EnvFlag,
772    pub no_dev: EnvFlag,
773    pub show_resolution: EnvFlag,
774    pub no_editable: EnvFlag,
775    pub no_install_project: EnvFlag,
776    pub no_install_workspace: EnvFlag,
777    pub no_install_local: EnvFlag,
778    pub only_install_project: EnvFlag,
779    pub only_install_workspace: EnvFlag,
780    pub only_install_local: EnvFlag,
781    pub no_env_file: EnvFlag,
782    pub no_group: Option<Vec<GroupName>>,
783    pub no_binary_package: Option<Vec<PackageName>>,
784    pub no_build_package: Option<Vec<PackageName>>,
785    pub no_sources_package: Option<Vec<PackageName>>,
786    pub venv_seed: EnvFlag,
787    pub venv_clear: EnvFlag,
788    pub venv_relocatable: EnvFlag,
789    pub init_bare: EnvFlag,
790    pub malware_check: EnvFlag,
791    pub malware_check_url: Option<DisplaySafeUrl>,
792    #[cfg(unix)]
793    pub run_rlimit_nofile: Option<u32>,
794}
795
796impl EnvironmentOptions {
797    /// Create a new [`EnvironmentOptions`] from environment variables.
798    pub fn new() -> Result<Self, Error> {
799        // Timeout options, matching https://doc.rust-lang.org/nightly/cargo/reference/config.html#httptimeout
800        // `UV_REQUEST_TIMEOUT` is provided for backwards compatibility with v0.1.6
801        let http_read_timeout = parse_integer_environment_variable(
802            EnvVars::UV_HTTP_TIMEOUT,
803            Some("value should be an integer number of seconds"),
804        )?
805        .or(parse_integer_environment_variable(
806            EnvVars::UV_REQUEST_TIMEOUT,
807            Some("value should be an integer number of seconds"),
808        )?)
809        .or(parse_integer_environment_variable(
810            EnvVars::HTTP_TIMEOUT,
811            Some("value should be an integer number of seconds"),
812        )?)
813        .map(Duration::from_secs);
814
815        // Ignore the deprecated `UV_NATIVE_TLS` variable when its replacement is set.
816        let system_certs = EnvFlag::new(EnvVars::UV_SYSTEM_CERTS)?;
817        let native_tls = if system_certs.value.is_some() {
818            EnvFlag {
819                value: None,
820                env_var: EnvVars::UV_NATIVE_TLS,
821            }
822        } else {
823            EnvFlag::new(EnvVars::UV_NATIVE_TLS)?
824        };
825
826        Ok(Self {
827            ruff_path: parse_path_environment_variable(EnvVars::RUFF),
828            ty_path: parse_path_environment_variable(EnvVars::TY),
829            skip_wheel_filename_check: parse_boolish_environment_variable(
830                EnvVars::UV_SKIP_WHEEL_FILENAME_CHECK,
831            )?,
832            require_metadata_range_requests: parse_boolish_environment_variable(
833                EnvVars::UV_REQUIRE_METADATA_RANGE_REQUESTS,
834            )?,
835            hide_build_output: parse_boolish_environment_variable(EnvVars::UV_HIDE_BUILD_OUTPUT)?,
836            python_install_bin: parse_boolish_environment_variable(EnvVars::UV_PYTHON_INSTALL_BIN)?,
837            python_install_registry: parse_boolish_environment_variable(
838                EnvVars::UV_PYTHON_INSTALL_REGISTRY,
839            )?,
840            python_no_registry: EnvFlag::new(EnvVars::UV_PYTHON_NO_REGISTRY)?,
841            concurrency: Concurrency {
842                downloads: parse_integer_environment_variable(
843                    EnvVars::UV_CONCURRENT_DOWNLOADS,
844                    None,
845                )?,
846                builds: parse_integer_environment_variable(EnvVars::UV_CONCURRENT_BUILDS, None)?,
847                installs: parse_integer_environment_variable(
848                    EnvVars::UV_CONCURRENT_INSTALLS,
849                    None,
850                )?,
851                cache_reads: parse_integer_environment_variable(
852                    EnvVars::UV_CONCURRENT_CACHE_READS,
853                    None,
854                )?,
855            },
856            install_mirrors: PythonInstallMirrors {
857                python_install_mirror: parse_string_environment_variable(
858                    EnvVars::UV_PYTHON_INSTALL_MIRROR,
859                )?,
860                pypy_install_mirror: parse_string_environment_variable(
861                    EnvVars::UV_PYPY_INSTALL_MIRROR,
862                )?,
863                python_downloads_json_url: parse_string_environment_variable(
864                    EnvVars::UV_PYTHON_DOWNLOADS_JSON_URL,
865                )?,
866            },
867            log_context: parse_boolish_environment_variable(EnvVars::UV_LOG_CONTEXT)?,
868            lfs: parse_boolish_environment_variable(EnvVars::UV_GIT_LFS)?,
869            cuda_driver_version: parse_typed_environment_variable(
870                EnvVars::UV_CUDA_DRIVER_VERSION,
871                None,
872            )?,
873            amd_gpu_architecture: parse_typed_environment_variable(
874                EnvVars::UV_AMD_GPU_ARCHITECTURE,
875                None,
876            )?,
877            http_read_timeout_upload: parse_integer_environment_variable(
878                EnvVars::UV_UPLOAD_HTTP_TIMEOUT,
879                Some("value should be an integer number of seconds"),
880            )?
881            .map(Duration::from_secs)
882            .or(http_read_timeout)
883            .unwrap_or(DEFAULT_READ_TIMEOUT_UPLOAD),
884            http_read_timeout: http_read_timeout.unwrap_or(DEFAULT_READ_TIMEOUT),
885            http_connect_timeout: parse_integer_environment_variable(
886                EnvVars::UV_HTTP_CONNECT_TIMEOUT,
887                Some("value should be an integer number of seconds"),
888            )?
889            .map(Duration::from_secs)
890            .unwrap_or(DEFAULT_CONNECT_TIMEOUT),
891            http_retries: parse_integer_environment_variable(EnvVars::UV_HTTP_RETRIES, None)?
892                .unwrap_or(uv_client::DEFAULT_RETRIES),
893            #[cfg(feature = "tracing-durations-export")]
894            tracing_durations_file: parse_path_environment_variable(
895                EnvVars::TRACING_DURATIONS_FILE,
896            ),
897            frozen: EnvFlag::new(EnvVars::UV_FROZEN)?,
898            locked: EnvFlag::new(EnvVars::UV_LOCKED)?,
899            offline: EnvFlag::new(EnvVars::UV_OFFLINE)?,
900            no_sync: EnvFlag::new(EnvVars::UV_NO_SYNC)?,
901            managed_python: EnvFlag::new(EnvVars::UV_MANAGED_PYTHON)?,
902            no_managed_python: EnvFlag::new(EnvVars::UV_NO_MANAGED_PYTHON)?,
903            native_tls,
904            system_certs,
905            preview: EnvFlag::new(EnvVars::UV_PREVIEW)?,
906            isolated: EnvFlag::new(EnvVars::UV_ISOLATED)?,
907            no_progress: EnvFlag::new(EnvVars::UV_NO_PROGRESS)?,
908            no_installer_metadata: EnvFlag::new(EnvVars::UV_NO_INSTALLER_METADATA)?,
909            dev: EnvFlag::new(EnvVars::UV_DEV)?,
910            no_dev: EnvFlag::new(EnvVars::UV_NO_DEV)?,
911            show_resolution: EnvFlag::new(EnvVars::UV_SHOW_RESOLUTION)?,
912            no_editable: EnvFlag::new(EnvVars::UV_NO_EDITABLE)?,
913            no_install_project: EnvFlag::new(EnvVars::UV_NO_INSTALL_PROJECT)?,
914            no_install_workspace: EnvFlag::new(EnvVars::UV_NO_INSTALL_WORKSPACE)?,
915            no_install_local: EnvFlag::new(EnvVars::UV_NO_INSTALL_LOCAL)?,
916            only_install_project: EnvFlag::new(EnvVars::UV_ONLY_INSTALL_PROJECT)?,
917            only_install_workspace: EnvFlag::new(EnvVars::UV_ONLY_INSTALL_WORKSPACE)?,
918            only_install_local: EnvFlag::new(EnvVars::UV_ONLY_INSTALL_LOCAL)?,
919            no_env_file: EnvFlag::new(EnvVars::UV_NO_ENV_FILE)?,
920            no_group: parse_name_list_environment_variable(EnvVars::UV_NO_GROUP)?,
921            no_binary_package: parse_name_list_environment_variable(EnvVars::UV_NO_BINARY_PACKAGE)?,
922            no_build_package: parse_name_list_environment_variable(EnvVars::UV_NO_BUILD_PACKAGE)?,
923            no_sources_package: parse_name_list_environment_variable(
924                EnvVars::UV_NO_SOURCES_PACKAGE,
925            )?,
926            venv_seed: EnvFlag::new(EnvVars::UV_VENV_SEED)?,
927            venv_clear: EnvFlag::new(EnvVars::UV_VENV_CLEAR)?,
928            venv_relocatable: EnvFlag::new(EnvVars::UV_VENV_RELOCATABLE)?,
929            init_bare: EnvFlag::new(EnvVars::UV_INIT_BARE)?,
930            malware_check: EnvFlag::new(EnvVars::UV_MALWARE_CHECK)?,
931            malware_check_url: parse_string_environment_variable(EnvVars::UV_MALWARE_CHECK_URL)?
932                .map(|value| {
933                    value.parse::<DisplaySafeUrl>().map_err(|err| {
934                        Error::InvalidEnvironmentVariable(InvalidEnvironmentVariable {
935                            name: EnvVars::UV_MALWARE_CHECK_URL.to_string(),
936                            value,
937                            err: err.to_string(),
938                        })
939                    })
940                })
941                .transpose()?,
942            #[cfg(unix)]
943            run_rlimit_nofile: parse_integer_environment_variable(
944                EnvVars::UV_RUN_RLIMIT_NOFILE,
945                None,
946            )?,
947        })
948    }
949}
950
951/// Parse a string environment variable.
952fn parse_string_environment_variable(name: &'static str) -> Result<Option<String>, Error> {
953    match std::env::var(name) {
954        Ok(v) => {
955            if v.is_empty() {
956                Ok(None)
957            } else {
958                Ok(Some(v))
959            }
960        }
961        Err(e) => match e {
962            std::env::VarError::NotPresent => Ok(None),
963            std::env::VarError::NotUnicode(err) => Err(Error::InvalidEnvironmentVariable(
964                InvalidEnvironmentVariable {
965                    name: name.to_string(),
966                    value: err.to_string_lossy().to_string(),
967                    err: "expected a valid UTF-8 string".to_string(),
968                },
969            )),
970        },
971    }
972}
973
974/// Parse an environment variable containing a whitespace-delimited list of names.
975fn parse_name_list_environment_variable<T>(name: &'static str) -> Result<Option<Vec<T>>, Error>
976where
977    T: FromStr,
978    <T as FromStr>::Err: std::fmt::Display,
979{
980    let Some(value) = parse_string_environment_variable(name)? else {
981        return Ok(None);
982    };
983
984    let names = value
985        .split_whitespace()
986        .map(|entry| {
987            entry.parse::<T>().map_err(|err| {
988                Error::InvalidEnvironmentVariable(InvalidEnvironmentVariable {
989                    name: name.to_string(),
990                    value: value.clone(),
991                    err: err.to_string(),
992                })
993            })
994        })
995        .collect::<Result<Vec<_>, _>>()?;
996
997    if names.is_empty() {
998        Ok(None)
999    } else {
1000        Ok(Some(names))
1001    }
1002}
1003
1004fn parse_typed_environment_variable<T>(
1005    name: &'static str,
1006    help: Option<&str>,
1007) -> Result<Option<T>, Error>
1008where
1009    T: std::str::FromStr,
1010    <T as std::str::FromStr>::Err: std::fmt::Display,
1011{
1012    let value = match std::env::var(name) {
1013        Ok(v) => v,
1014        Err(e) => {
1015            return match e {
1016                std::env::VarError::NotPresent => Ok(None),
1017                std::env::VarError::NotUnicode(err) => Err(Error::InvalidEnvironmentVariable(
1018                    InvalidEnvironmentVariable {
1019                        name: name.to_string(),
1020                        value: err.to_string_lossy().to_string(),
1021                        err: "expected a valid UTF-8 string".to_string(),
1022                    },
1023                )),
1024            };
1025        }
1026    };
1027    if value.is_empty() {
1028        return Ok(None);
1029    }
1030
1031    match value.parse::<T>() {
1032        Ok(v) => Ok(Some(v)),
1033        Err(err) => Err(Error::InvalidEnvironmentVariable(
1034            InvalidEnvironmentVariable {
1035                name: name.to_string(),
1036                value,
1037                err: if let Some(help) = help {
1038                    format!("{err}; {help}")
1039                } else {
1040                    err.to_string()
1041                },
1042            },
1043        )),
1044    }
1045}
1046
1047fn parse_integer_environment_variable<T>(
1048    name: &'static str,
1049    help: Option<&str>,
1050) -> Result<Option<T>, Error>
1051where
1052    T: std::str::FromStr + Copy,
1053    <T as std::str::FromStr>::Err: std::fmt::Display,
1054{
1055    let value = match std::env::var(name) {
1056        Ok(v) => v,
1057        Err(e) => {
1058            return match e {
1059                std::env::VarError::NotPresent => Ok(None),
1060                std::env::VarError::NotUnicode(err) => Err(Error::InvalidEnvironmentVariable(
1061                    InvalidEnvironmentVariable {
1062                        name: name.to_string(),
1063                        value: err.to_string_lossy().to_string(),
1064                        err: "expected a valid UTF-8 string".to_string(),
1065                    },
1066                )),
1067            };
1068        }
1069    };
1070    if value.is_empty() {
1071        return Ok(None);
1072    }
1073
1074    match value.parse::<T>() {
1075        Ok(v) => Ok(Some(v)),
1076        Err(err) => Err(Error::InvalidEnvironmentVariable(
1077            InvalidEnvironmentVariable {
1078                name: name.to_string(),
1079                value,
1080                err: if let Some(help) = help {
1081                    format!("{err}; {help}")
1082                } else {
1083                    err.to_string()
1084                },
1085            },
1086        )),
1087    }
1088}
1089
1090/// Parse a path environment variable.
1091fn parse_path_environment_variable(name: &'static str) -> Option<PathBuf> {
1092    let value = std::env::var_os(name)?;
1093
1094    if value.is_empty() {
1095        return None;
1096    }
1097
1098    Some(PathBuf::from(value))
1099}
1100
1101/// Populate the [`EnvironmentFlags`] from the given [`EnvironmentOptions`].
1102impl From<&EnvironmentOptions> for EnvironmentFlags {
1103    fn from(options: &EnvironmentOptions) -> Self {
1104        let mut flags = Self::empty();
1105        if options.skip_wheel_filename_check == Some(true) {
1106            flags.insert(Self::SKIP_WHEEL_FILENAME_CHECK);
1107        }
1108        if options.hide_build_output == Some(true) {
1109            flags.insert(Self::HIDE_BUILD_OUTPUT);
1110        }
1111        flags
1112    }
1113}
uv_settings/lib.rs

uv_settings/
lib.rs
