From 870896b87c0e722253dc654a33c24ba2e4adf79a Mon Sep 17 00:00:00 2001 From: j178 <10510431+j178@users.noreply.github.com> Date: Wed, 23 Oct 2024 17:00:10 +0800 Subject: [PATCH] Generate environment variables doc --- Cargo.lock | 3 + Cargo.toml | 2 +- crates/uv-dev/src/generate_cli_reference.rs | 1 - .../uv-dev/src/generate_env_vars_reference.rs | 85 ++++++ .../src/generate_env_vars_reference/tests.rs | 19 ++ crates/uv-dev/src/generate_json_schema.rs | 1 - .../uv-dev/src/generate_options_reference.rs | 1 - crates/uv-dev/src/main.rs | 5 + crates/uv-macros/src/lib.rs | 55 +++- crates/uv-static/Cargo.toml | 1 + crates/uv-static/src/env_vars.rs | 3 + docs/configuration/environment.md | 268 ++++++++---------- 12 files changed, 291 insertions(+), 153 deletions(-) create mode 100644 crates/uv-dev/src/generate_env_vars_reference.rs create mode 100644 crates/uv-dev/src/generate_env_vars_reference/tests.rs diff --git a/Cargo.lock b/Cargo.lock index 2126000c4738..267895cc8ac4 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -5221,6 +5221,9 @@ dependencies = [ [[package]] name = "uv-static" version = "0.0.1" +dependencies = [ + "uv-macros", +] [[package]] name = "uv-tool" diff --git a/Cargo.toml b/Cargo.toml index 99b0dcf79c8f..fc2ecdc7e682 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -147,7 +147,7 @@ serde_json = { version = "1.0.128" } sha2 = { version = "0.10.8" } smallvec = { version = "1.13.2" } spdx = { version = "0.10.6" } -syn = { version = "2.0.77" } +syn = { version = "2.0.77", features = ["full"] } sys-info = { version = "0.9.1" } target-lexicon = { version = "0.12.16" } tempfile = { version = "3.12.0" } diff --git a/crates/uv-dev/src/generate_cli_reference.rs b/crates/uv-dev/src/generate_cli_reference.rs index f036053cecf5..854e5c5faafa 100644 --- a/crates/uv-dev/src/generate_cli_reference.rs +++ b/crates/uv-dev/src/generate_cli_reference.rs @@ -31,7 +31,6 @@ const SHOW_HIDDEN_COMMANDS: &[&str] = &["generate-shell-completion"]; #[derive(clap::Args)] pub(crate) struct Args { - /// Write the generated output to stdout (rather than to `settings.md`). #[arg(long, default_value_t, value_enum)] pub(crate) mode: Mode, } diff --git a/crates/uv-dev/src/generate_env_vars_reference.rs b/crates/uv-dev/src/generate_env_vars_reference.rs new file mode 100644 index 000000000000..510821dda0fa --- /dev/null +++ b/crates/uv-dev/src/generate_env_vars_reference.rs @@ -0,0 +1,85 @@ +//! Generate the environment variables reference from `uv_static::EnvVars`. + +use anyhow::bail; +use pretty_assertions::StrComparison; +use std::path::PathBuf; + +use uv_static::EnvVars; + +use crate::generate_all::Mode; +use crate::ROOT_DIR; + +#[derive(clap::Args)] +pub(crate) struct Args { + #[arg(long, default_value_t, value_enum)] + mode: Mode, +} + +pub(crate) fn main(args: &Args) -> anyhow::Result<()> { + let reference_string = generate(); + let filename = "environment.md"; + let reference_path = PathBuf::from(ROOT_DIR) + .join("docs") + .join("configuration") + .join(filename); + + match args.mode { + Mode::DryRun => { + anstream::println!("{reference_string}"); + } + Mode::Check => match fs_err::read_to_string(reference_path) { + Ok(current) => { + if current == reference_string { + anstream::println!("Up-to-date: {filename}"); + } else { + let comparison = StrComparison::new(¤t, &reference_string); + bail!("{filename} changed, please run `cargo dev generate-env-vars-reference`:\n{comparison}"); + } + } + Err(err) if err.kind() == std::io::ErrorKind::NotFound => { + bail!("{filename} not found, please run `cargo dev generate-env-vars-reference`"); + } + Err(err) => { + bail!( + "{filename} changed, please run `cargo dev generate-env-vars-reference`:\n{err}" + ); + } + }, + Mode::Write => match fs_err::read_to_string(&reference_path) { + Ok(current) => { + if current == reference_string { + anstream::println!("Up-to-date: {filename}"); + } else { + anstream::println!("Updating: {filename}"); + fs_err::write(reference_path, reference_string.as_bytes())?; + } + } + Err(err) if err.kind() == std::io::ErrorKind::NotFound => { + anstream::println!("Updating: {filename}"); + fs_err::write(reference_path, reference_string.as_bytes())?; + } + Err(err) => { + bail!("{filename} changed, please run `cargo dev generate-env-vars-reference`:\n{err}"); + } + }, + } + + Ok(()) +} + +fn generate() -> String { + let mut output = String::new(); + + output.push_str("# Environment variables\n\n"); + output + .push_str("uv accepts the following command-line arguments as environment variables:\n\n"); + + EnvVars::constants().iter().for_each(|(var, doc)| { + output.push_str(&format!("- `{}`: {}\n", var, doc)); + }); + + output +} + +#[cfg(test)] +mod tests; diff --git a/crates/uv-dev/src/generate_env_vars_reference/tests.rs b/crates/uv-dev/src/generate_env_vars_reference/tests.rs new file mode 100644 index 000000000000..896fb0ecdd4e --- /dev/null +++ b/crates/uv-dev/src/generate_env_vars_reference/tests.rs @@ -0,0 +1,19 @@ +use std::env; + +use anyhow::Result; + +use uv_static::EnvVars; + +use crate::generate_all::Mode; + +use super::{main, Args}; + +#[test] +fn test_generate_env_vars_reference() -> Result<()> { + let mode = if env::var(EnvVars::UV_UPDATE_SCHEMA).as_deref() == Ok("1") { + Mode::Write + } else { + Mode::Check + }; + main(&Args { mode }) +} diff --git a/crates/uv-dev/src/generate_json_schema.rs b/crates/uv-dev/src/generate_json_schema.rs index 2fcf5d5d8cd2..5e7ccfdf8ef8 100644 --- a/crates/uv-dev/src/generate_json_schema.rs +++ b/crates/uv-dev/src/generate_json_schema.rs @@ -27,7 +27,6 @@ struct CombinedOptions { #[derive(clap::Args)] pub(crate) struct Args { - /// Write the generated output to stdout (rather than to `uv.schema.json`). #[arg(long, default_value_t, value_enum)] pub(crate) mode: Mode, } diff --git a/crates/uv-dev/src/generate_options_reference.rs b/crates/uv-dev/src/generate_options_reference.rs index 0e066d9aff9a..535243997cbc 100644 --- a/crates/uv-dev/src/generate_options_reference.rs +++ b/crates/uv-dev/src/generate_options_reference.rs @@ -34,7 +34,6 @@ struct CombinedOptions { #[derive(clap::Args)] pub(crate) struct Args { - /// Write the generated output to stdout (rather than to `settings.md`). #[arg(long, default_value_t, value_enum)] pub(crate) mode: Mode, } diff --git a/crates/uv-dev/src/main.rs b/crates/uv-dev/src/main.rs index b296edb11f89..a46626d42f39 100644 --- a/crates/uv-dev/src/main.rs +++ b/crates/uv-dev/src/main.rs @@ -20,6 +20,7 @@ use crate::clear_compile::ClearCompileArgs; use crate::compile::CompileArgs; use crate::generate_all::Args as GenerateAllArgs; use crate::generate_cli_reference::Args as GenerateCliReferenceArgs; +use crate::generate_env_vars_reference::Args as GenerateEnvVarsReferenceArgs; use crate::generate_json_schema::Args as GenerateJsonSchemaArgs; use crate::generate_options_reference::Args as GenerateOptionsReferenceArgs; #[cfg(feature = "render")] @@ -31,6 +32,7 @@ mod clear_compile; mod compile; mod generate_all; mod generate_cli_reference; +mod generate_env_vars_reference; mod generate_json_schema; mod generate_options_reference; mod render_benchmarks; @@ -54,6 +56,8 @@ enum Cli { GenerateOptionsReference(GenerateOptionsReferenceArgs), /// Generate the CLI reference for the documentation. GenerateCliReference(GenerateCliReferenceArgs), + /// Generate the environment variables reference for the documentation. + GenerateEnvVarsReference(GenerateEnvVarsReferenceArgs), #[cfg(feature = "render")] /// Render the benchmarks. RenderBenchmarks(RenderBenchmarksArgs), @@ -70,6 +74,7 @@ async fn run() -> Result<()> { Cli::GenerateJSONSchema(args) => generate_json_schema::main(&args)?, Cli::GenerateOptionsReference(args) => generate_options_reference::main(&args)?, Cli::GenerateCliReference(args) => generate_cli_reference::main(&args)?, + Cli::GenerateEnvVarsReference(args) => generate_env_vars_reference::main(&args)?, #[cfg(feature = "render")] Cli::RenderBenchmarks(args) => render_benchmarks::render_benchmarks(&args)?, } diff --git a/crates/uv-macros/src/lib.rs b/crates/uv-macros/src/lib.rs index d9db61f3daa0..07530a0b1995 100644 --- a/crates/uv-macros/src/lib.rs +++ b/crates/uv-macros/src/lib.rs @@ -2,7 +2,7 @@ mod options_metadata; use proc_macro::TokenStream; use quote::quote; -use syn::{parse_macro_input, DeriveInput}; +use syn::{parse_macro_input, Attribute, DeriveInput, ImplItem, ItemImpl}; #[proc_macro_derive(OptionsMetadata, attributes(option, doc, option_group))] pub fn derive_options_metadata(input: TokenStream) -> TokenStream { @@ -49,3 +49,56 @@ fn impl_combine(ast: &DeriveInput) -> TokenStream { }; gen.into() } + +fn get_doc_comment(attr: &Attribute) -> Option { + if attr.path().is_ident("doc") { + if let syn::Meta::NameValue(meta) = &attr.meta { + if let syn::Expr::Lit(expr) = &meta.value { + if let syn::Lit::Str(str) = &expr.lit { + return Some(str.value().trim().to_string()); + } + } + } + } + None +} + +#[proc_macro_attribute] +pub fn collect_constants(_attr: TokenStream, input: TokenStream) -> TokenStream { + let ast = parse_macro_input!(input as ItemImpl); + + let constants: Vec<_> = ast + .items + .iter() + .filter_map(|item| { + match item { + ImplItem::Const(item) => { + let name = item.ident.to_string(); + let doc = item.attrs.iter().find_map(get_doc_comment).expect("Missing doc comment"); + Some((name, doc)) + } + _ => None, + } + }) + .collect(); + + let struct_name = &ast.self_ty; + let pairs = constants.iter().map(|(name, doc)| { + quote! { + (#name, #doc) + } + }); + + let expanded = quote! { + #ast + + impl #struct_name { + /// Returns a list of pairs of constants and their documentation defined in this impl block. + pub fn constants<'a>() -> &'a [(&'static str, &'static str)] { + &[#(#pairs),*] + } + } + }; + + expanded.into() +} diff --git a/crates/uv-static/Cargo.toml b/crates/uv-static/Cargo.toml index b054021e6759..77d1fe54b2c1 100644 --- a/crates/uv-static/Cargo.toml +++ b/crates/uv-static/Cargo.toml @@ -16,3 +16,4 @@ doctest = false workspace = true [dependencies] +uv-macros = { workspace = true } diff --git a/crates/uv-static/src/env_vars.rs b/crates/uv-static/src/env_vars.rs index fa5eb8de45e6..0ff447dde201 100644 --- a/crates/uv-static/src/env_vars.rs +++ b/crates/uv-static/src/env_vars.rs @@ -1,6 +1,9 @@ +use uv_macros::collect_constants; + /// Declares all environment variable used throughout `uv` and its crates. pub struct EnvVars; +#[collect_constants] impl EnvVars { /// Equivalent to the `--default-index` argument. Base index URL for searching packages. pub const UV_DEFAULT_INDEX: &'static str = "UV_DEFAULT_INDEX"; diff --git a/docs/configuration/environment.md b/docs/configuration/environment.md index 0806d54807eb..bbabaf88c83c 100644 --- a/docs/configuration/environment.md +++ b/docs/configuration/environment.md @@ -2,153 +2,125 @@ uv accepts the following command-line arguments as environment variables: -- `UV_INDEX`: Equivalent to the `--index` command-line argument. If set, uv will use this - space-separated list of URLs as additional indexes when searching for packages. -- `UV_DEFAULT_INDEX`: Equivalent to the `--default-index` command-line argument. If set, uv will use - this URL as the default index when searching for packages. -- `UV_INDEX_URL`: Equivalent to the `--index-url` command-line argument. If set, uv will use this - URL as the default index when searching for packages. (Deprecated: use `UV_DEFAULT_INDEX` - instead.) -- `UV_EXTRA_INDEX_URL`: Equivalent to the `--extra-index-url` command-line argument. If set, uv will - use this space-separated list of URLs as additional indexes when searching for packages. - (Deprecated: use `UV_INDEX` instead.) -- `UV_FIND_LINKS`: Equivalent to the `--find-links` command-line argument. If set, uv will use this - comma-separated list of additional locations to search for packages. -- `UV_CACHE_DIR`: Equivalent to the `--cache-dir` command-line argument. If set, uv will use this - directory for caching instead of the default cache directory. -- `UV_NO_CACHE`: Equivalent to the `--no-cache` command-line argument. If set, uv will not use the - cache for any operations. -- `UV_RESOLUTION`: Equivalent to the `--resolution` command-line argument. For example, if set to - `lowest-direct`, uv will install the lowest compatible versions of all direct dependencies. -- `UV_PRERELEASE`: Equivalent to the `--prerelease` command-line argument. For example, if set to - `allow`, uv will allow pre-release versions for all dependencies. -- `UV_SYSTEM_PYTHON`: Equivalent to the `--system` command-line argument. If set to `true`, uv will - use the first Python interpreter found in the system `PATH`. WARNING: `UV_SYSTEM_PYTHON=true` is - intended for use in continuous integration (CI) or containerized environments and should be used - with caution, as modifying the system Python can lead to unexpected behavior. -- `UV_PYTHON`: Equivalent to the `--python` command-line argument. If set to a path, uv will use - this Python interpreter for all operations. -- `UV_BREAK_SYSTEM_PACKAGES`: Equivalent to the `--break-system-packages` command-line argument. If - set to `true`, uv will allow the installation of packages that conflict with system-installed - packages. WARNING: `UV_BREAK_SYSTEM_PACKAGES=true` is intended for use in continuous integration - (CI) or containerized environments and should be used with caution, as modifying the system Python - can lead to unexpected behavior. -- `UV_NATIVE_TLS`: Equivalent to the `--native-tls` command-line argument. If set to `true`, uv will - use the system's trust store instead of the bundled `webpki-roots` crate. -- `UV_INDEX_STRATEGY`: Equivalent to the `--index-strategy` command-line argument. For example, if - set to `unsafe-any-match`, uv will consider versions of a given package available across all index - URLs, rather than limiting its search to the first index URL that contains the package. -- `UV_REQUIRE_HASHES`: Equivalent to the `--require-hashes` command-line argument. If set to `true`, - uv will require that all dependencies have a hash specified in the requirements file. -- `UV_CONSTRAINT`: Equivalent to the `--constraint` command-line argument. If set, uv will use this - file as the constraints file. Uses space-separated list of files. -- `UV_BUILD_CONSTRAINT`: Equivalent to the `--build-constraint` command-line argument. If set, uv - will use this file as constraints for any source distribution builds. Uses space-separated list of - files. -- `UV_OVERRIDE`: Equivalent to the `--override` command-line argument. If set, uv will use this file - as the overrides file. Uses space-separated list of files. -- `UV_LINK_MODE`: Equivalent to the `--link-mode` command-line argument. If set, uv will use this as - a link mode. -- `UV_NO_BUILD_ISOLATION`: Equivalent to the `--no-build-isolation` command-line argument. If set, - uv will skip isolation when building source distributions. -- `UV_CUSTOM_COMPILE_COMMAND`: Equivalent to the `--custom-compile-command` command-line argument. - Used to override uv in the output header of the `requirements.txt` files generated by - `uv pip compile`. Intended for use-cases in which `uv pip compile` is called from within a wrapper - script, to include the name of the wrapper script in the output file. -- `UV_KEYRING_PROVIDER`: Equivalent to the `--keyring-provider` command-line argument. If set, uv - will use this value as the keyring provider. -- `UV_CONFIG_FILE`: Equivalent to the `--config-file` command-line argument. Expects a path to a - local `uv.toml` file to use as the configuration file. -- `UV_NO_CONFIG`: Equivalent to the `--no-config` command-line argument. If set, uv will not read - any configuration files from the current directory, parent directories, or user configuration - directories. -- `UV_EXCLUDE_NEWER`: Equivalent to the `--exclude-newer` command-line argument. If set, uv will - exclude distributions published after the specified date. -- `UV_PYTHON_PREFERENCE`: Equivalent to the `--python-preference` command-line argument. Whether uv - should prefer system or managed Python versions. -- `UV_PYTHON_DOWNLOADS`: Equivalent to the - [`python-downloads`](../reference/settings.md#python-downloads) setting and, when disabled, the - `--no-python-downloads` option. Whether uv should allow Python downloads. -- `UV_COMPILE_BYTECODE`: Equivalent to the `--compile-bytecode` command-line argument. If set, uv - will compile Python source files to bytecode after installation. -- `UV_PUBLISH_URL`: Equivalent to the `--publish-url` command-line argument. The URL of the upload - endpoint of the index to use with `uv publish`. -- `UV_PUBLISH_TOKEN`: Equivalent to the `--token` command-line argument in `uv publish`. If set, uv - will use this token (with the username `__token__`) for publishing. -- `UV_PUBLISH_USERNAME`: Equivalent to the `--username` command-line argument in `uv publish`. If - set, uv will use this username for publishing. -- `UV_PUBLISH_PASSWORD`: Equivalent to the `--password` command-line argument in `uv publish`. If - set, uv will use this password for publishing. -- `UV_NO_SYNC`: Equivalent to the `--no-sync` command-line argument. If set, uv will skip updating - the environment. -- `UV_LOCKED`: Equivalent to the `--locked` command-line argument. If set, uv will assert that the - `uv.lock` remains unchanged. -- `UV_FROZEN`: Equivalent to the `--frozen` command-line argument. If set, uv will run without - updating the `uv.lock` file. - -In each case, the corresponding command-line argument takes precedence over an environment variable. - -In addition, uv respects the following environment variables: - -- `UV_CONCURRENT_DOWNLOADS`: Sets the maximum number of in-flight concurrent downloads that uv will - perform at any given time. -- `UV_CONCURRENT_BUILDS`: Sets the maximum number of source distributions that uv will build - concurrently at any given time. -- `UV_CONCURRENT_INSTALLS`: Used to control the number of threads used when installing and unzipping - packages. -- `UV_TOOL_DIR`: Used to specify the directory where uv will store managed tools. -- `UV_TOOL_BIN_DIR`: Used to specify the "bin" directory where uv will install tool executables. -- `UV_PROJECT_ENVIRONMENT`: Use to specify the path to the directory to use for a project virtual - environment. See the - [project documentation](../concepts/projects.md#configuring-the-project-environment-path) for more - details. -- `UV_PYTHON_INSTALL_DIR`: Used to specify the directory where uv will store managed Python - installations. -- `UV_PYTHON_INSTALL_MIRROR`: Managed Python installations are downloaded from - [`python-build-standalone`](https://github.com/indygreg/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/indygreg/python-build-standalone/releases/download` in, e.g., - `https://github.com/indygreg/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. -- `UV_PYPY_INSTALL_MIRROR`: Managed PyPy installations are downloaded from - [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. -- `XDG_CONFIG_HOME`: Used to specify the path to uv user-level configuration directory on Unix - systems. -- `XDG_CACHE_HOME`: Used to specify the directory where uv stores cache files on Unix systems. -- `XDG_DATA_HOME`: Used to specify the directory where uv stores managed Python installations and - managed tools on Unix systems. -- `XDG_BIN_HOME`: Used to specify the directory where executables are installed into. -- `SSL_CERT_FILE`: If set, uv will use this file as the certificate bundle instead of the system's - trust store. -- `SSL_CLIENT_CERT`: If set, uv will use this file for mTLS authentication. This should be a single - file containing both the certificate and the private key in PEM format. -- `RUST_LOG`: If set, uv will use this value as the log level for its `--verbose` output. Accepts - any filter compatible with the `tracing_subscriber` crate. For example, `RUST_LOG=trace` will - enable trace-level logging. See the - [tracing documentation](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax) - for more. -- `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`: The proxy to use for all HTTP/HTTPS requests. -- `HTTP_TIMEOUT` (or `UV_HTTP_TIMEOUT`): If set, uv will use this value (in seconds) as the timeout - for HTTP reads (default: 30 s). -- `PYC_INVALIDATION_MODE`: The validation modes to use when run with `--compile`. See: - [`PycInvalidationMode`](https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode). +- `UV_DEFAULT_INDEX`: Equivalent to the `--default-index` argument. Base index URL for searching packages. +- `UV_INDEX`: Equivalent to the `--index` argument. Additional indexes for searching packages. +- `UV_INDEX_URL`: Equivalent to the `--index-url` argument. Base index URL for searching packages. +- `UV_EXTRA_INDEX_URL`: Equivalent to the `--extra-index-url` argument. Additional indexes for searching packages. +- `UV_FIND_LINKS`: Equivalent to the `--find-links` argument. Additional package search locations. +- `UV_CACHE_DIR`: Equivalent to the `--cache-dir` argument. Custom directory for caching. +- `UV_NO_CACHE`: Equivalent to the `--no-cache` argument. Disables cache usage. +- `UV_RESOLUTION`: Equivalent to the `--resolution` argument. Controls dependency resolution strategy. +- `UV_PRERELEASE`: Equivalent to the `--prerelease` argument. Allows or disallows pre-release versions. +- `UV_SYSTEM_PYTHON`: Equivalent to the `--system` argument. Use system Python interpreter. +- `UV_PYTHON`: Equivalent to the `--python` argument. Path to a specific Python interpreter. +- `UV_BREAK_SYSTEM_PACKAGES`: Equivalent to the `--break-system-packages` argument. Allows breaking system packages. +- `UV_NATIVE_TLS`: Equivalent to the `--native-tls` argument. Uses system's trust store for TLS. +- `UV_INDEX_STRATEGY`: Equivalent to the `--index-strategy` argument. Defines strategy for searching index URLs. +- `UV_REQUIRE_HASHES`: Equivalent to the `--require-hashes` argument. Requires hashes for all dependencies. +- `UV_CONSTRAINT`: Equivalent to the `--constraint` argument. Path to constraints file. +- `UV_BUILD_CONSTRAINT`: Equivalent to the `--build-constraint` argument. Path to build constraints file. +- `UV_OVERRIDE`: Equivalent to the `--override` argument. Path to overrides file. +- `UV_LINK_MODE`: Equivalent to the `--link-mode` argument. Specifies link mode for the installation. +- `UV_NO_BUILD_ISOLATION`: Equivalent to the `--no-build-isolation` argument. Skips build isolation. +- `UV_CUSTOM_COMPILE_COMMAND`: Equivalent to the `--custom-compile-command` argument. Overrides the command in `requirements.txt`. +- `UV_KEYRING_PROVIDER`: Equivalent to the `--keyring-provider` argument. Specifies keyring provider. +- `UV_CONFIG_FILE`: Equivalent to the `--config-file` argument. Path to configuration file. +- `UV_NO_CONFIG`: Equivalent to the `--no-config` argument. Prevents reading configuration files. +- `UV_EXCLUDE_NEWER`: Equivalent to the `--exclude-newer` argument. Excludes newer distributions after a date. +- `UV_PYTHON_PREFERENCE`: Equivalent to the `--python-preference` argument. Controls preference for Python versions. +- `UV_PYTHON_DOWNLOADS`: Equivalent to the `--no-python-downloads` argument. Disables Python downloads. +- `UV_COMPILE_BYTECODE`: Equivalent to the `--compile-bytecode` argument. Compiles Python source to bytecode. +- `UV_PUBLISH_URL`: Equivalent to the `--publish-url` argument. URL for publishing packages. +- `UV_PUBLISH_TOKEN`: Equivalent to the `--token` argument in `uv publish`. Token for publishing. +- `UV_PUBLISH_USERNAME`: Equivalent to the `--username` argument in `uv publish`. Username for publishing. +- `UV_PUBLISH_PASSWORD`: Equivalent to the `--password` argument in `uv publish`. Password for publishing. +- `UV_NO_SYNC`: Equivalent to the `--no-sync` argument. Skips syncing the environment. +- `UV_LOCKED`: Equivalent to the `--locked` argument. Assert that the `uv.lock` will remain unchanged. +- `UV_FROZEN`: Equivalent to the `--frozen` argument. Run without updating the `uv.lock` file. +- `UV_PREVIEW`: Equivalent to the `--preview` argument. Enables preview mode. +- `UV_GITHUB_TOKEN`: Equivalent to the `--token` argument for self update. A GitHub token for authentication. +- `UV_VERIFY_HASHES`: Equivalent to the `--verify-hashes` argument. Verifies included hashes. +- `UV_INSECURE_HOST`: Equivalent to the `--allow-insecure-host` argument. +- `UV_CONCURRENT_DOWNLOADS`: Sets the maximum number of in-flight concurrent downloads. +- `UV_CONCURRENT_BUILDS`: Sets the maximum number of concurrent builds for source distributions. +- `UV_CONCURRENT_INSTALLS`: Controls the number of threads used for concurrent installations. +- `UV_TOOL_DIR`: Specifies the directory where `uv` stores managed tools. +- `UV_TOOL_BIN_DIR`: Specifies the "bin" directory for installing tool executables. +- `UV_PROJECT_ENVIRONMENT`: Specifies the path to the project virtual environment. +- `UV_PYTHON_INSTALL_DIR`: Specifies the directory for storing managed Python installations. +- `UV_PYTHON_INSTALL_MIRROR`: Mirror URL for downloading managed Python installations. +- `UV_PYPY_INSTALL_MIRROR`: Mirror URL for downloading managed PyPy installations. +- `UV_TEST_PYTHON_PATH`: Used to override `PATH` to limit Python executable availability in the test suite. +- `UV_SHOW_RESOLUTION`: Include resolver and installer output related to environment modifications. +- `UV_UPDATE_SCHEMA`: Use to update the json schema files. +- `UV_NO_WRAP`: Use to disable line wrapping for diagnostics. +- `UV_STACK_SIZE`: Use to control the stack size used by uv. Typically more relevant for Windows in debug mode. +- `UV_COMMIT_HASH`: Used to set the uv commit hash at build time via `build.rs`. +- `UV_COMMIT_SHORT_HASH`: Used to set the uv commit short hash at build time via `build.rs`. +- `UV_COMMIT_DATE`: Used to set the uv commit date at build time via `build.rs`. +- `UV_LAST_TAG`: Used to set the uv tag at build time via `build.rs`. +- `UV_LAST_TAG_DISTANCE`: Used to set the uv tag distance from head at build time via `build.rs`. +- `UV_INTERNAL__PARENT_INTERPRETER`: Used to set the spawning/parent interpreter when using --system in the test suite. +- `UV_INTERNAL__SHOW_DERIVATION_TREE`: Used to force showing the derivation tree during resolver error reporting. +- `UV_INTERNAL__TEST_DIR`: Used to set a temporary directory for some tests. +- `XDG_CONFIG_DIRS`: Path to system-level configuration directory on Unix systems. +- `SYSTEMDRIVE`: Path to system-level configuration directory on Windows systems. +- `XDG_CONFIG_HOME`: Path to user-level configuration directory on Unix systems. +- `XDG_CACHE_HOME`: Path to cache directory on Unix systems. +- `XDG_DATA_HOME`: Path to directory for storing managed Python installations and tools. +- `XDG_BIN_HOME`: Path to directory where executables are installed. +- `UV_HTTP_TIMEOUT`: Timeout (in seconds) for HTTP requests. +- `UV_REQUEST_TIMEOUT`: Timeout (in seconds) for HTTP requests. +- `HTTP_TIMEOUT`: Timeout (in seconds) for HTTP requests. +- `SSL_CERT_FILE`: Custom certificate bundle file path for SSL connections. +- `SSL_CLIENT_CERT`: File for mTLS authentication (contains certificate and private key). +- `HTTP_PROXY`: Proxy for HTTP requests. +- `HTTPS_PROXY`: Proxy for HTTPS requests. +- `ALL_PROXY`: General proxy for all network requests. - `VIRTUAL_ENV`: Used to detect an activated virtual environment. - `CONDA_PREFIX`: Used to detect an activated Conda environment. -- `PROMPT`: Used to detect the use of the Windows Command Prompt (as opposed to PowerShell). -- `VIRTUAL_ENV_DISABLE_PROMPT`: If set to `1` before a virtual environment is activated, then the - virtual environment name will not be prepended to the terminal prompt. -- `NU_VERSION`: Used to detect the use of NuShell. -- `FISH_VERSION`: Used to detect the use of the Fish shell. -- `BASH_VERSION`: Used to detect the use of the Bash shell. -- `ZSH_VERSION`: Used to detect the use of the Zsh shell. -- `MACOSX_DEPLOYMENT_TARGET`: Used with `--python-platform macos` and related variants to set the - deployment target (i.e., the minimum supported macOS version). Defaults to `12.0`, the - least-recent non-EOL macOS version at time of writing. -- `NO_COLOR`: Disable colors. Takes precedence over `FORCE_COLOR`. See - [no-color.org](https://no-color.org). -- `FORCE_COLOR`: Enforce colors regardless of TTY support. See - [force-color.org](https://force-color.org). +- `VIRTUAL_ENV_DISABLE_PROMPT`: Disables prepending virtual environment name to the terminal prompt. +- `PROMPT`: Used to detect Windows Command Prompt usage. +- `NU_VERSION`: Used to detect `NuShell` usage. +- `FISH_VERSION`: Used to detect Fish shell usage. +- `BASH_VERSION`: Used to detect Bash shell usage. +- `ZSH_VERSION`: Used to detect Zsh shell usage. +- `ZDOTDIR`: Used to determine which `.zshenv` to use when Zsh is being used. +- `KSH_VERSION`: Used to detect Ksh shell usage. +- `MACOSX_DEPLOYMENT_TARGET`: Sets macOS deployment target when using `--python-platform macos`. +- `NO_COLOR`: Disables colored output (takes precedence over `FORCE_COLOR`). +- `FORCE_COLOR`: Forces colored output regardless of terminal support. +- `CLICOLOR_FORCE`: Use to control color via `anstyle`. +- `PATH`: The standard `PATH` env var. +- `HOME`: The standard `HOME` env var. +- `SHELL`: The standard `SHELL` posix env var. +- `PWD`: The standard `PWD` posix env var. +- `LOCALAPPDATA`: Used to look for Microsoft Store Pythons installations. +- `GIT_DIR`: Path to the `.git` directory. Ignored by `uv` when performing fetch. +- `GIT_WORK_TREE`: Path to the git working tree. Ignored by `uv` when performing fetch. +- `GIT_INDEX_FILE`: Path to the index file for staged changes. Ignored by `uv` when performing fetch. +- `GIT_OBJECT_DIRECTORY`: Path to where git object files are located. Ignored by `uv` when performing fetch. +- `GIT_ALTERNATE_OBJECT_DIRECTORIES`: Alternate locations for git objects. Ignored by `uv` when performing fetch. +- `GITHUB_ACTIONS`: Used for trusted publishing via `uv publish`. +- `ACTIONS_ID_TOKEN_REQUEST_URL`: Used for trusted publishing via `uv publish`. Contains the oidc token url. +- `ACTIONS_ID_TOKEN_REQUEST_TOKEN`: Used for trusted publishing via `uv publish`. Contains the oidc request token. +- `PYTHONIOENCODING`: Sets the encoding for standard I/O streams (e.g., PYTHONIOENCODING=utf-8). +- `PYTHONUNBUFFERED`: Forces unbuffered I/O streams, equivalent to `-u` in Python. +- `PYTHONUTF8`: Enables UTF-8 mode for Python, equivalent to `-X utf8`. +- `PYTHONPATH`: Adds directories to Python module search path (e.g., PYTHONPATH=/path/to/modules). +- `CI`: Typically set by CI runners, used to detect a CI runner. +- `NETRC`: Use to set the .netrc file location. +- `PAGER`: The standard `PAGER` posix env var. Used by `uv` to configure the appropriate pager. +- `JPY_SESSION_NAME`: Used to detect when running inside a Jupyter notebook. +- `TRACING_DURATIONS_TEST_ROOT`: Use to create the tracing root directory via the `tracing-durations-export` feature. +- `TRACING_DURATIONS_FILE`: Use to create the tracing durations file via the `tracing-durations-export` feature. +- `TARGET`: Used to set `RUST_HOST_TARGET` at build time via `build.rs`. +- `RUST_LOG`: Custom log level for verbose output, compatible with `tracing_subscriber`. +- `CARGO_MANIFEST_DIR`: The directory containing the `Cargo.toml` manifest for a package. +- `CARGO_TARGET_DIR`: Specifies the directory where Cargo stores build artifacts (target directory). +- `URL`: Used in tests for environment substitution testing in `requirements.in`. +- `FILE_PATH`: Used in tests for environment substitution testing in `requirements.in`. +- `HATCH_PATH`: Used in tests for environment substitution testing in `requirements.in`. +- `BLACK_PATH`: Used in tests for environment substitution testing in `requirements.in`. +- `ROOT_PATH`: Used in testing Hatch's root.uri feature +- `KEYRING_TEST_CREDENTIALS`: Used to set test credentials for keyring tests.