pioduino/uv
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Add reference documentation for global settings (#5123)

Browse Source 
## Summary

Second part of: https://github.com/astral-sh/uv/issues/5093.
This commit is contained in:
Charlie Marsh
2024-07-16 16:50:04 -04:00
committed by GitHub
parent 47e453b01a
commit f7c52fdbfb
18 changed files with 428 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files
crates/uv-cli/src/lib.rs
+68 -67
View File
@@ -111,8 +111,8 @@ pub struct GlobalArgs {
/// Whether to load TLS certificates from the platform's native certificate store.
///
/// By default, `uv` loads certificates from the bundled `webpki-roots` crate. The
/// `webpki-roots` are a reliable set of trust roots from Mozilla, and including them in `uv`
/// By default, uv loads certificates from the bundled `webpki-roots` crate. The
/// `webpki-roots` are a reliable set of trust roots from Mozilla, and including them in uv
/// improves portability and performance (especially on macOS).
///
/// However, in some cases, you may want to use the platform's native certificate store,
@@ -131,7 +131,8 @@ pub struct GlobalArgs {
#[arg(global = true, long, overrides_with("offline"), hide = true)]
pub no_offline: bool,
/// Whether to prefer using Python from uv or on the system.
/// Whether to prefer using Python installations that are already present on the system, or
/// those that are downloaded and installed by uv.
#[arg(global = true, long)]
pub python_preference: Option<PythonPreference>,
@@ -216,7 +217,7 @@ pub enum Commands {
after_long_help = ""
)]
Cache(CacheNamespace),
/// Manage the `uv` executable.
/// Manage the uv executable.
#[command(name = "self")]
#[cfg(feature = "self-update")]
Self_(SelfNamespace),
@@ -258,7 +259,7 @@ pub struct SelfNamespace {
#[derive(Subcommand)]
#[cfg(feature = "self-update")]
pub enum SelfCommand {
/// Update `uv` to the latest version.
/// Update uv to the latest version.
Update,
}
@@ -454,7 +455,7 @@ fn parse_maybe_file_path(input: &str) -> Result<Maybe<PathBuf>, String> {
pub struct PipCompileArgs {
/// Include all packages listed in the given `requirements.in` files.
///
/// If a `pyproject.toml`, `setup.py`, or `setup.cfg` file is provided, `uv` will
/// If a `pyproject.toml`, `setup.py`, or `setup.cfg` file is provided, uv will
/// extract the requirements for the relevant project.
///
/// If `-` is provided, then requirements will be read from stdin.
@@ -516,7 +517,7 @@ pub struct PipCompileArgs {
/// Include extras in the output file.
///
/// By default, `uv` strips extras, as any packages pulled in by the extras are already included
/// 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.
#[arg(long, overrides_with("strip_extras"))]
@@ -527,7 +528,7 @@ pub struct PipCompileArgs {
/// Include environment markers in the output file.
///
/// By default, `uv` strips environment markers, as the resolution generated by `compile` is
/// By default, uv strips environment markers, as the resolution generated by `compile` is
/// only guaranteed to be correct for the target environment.
#[arg(long, overrides_with("strip_markers"))]
pub no_strip_markers: bool,
@@ -561,7 +562,7 @@ pub struct PipCompileArgs {
/// The Python interpreter against which to compile the requirements.
///
/// By default, `uv` uses the virtual environment in the current working directory or any parent
/// By default, uv uses the virtual environment in the current working directory or any parent
/// directory, falling back to searching for a Python executable in `PATH`. The `--python`
/// option allows you to specify a different interpreter.
///
@@ -575,9 +576,9 @@ pub struct PipCompileArgs {
/// Install packages into the system Python.
///
/// By default, `uv` uses the virtual environment in the current working directory or any parent
/// By default, uv uses the virtual environment in the current working directory or any parent
/// directory, falling back to searching for a Python executable in `PATH`. The `--system`
/// option instructs `uv` to avoid using a virtual environment Python and restrict its search to
/// option instructs uv to avoid using a virtual environment Python and restrict its search to
/// the system path.
#[arg(
long,
@@ -752,7 +753,7 @@ pub struct PipCompileArgs {
pub struct PipSyncArgs {
/// Include all packages listed in the given `requirements.txt` files.
///
/// If a `pyproject.toml`, `setup.py`, or `setup.cfg` file is provided, `uv` will
/// If a `pyproject.toml`, `setup.py`, or `setup.cfg` file is provided, uv will
/// extract the requirements for the relevant project.
///
/// If `-` is provided, then requirements will be read from stdin.
@@ -795,7 +796,7 @@ pub struct PipSyncArgs {
/// The Python interpreter into which packages should be installed.
///
/// By default, `uv` installs into the virtual environment in the current working directory or
/// 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.
@@ -810,8 +811,8 @@ pub struct PipSyncArgs {
/// Install packages into the system Python.
///
/// 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
/// 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
@@ -827,12 +828,12 @@ pub struct PipSyncArgs {
#[arg(long, overrides_with("system"), hide = true)]
pub no_system: bool,
/// Allow `uv` to modify an `EXTERNALLY-MANAGED` Python installation.
/// 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`).
/// explicitly recommend against modifications by other package managers (like uv or `pip`).
#[arg(
long,
env = "UV_BREAK_SYSTEM_PACKAGES",
@@ -983,7 +984,7 @@ pub struct PipInstallArgs {
/// Install all packages listed in the given `requirements.txt` files.
///
/// If a `pyproject.toml`, `setup.py`, or `setup.cfg` file is provided, `uv` will
/// If a `pyproject.toml`, `setup.py`, or `setup.cfg` file is provided, uv will
/// extract the requirements for the relevant project.
///
/// If `-` is provided, then requirements will be read from stdin.
@@ -1067,7 +1068,7 @@ pub struct PipInstallArgs {
/// The Python interpreter into which packages should be installed.
///
/// By default, `uv` installs into the virtual environment in the current working directory or
/// 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.
@@ -1082,8 +1083,8 @@ pub struct PipInstallArgs {
/// Install packages into the system Python.
///
/// 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
/// 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
@@ -1099,12 +1100,12 @@ pub struct PipInstallArgs {
#[arg(long, overrides_with("system"), hide = true)]
pub no_system: bool,
/// Allow `uv` to modify an `EXTERNALLY-MANAGED` Python installation.
/// 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`).
/// explicitly recommend against modifications by other package managers (like uv or `pip`).
#[arg(
long,
env = "UV_BREAK_SYSTEM_PACKAGES",
@@ -1252,7 +1253,7 @@ pub struct PipUninstallArgs {
/// The Python interpreter from which packages should be uninstalled.
///
/// By default, `uv` uninstalls from the virtual environment in the current working directory or
/// By default, uv uninstalls from 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.
@@ -1267,7 +1268,7 @@ pub struct PipUninstallArgs {
/// Attempt to use `keyring` for authentication for remote requirements files.
///
/// At present, only `--keyring-provider subprocess` is supported, which configures `uv` to
/// At present, only `--keyring-provider subprocess` is supported, which configures uv to
/// use the `keyring` CLI to handle authentication.
///
/// Defaults to `disabled`.
@@ -1276,8 +1277,8 @@ pub struct PipUninstallArgs {
/// Use the system Python to uninstall packages.
///
/// By default, `uv` uninstalls from the virtual environment in the current working directory or
/// any parent directory. The `--system` option instructs `uv` to instead use the first Python
/// By default, uv uninstalls from 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
@@ -1293,12 +1294,12 @@ pub struct PipUninstallArgs {
#[arg(long, overrides_with("system"), hide = true)]
pub no_system: bool,
/// Allow `uv` to modify an `EXTERNALLY-MANAGED` Python installation.
/// 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`).
/// explicitly recommend against modifications by other package managers (like uv or `pip`).
#[arg(
long,
env = "UV_BREAK_SYSTEM_PACKAGES",
@@ -1339,7 +1340,7 @@ pub struct PipFreezeArgs {
/// The Python interpreter for which packages should be listed.
///
/// By default, `uv` lists packages in the currently activated virtual environment, or a virtual
/// By default, uv lists packages in the currently activated virtual environment, or a virtual
/// environment (`.venv`) located in the current working directory or any parent directory,
/// falling back to the system Python if no virtual environment is found.
///
@@ -1353,10 +1354,10 @@ pub struct PipFreezeArgs {
/// List packages for the system Python.
///
/// By default, `uv` lists packages in the currently activated virtual environment, or a virtual
/// By default, uv lists packages in the currently activated virtual environment, or a virtual
/// environment (`.venv`) located in the current working directory or any parent directory,
/// falling back to the system Python if no virtual environment is found. The `--system` option
/// instructs `uv` to use the first Python found in the system `PATH`.
/// instructs uv to 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.
@@ -1404,7 +1405,7 @@ pub struct PipListArgs {
/// The Python interpreter for which packages should be listed.
///
/// By default, `uv` lists packages in the currently activated virtual environment, or a virtual
/// By default, uv lists packages in the currently activated virtual environment, or a virtual
/// environment (`.venv`) located in the current working directory or any parent directory,
/// falling back to the system Python if no virtual environment is found.
///
@@ -1418,10 +1419,10 @@ pub struct PipListArgs {
/// List packages for the system Python.
///
/// By default, `uv` lists packages in the currently activated virtual environment, or a virtual
/// By default, uv lists packages in the currently activated virtual environment, or a virtual
/// environment (`.venv`) located in the current working directory or any parent directory,
/// falling back to the system Python if no virtual environment is found. The `--system` option
/// instructs `uv` to use the first Python found in the system `PATH`.
/// instructs uv to 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.
@@ -1445,7 +1446,7 @@ pub struct PipListArgs {
pub struct PipCheckArgs {
/// The Python interpreter for which packages should be listed.
///
/// By default, `uv` lists packages in the currently activated virtual environment, or a virtual
/// By default, uv lists packages in the currently activated virtual environment, or a virtual
/// environment (`.venv`) located in the current working directory or any parent directory,
/// falling back to the system Python if no virtual environment is found.
///
@@ -1459,10 +1460,10 @@ pub struct PipCheckArgs {
/// List packages for the system Python.
///
/// By default, `uv` lists packages in the currently activated virtual environment, or a virtual
/// By default, uv lists packages in the currently activated virtual environment, or a virtual
/// environment (`.venv`) located in the current working directory or any parent directory,
/// falling back to the system Python if no virtual environment is found. The `--system` option
/// instructs `uv` to use the first Python found in the system `PATH`.
/// instructs uv to 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.
@@ -1494,7 +1495,7 @@ pub struct PipShowArgs {
/// The Python interpreter for which packages should be listed.
///
/// By default, `uv` lists packages in the currently activated virtual environment, or a virtual
/// By default, uv lists packages in the currently activated virtual environment, or a virtual
/// environment (`.venv`) located in the current working directory or any parent directory,
/// falling back to the system Python if no virtual environment is found.
///
@@ -1508,10 +1509,10 @@ pub struct PipShowArgs {
/// List packages for the system Python.
///
/// By default, `uv` lists packages in the currently activated virtual environment, or a virtual
/// By default, uv lists packages in the currently activated virtual environment, or a virtual
/// environment (`.venv`) located in the current working directory or any parent directory,
/// falling back to the system Python if no virtual environment is found. The `--system` option
/// instructs `uv` to use the first Python found in the system `PATH`.
/// instructs uv to 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.
@@ -1546,7 +1547,7 @@ pub struct PipTreeArgs {
/// The Python interpreter for which packages should be listed.
///
/// By default, `uv` lists packages in the currently activated virtual environment, or a virtual
/// By default, uv lists packages in the currently activated virtual environment, or a virtual
/// environment (`.venv`) located in the current working directory or any parent directory,
/// falling back to the system Python if no virtual environment is found.
///
@@ -1560,10 +1561,10 @@ pub struct PipTreeArgs {
/// List packages for the system Python.
///
/// By default, `uv` lists packages in the currently activated virtual environment, or a virtual
/// By default, uv lists packages in the currently activated virtual environment, or a virtual
/// environment (`.venv`) located in the current working directory or any parent directory,
/// falling back to the system Python if no virtual environment is found. The `--system` option
/// instructs `uv` to use the first Python found in the system `PATH`.
/// instructs uv to 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.
@@ -1600,8 +1601,8 @@ pub struct VenvArgs {
/// Use the system Python to uninstall packages.
///
/// By default, `uv` uninstalls from the virtual environment in the current working directory or
/// any parent directory. The `--system` option instructs `uv` to use the first Python found in
/// By default, uv uninstalls from the virtual environment in the current working directory or
/// any parent directory. The `--system` option instructs uv to use the first Python found in
/// the system `PATH`.
///
/// WARNING: `--system` is intended for use in continuous integration (CI) environments and
@@ -1653,11 +1654,11 @@ pub struct VenvArgs {
/// Give the virtual environment access to the system site packages directory.
///
/// Unlike `pip`, when a virtual environment is created with `--system-site-packages`, `uv` will
/// Unlike `pip`, when a virtual environment is created with `--system-site-packages`, uv will
/// _not_ take system site packages into account when running commands like `uv pip list` or
/// `uv pip install`. The `--system-site-packages` flag will provide the virtual environment
/// with access to the system site packages directory at runtime, but it will not affect the
/// behavior of `uv` commands.
/// behavior of uv commands.
#[arg(long)]
pub system_site_packages: bool,
@@ -1666,7 +1667,7 @@ pub struct VenvArgs {
/// 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
/// 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-match`). This prevents
/// "dependency confusion" attacks, whereby an attack can upload a malicious package under the
/// same name to a secondary.
@@ -1675,7 +1676,7 @@ pub struct VenvArgs {
/// Attempt to use `keyring` for authentication for index URLs.
///
/// At present, only `--keyring-provider subprocess` is supported, which configures `uv` to
/// At present, only `--keyring-provider subprocess` is supported, which configures uv to
/// use the `keyring` CLI to handle authentication.
///
/// Defaults to `disabled`.
@@ -1774,7 +1775,7 @@ pub struct RunArgs {
/// The Python interpreter to use to build the run environment.
///
/// By default, `uv` uses the virtual environment in the current working directory or any parent
/// By default, uv uses the virtual environment in the current working directory or any parent
/// directory, falling back to searching for a Python executable in `PATH`. The `--python`
/// option allows you to specify a different interpreter.
///
@@ -1835,7 +1836,7 @@ pub struct SyncArgs {
/// The Python interpreter to use to build the run environment.
///
/// By default, `uv` uses the virtual environment in the current working directory or any parent
/// By default, uv uses the virtual environment in the current working directory or any parent
/// directory, falling back to searching for a Python executable in `PATH`. The `--python`
/// option allows you to specify a different interpreter.
///
@@ -1862,7 +1863,7 @@ pub struct LockArgs {
/// The Python interpreter to use to build the run environment.
///
/// By default, `uv` uses the virtual environment in the current working directory or any parent
/// By default, uv uses the virtual environment in the current working directory or any parent
/// directory, falling back to searching for a Python executable in `PATH`. The `--python`
/// option allows you to specify a different interpreter.
///
@@ -1931,7 +1932,7 @@ pub struct AddArgs {
/// The Python interpreter into which packages should be installed.
///
/// By default, `uv` installs into the virtual environment in the current working directory or
/// 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.
@@ -1975,7 +1976,7 @@ pub struct RemoveArgs {
/// The Python interpreter into which packages should be installed.
///
/// By default, `uv` installs into the virtual environment in the current working directory or
/// 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.
@@ -2003,7 +2004,7 @@ pub struct TreeArgs {
/// The Python interpreter for which packages should be listed.
///
/// By default, `uv` installs into the virtual environment in the current working directory or
/// 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.
@@ -2083,7 +2084,7 @@ pub struct ToolRunArgs {
/// The Python interpreter to use to build the run environment.
///
/// By default, `uv` uses the virtual environment in the current working directory or any parent
/// By default, uv uses the virtual environment in the current working directory or any parent
/// directory, falling back to searching for a Python executable in `PATH`. The `--python`
/// option allows you to specify a different interpreter.
///
@@ -2366,7 +2367,7 @@ pub struct InstallerArgs {
/// 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
/// 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-match`). This prevents
/// "dependency confusion" attacks, whereby an attack can upload a malicious package under the
/// same name to a secondary.
@@ -2375,7 +2376,7 @@ pub struct InstallerArgs {
/// Attempt to use `keyring` for authentication for index URLs.
///
/// At present, only `--keyring-provider subprocess` is supported, which configures `uv` to
/// At present, only `--keyring-provider subprocess` is supported, which configures uv to
/// use the `keyring` CLI to handle authentication.
///
/// Defaults to `disabled`.
@@ -2442,7 +2443,7 @@ pub struct ResolverArgs {
/// 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
/// 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-match`). This prevents
/// "dependency confusion" attacks, whereby an attack can upload a malicious package under the
/// same name to a secondary.
@@ -2451,7 +2452,7 @@ pub struct ResolverArgs {
/// Attempt to use `keyring` for authentication for index URLs.
///
/// At present, only `--keyring-provider subprocess` is supported, which configures `uv` to
/// At present, only `--keyring-provider subprocess` is supported, which configures uv to
/// use the `keyring` CLI to handle authentication.
///
/// Defaults to `disabled`.
@@ -2461,13 +2462,13 @@ pub struct ResolverArgs {
/// 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`).
/// By default, uv will use the latest compatible version of each package (`highest`).
#[arg(long, value_enum, env = "UV_RESOLUTION")]
pub resolution: Option<ResolutionMode>,
/// The strategy to use when considering pre-release versions.
///
/// By default, `uv` will accept pre-releases for packages that _only_ publish pre-releases,
/// By default, uv will accept pre-releases for packages that _only_ publish pre-releases,
/// along with first-party requirements that contain an explicit pre-release marker in the
/// declared specifiers (`if-necessary-or-explicit`).
#[arg(long, value_enum, env = "UV_PRERELEASE")]
@@ -2529,7 +2530,7 @@ pub struct ResolverInstallerArgs {
/// 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
/// 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-match`). This prevents
/// "dependency confusion" attacks, whereby an attack can upload a malicious package under the
/// same name to a secondary.
@@ -2538,7 +2539,7 @@ pub struct ResolverInstallerArgs {
/// Attempt to use `keyring` for authentication for index URLs.
///
/// At present, only `--keyring-provider subprocess` is supported, which configures `uv` to
/// At present, only `--keyring-provider subprocess` is supported, which configures uv to
/// use the `keyring` CLI to handle authentication.
///
/// Defaults to `disabled`.
@@ -2548,13 +2549,13 @@ pub struct ResolverInstallerArgs {
/// 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`).
/// By default, uv will use the latest compatible version of each package (`highest`).
#[arg(long, value_enum, env = "UV_RESOLUTION")]
pub resolution: Option<ResolutionMode>,
/// The strategy to use when considering pre-release versions.
///
/// By default, `uv` will accept pre-releases for packages that _only_ publish pre-releases,
/// By default, uv will accept pre-releases for packages that _only_ publish pre-releases,
/// along with first-party requirements that contain an explicit pre-release marker in the
/// declared specifiers (`if-necessary-or-explicit`).
#[arg(long, value_enum, env = "UV_PRERELEASE")]