mirrors/uv
1
0
Fork 0
mirror of https://github.com/astral-sh/uv.git synced 2025-08-02 01:52:22 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Add reference documentation for pip settings (#5125)

Browse source 
## Summary

Third part of https://github.com/astral-sh/uv/issues/5093.
This commit is contained in:
Charlie Marsh 2024-07-16 17:14:27 -04:00 • committed by GitHub
parent 21cda3e079
commit 7211e62132
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 2199 additions and 50 deletions
Download patch file Download diff file Expand all files Collapse all files

90
crates/uv-cli/src/lib.rs
View file

@ -485,11 +485,13 @@ pub struct PipCompileArgs {
pub r#override: Vec<Maybe<PathBuf>>,
/// Include optional dependencies from the extra group name; may be provided more than once.
///
/// Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources.
#[arg(long, conflicts_with = "all_extras", value_parser = extra_name_with_clap_error)]
pub extra: Option<Vec<ExtraName>>,
/// Include all optional dependencies.
///
/// Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources.
#[arg(long, conflicts_with = "extra")]
pub all_extras: bool,
@ -512,6 +514,9 @@ pub struct PipCompileArgs {
pub deps: bool,
/// Write the compiled requirements to the given `requirements.txt` file.
///
/// If the file already exists, the existing versions will be preferred when resolving
/// dependencies, unless `--upgrade` is also specified.
#[arg(long, short)]
pub output_file: Option<PathBuf>,
@ -550,13 +555,16 @@ pub struct PipCompileArgs {
#[arg(long, overrides_with("no_header"), hide = true)]
pub header: bool,
/// Choose the style of the annotation comments, which indicate the source of each package.
/// The style of the annotation comments included in the output file, used to indicate the
/// source of each package.
///
/// Defaults to `split`.
#[arg(long, value_enum)]
pub annotation_style: Option<AnnotationStyle>,
/// Change header comment to reflect custom command wrapping `uv pip compile`.
/// The header comment to include at the top of the output file generated by `uv pip compile`.
///
/// Used to reflect custom build scripts and commands that wrap `uv pip compile`.
#[arg(long, env = "UV_CUSTOM_COMPILE_COMMAND")]
pub custom_compile_command: Option<String>,
@ -574,7 +582,7 @@ pub struct PipCompileArgs {
#[arg(long, verbatim_doc_comment)]
pub python: Option<String>,
/// Install packages into the system Python.
/// Install packages into the system Python environment.
///
/// 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`
@ -665,11 +673,11 @@ pub struct PipCompileArgs {
#[arg(long, conflicts_with = "no_build")]
pub only_binary: Option<Vec<PackageNameSpecifier>>,
/// The minimum Python version that should be supported by the compiled requirements (e.g.,
/// `3.7` or `3.7.9`).
/// The minimum Python version that should be supported by the resolved requirements (e.g.,
/// `3.8` or `3.8.17`).
///
/// If a patch version is omitted, the minimum patch version is assumed. For example, `3.7` is
/// mapped to `3.7.0`.
/// If a patch version is omitted, the minimum patch version is assumed. For example, `3.8` is
/// mapped to `3.8.0`.
#[arg(long, short)]
pub python_version: Option<PythonVersion>,
@ -783,6 +791,7 @@ pub struct PipSyncArgs {
/// must either be pinned to exact versions (e.g., `==1.0.0`), or be specified via direct URL.
///
/// Hash-checking mode introduces a number of additional constraints:
///
/// - Git dependencies are not supported.
/// - Editable installs are not supported.
/// - Local dependencies are not supported, unless they point to a specific wheel (`.whl`) or
@ -809,7 +818,7 @@ pub struct PipSyncArgs {
#[arg(long, short, env = "UV_PYTHON", verbatim_doc_comment)]
pub python: Option<String>,
/// Install packages into the system Python.
/// Install packages into the system Python environment.
///
/// By default, uv installs into the virtual environment in the current working directory or
/// any parent directory. The `--system` option instructs uv to instead use the first Python
@ -845,14 +854,13 @@ pub struct PipSyncArgs {
#[arg(long, overrides_with("break_system_packages"))]
pub no_break_system_packages: bool,
/// Install packages into the specified directory, rather than into the virtual environment
/// or system Python interpreter. The packages will be installed at the top-level of the
/// directory
/// Install packages into the specified directory, rather than into the virtual or system Python
/// environment. The packages will be installed at the top-level of the directory.
#[arg(long, conflicts_with = "prefix")]
pub target: Option<PathBuf>,
/// Install packages into `lib`, `bin`, and other top-level folders under the specified
/// directory, as if a virtual environment were created at the specified location.
/// directory, as if a virtual environment were present at that location.
///
/// In general, prefer the use of `--python` to install into an alternate environment, as
/// scripts and other artifacts installed via `--prefix` will reference the installing
@ -957,7 +965,7 @@ pub struct PipSyncArgs {
#[arg(long)]
pub python_platform: Option<TargetTriple>,
/// Validate the virtual environment after completing the installation, to detect packages with
/// Validate the Python environment after completing the installation, to detect and with
/// missing dependencies or other issues.
#[arg(long, overrides_with("no_strict"))]
pub strict: bool,
@ -1018,11 +1026,13 @@ pub struct PipInstallArgs {
pub r#override: Vec<Maybe<PathBuf>>,
/// Include optional dependencies from the extra group name; may be provided more than once.
///
/// Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources.
#[arg(long, conflicts_with = "all_extras", value_parser = extra_name_with_clap_error)]
pub extra: Option<Vec<ExtraName>>,
/// Include all optional dependencies.
///
/// Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources.
#[arg(long, conflicts_with = "extra", overrides_with = "no_all_extras")]
pub all_extras: bool,
@ -1051,6 +1061,7 @@ pub struct PipInstallArgs {
/// must either be pinned to exact versions (e.g., `==1.0.0`), or be specified via direct URL.
///
/// Hash-checking mode introduces a number of additional constraints:
///
/// - Git dependencies are not supported.
/// - Editable installs are not supported.
/// - Local dependencies are not supported, unless they point to a specific wheel (`.whl`) or
@ -1081,7 +1092,7 @@ pub struct PipInstallArgs {
#[arg(long, short, env = "UV_PYTHON", verbatim_doc_comment)]
pub python: Option<String>,
/// Install packages into the system Python.
/// Install packages into the system Python environment.
///
/// By default, uv installs into the virtual environment in the current working directory or
/// any parent directory. The `--system` option instructs uv to instead use the first Python
@ -1117,14 +1128,13 @@ pub struct PipInstallArgs {
#[arg(long, overrides_with("break_system_packages"))]
pub no_break_system_packages: bool,
/// Install packages into the specified directory, rather than into the virtual environment
/// or system Python interpreter. The packages will be installed at the top-level of the
/// directory
/// Install packages into the specified directory, rather than into the virtual or system Python
/// environment. The packages will be installed at the top-level of the directory.
#[arg(long, conflicts_with = "prefix")]
pub target: Option<PathBuf>,
/// Install packages into `lib`, `bin`, and other top-level folders under the specified
/// directory, as if a virtual environment were created at the specified location.
/// directory, as if a virtual environment were present at that location.
///
/// In general, prefer the use of `--python` to install into an alternate environment, as
/// scripts and other artifacts installed via `--prefix` will reference the installing
@ -1222,7 +1232,7 @@ pub struct PipInstallArgs {
#[arg(long)]
pub python_platform: Option<TargetTriple>,
/// Validate the virtual environment after completing the installation, to detect packages with
/// Validate the Python environment after completing the installation, to detect and with
/// missing dependencies or other issues.
#[arg(long, overrides_with("no_strict"))]
pub strict: bool,
@ -1330,7 +1340,7 @@ pub struct PipFreezeArgs {
#[arg(long)]
pub exclude_editable: bool,
/// Validate the virtual environment, to detect packages with missing dependencies or other
/// Validate the Python environment, to detect packages with missing dependencies and other
/// issues.
#[arg(long, overrides_with("no_strict"))]
pub strict: bool,
@ -1395,7 +1405,7 @@ pub struct PipListArgs {
#[arg(long, value_enum, default_value_t = ListFormat::default())]
pub format: ListFormat,
/// Validate the virtual environment, to detect packages with missing dependencies or other
/// Validate the Python environment, to detect packages with missing dependencies and other
/// issues.
#[arg(long, overrides_with("no_strict"))]
pub strict: bool,
@ -1485,7 +1495,7 @@ pub struct PipShowArgs {
/// The package(s) to display.
pub package: Vec<PackageName>,
/// Validate the virtual environment, to detect packages with missing dependencies or other
/// Validate the Python environment, to detect packages with missing dependencies and other
/// issues.
#[arg(long, overrides_with("no_strict"))]
pub strict: bool,
@ -1537,7 +1547,7 @@ pub struct PipTreeArgs {
#[command(flatten)]
pub tree: DisplayTreeArgs,
/// Validate the virtual environment, to detect packages with missing dependencies or other
/// Validate the Python environment, to detect packages with missing dependencies and other
/// issues.
#[arg(long, overrides_with("no_strict"))]
pub strict: bool,
@ -1732,11 +1742,13 @@ impl ExternalCommand {
#[allow(clippy::struct_excessive_bools)]
pub struct RunArgs {
/// Include optional dependencies from the extra group name; may be provided more than once.
///
/// Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources.
#[arg(long, conflicts_with = "all_extras", value_parser = extra_name_with_clap_error)]
pub extra: Option<Vec<ExtraName>>,
/// Include all optional dependencies.
///
/// Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources.
#[arg(long, conflicts_with = "extra")]
pub all_extras: bool,
@ -1800,11 +1812,13 @@ pub struct SyncArgs {
pub frozen: bool,
/// Include optional dependencies from the extra group name; may be provided more than once.
///
/// Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources.
#[arg(long, conflicts_with = "all_extras", value_parser = extra_name_with_clap_error)]
pub extra: Option<Vec<ExtraName>>,
/// Include all optional dependencies.
///
/// Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources.
#[arg(long, conflicts_with = "extra")]
pub all_extras: bool,
@ -2401,15 +2415,16 @@ pub struct InstallerArgs {
#[arg(long, value_enum, env = "UV_LINK_MODE")]
pub link_mode: Option<install_wheel_rs::linker::LinkMode>,
/// Compile Python files to bytecode.
/// Compile Python files to bytecode after installation.
///
/// By default, does not compile Python (`.py`) files to bytecode (`__pycache__/*.pyc`), instead
/// Python lazily does the compilation the first time a module is imported. In cases where the
/// first start time matters, such as CLI applications and docker containers, this option can
/// trade longer install time for faster startup.
/// By default, uv does not compile Python (`.py`) files to bytecode (`__pycache__/*.pyc`);
/// instead, compilation is performed lazily the first time a module is imported. For use-cases
/// in which start time is critical, such as CLI applications and Docker containers, this option
/// can be enabled to trade longer installation times for faster start times.
///
/// The compile option will process the entire site-packages directory for consistency and
/// (like pip) ignore all errors.
/// When enabled, uv will process the entire site-packages directory (including packages that
/// are not being modified by the current operation) for consistency. Like pip, it will also
/// ignore errors.
#[arg(long, alias = "compile", overrides_with("no_compile_bytecode"))]
pub compile_bytecode: bool,
@ -2582,15 +2597,16 @@ pub struct ResolverInstallerArgs {
#[arg(long, value_enum, env = "UV_LINK_MODE")]
pub link_mode: Option<install_wheel_rs::linker::LinkMode>,
/// Compile Python files to bytecode.
/// Compile Python files to bytecode after installation.
///
/// By default, does not compile Python (`.py`) files to bytecode (`__pycache__/*.pyc`), instead
/// Python lazily does the compilation the first time a module is imported. In cases where the
/// first start time matters, such as CLI applications and docker containers, this option can
/// trade longer install time for faster startup.
/// By default, uv does not compile Python (`.py`) files to bytecode (`__pycache__/*.pyc`);
/// instead, compilation is performed lazily the first time a module is imported. For use-cases
/// in which start time is critical, such as CLI applications and Docker containers, this option
/// can be enabled to trade longer installation times for faster start times.
///
/// The compile option will process the entire site-packages directory for consistency and
/// (like pip) ignore all errors.
/// When enabled, uv will process the entire site-packages directory (including packages that
/// are not being modified by the current operation) for consistency. Like pip, it will also
/// ignore errors.
#[arg(long, alias = "compile", overrides_with("no_compile_bytecode"))]
pub compile_bytecode: bool,