From 7633f1db839abed6735da21dc8d06ed6f7dd5539 Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Wed, 29 Jan 2025 08:21:32 -0600 Subject: [PATCH] Reflow CLI documentation comments (#11040) I'm sorry, but I was writing some new content here and the inconsistent wrapping was very hard to maintain and I didn't want to muddy the diff there with reflowing. I don't think we need to be strict about the reflow (I'm not sure we even can be) but some of these were very far off from our typical wrap length. --- crates/uv-cli/src/lib.rs | 745 ++++++++++++++++++--------------------- docs/reference/cli.md | 2 +- 2 files changed, 346 insertions(+), 401 deletions(-) diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs index a261824b648c..d45c5942d74b 100644 --- a/crates/uv-cli/src/lib.rs +++ b/crates/uv-cli/src/lib.rs @@ -652,26 +652,24 @@ pub enum ProjectCommand { /// /// Ensures that the command runs in a Python environment. /// - /// When used with a file ending in `.py` or an HTTP(S) URL, the file - /// will be treated as a script and run with a Python interpreter, - /// i.e., `uv run file.py` is equivalent to `uv run python file.py`. - /// For URLs, the script is temporarily downloaded before execution. If - /// the script contains inline dependency metadata, it will be installed - /// into an isolated, ephemeral environment. When used with `-`, the - /// input will be read from stdin, and treated as a Python script. - /// - /// When used in a project, the project environment will be created and - /// updated before invoking the command. - /// - /// When used outside a project, if a virtual environment can be found in - /// the current directory or a parent directory, the command will be run in - /// that environment. Otherwise, the command will be run in the environment - /// of the discovered interpreter. - /// - /// Arguments following the command (or script) are not interpreted as - /// arguments to uv. All options to uv must be provided before the command, - /// e.g., `uv run --verbose foo`. A `--` can be used to separate the command - /// from uv options for clarity, e.g., `uv run --python 3.12 -- python`. + /// When used with a file ending in `.py` or an HTTP(S) URL, the file will be treated as a + /// script and run with a Python interpreter, i.e., `uv run file.py` is equivalent to `uv run + /// python file.py`. For URLs, the script is temporarily downloaded before execution. If the + /// script contains inline dependency metadata, it will be installed into an isolated, ephemeral + /// environment. When used with `-`, the input will be read from stdin, and treated as a Python + /// script. + /// + /// When used in a project, the project environment will be created and updated before invoking + /// the command. + /// + /// When used outside a project, if a virtual environment can be found in the current directory + /// or a parent directory, the command will be run in that environment. Otherwise, the command + /// will be run in the environment of the discovered interpreter. + /// + /// Arguments following the command (or script) are not interpreted as arguments to uv. All + /// options to uv must be provided before the command, e.g., `uv run --verbose foo`. A `--` can + /// be used to separate the command from uv options for clarity, e.g., `uv run --python 3.12 -- + /// python`. #[command( after_help = "Use `uv help run` for more details.", after_long_help = "" @@ -681,16 +679,13 @@ pub enum ProjectCommand { /// /// Follows the `pyproject.toml` specification. /// - /// If a `pyproject.toml` already exists at the target, uv will exit with an - /// error. + /// If a `pyproject.toml` already exists at the target, uv will exit with an error. /// - /// If a `pyproject.toml` is found in any of the parent directories of the - /// target path, the project will be added as a workspace member of - /// the parent. + /// If a `pyproject.toml` is found in any of the parent directories of the target path, the + /// project will be added as a workspace member of the parent. /// - /// Some project state is not created until needed, e.g., the project - /// virtual environment (`.venv`) and lockfile (`uv.lock`) are lazily - /// created during the first sync. + /// Some project state is not created until needed, e.g., the project virtual environment + /// (`.venv`) and lockfile (`uv.lock`) are lazily created during the first sync. Init(InitArgs), /// Add dependencies to the project. /// @@ -726,18 +721,18 @@ pub enum ProjectCommand { /// If multiple entries exist for a given dependency, i.e., each with different markers, all of /// the entries will be removed. /// - /// The lockfile and project environment will be updated to reflect the - /// removed dependencies. To skip updating the lockfile, use `--frozen`. To - /// skip updating the environment, use `--no-sync`. + /// The lockfile and project environment will be updated to reflect the removed dependencies. To + /// skip updating the lockfile, use `--frozen`. To skip updating the environment, use + /// `--no-sync`. /// - /// If any of the requested dependencies are not present in the project, uv - /// will exit with an error. + /// If any of the requested dependencies are not present in the project, uv will exit with an + /// error. /// - /// If a package has been manually installed in the environment, i.e., with - /// `uv pip install`, it will not be removed by `uv remove`. + /// If a package has been manually installed in the environment, i.e., with `uv pip install`, it + /// will not be removed by `uv remove`. /// - /// uv will search for a project in the current directory or any parent - /// directory. If a project cannot be found, uv will exit with an error. + /// uv will search for a project in the current directory or any parent directory. If a project + /// cannot be found, uv will exit with an error. #[command( after_help = "Use `uv help remove` for more details.", after_long_help = "" @@ -771,12 +766,11 @@ pub enum ProjectCommand { Sync(SyncArgs), /// Update the project's lockfile. /// - /// If the project lockfile (`uv.lock`) does not exist, it will be created. - /// If a lockfile is present, its contents will be used as preferences for - /// the resolution. + /// If the project lockfile (`uv.lock`) does not exist, it will be created. If a lockfile is + /// present, its contents will be used as preferences for the resolution. /// - /// If there are no changes to the project's dependencies, locking will have - /// no effect unless the `--upgrade` flag is provided. + /// If there are no changes to the project's dependencies, locking will have no effect unless + /// the `--upgrade` flag is provided. #[command( after_help = "Use `uv help lock` for more details.", after_long_help = "" @@ -1341,13 +1335,11 @@ pub struct PipSyncArgs { /// The Python interpreter into which packages should be installed. /// - /// By default, syncing requires a virtual environment. A path to an - /// alternative Python can be provided, but it is only recommended in - /// continuous integration (CI) environments and should be used with - /// caution, as it can modify the system Python installation. + /// By default, syncing requires a virtual environment. A path to an alternative Python can be + /// provided, but it is only recommended in continuous integration (CI) environments and should + /// be used with caution, as it can modify the system Python installation. /// - /// See `uv help python` for details on Python discovery and supported - /// request formats. + /// See `uv help python` for details on Python discovery and supported request formats. #[arg( long, short, @@ -1360,9 +1352,9 @@ pub struct PipSyncArgs { /// Install packages into the system Python environment. /// - /// By default, uv installs into the virtual environment in the current working directory or - /// any parent directory. The `--system` option instructs uv to instead use the first Python - /// found in the system `PATH`. + /// By default, uv installs into the virtual environment in the current working directory or any + /// parent directory. The `--system` option instructs uv to instead use the first Python found + /// in the system `PATH`. /// /// WARNING: `--system` is intended for use in continuous integration (CI) environments and /// should be used with caution, as it can modify the system Python installation. @@ -1438,19 +1430,19 @@ pub struct PipSyncArgs { /// The given packages will be built and installed from source. The resolver will still use /// pre-built wheels to extract package metadata, if available. /// - /// Multiple packages may be provided. Disable binaries for all packages with `:all:`. - /// Clear previously specified packages with `:none:`. + /// Multiple packages may be provided. Disable binaries for all packages with `:all:`. Clear + /// previously specified packages with `:none:`. #[arg(long, conflicts_with = "no_build")] pub no_binary: Option>, /// Only use pre-built wheels; don't build source distributions. /// - /// When enabled, resolving will not run code from the given packages. The cached wheels of already-built - /// source distributions will be reused, but operations that require building distributions will - /// exit with an error. + /// When enabled, resolving will not run code from the given packages. The cached wheels of + /// already-built source distributions will be reused, but operations that require building + /// distributions will exit with an error. /// - /// Multiple packages may be provided. Disable binaries for all packages with `:all:`. - /// Clear previously specified packages with `:none:`. + /// Multiple packages may be provided. Disable binaries for all packages with `:all:`. Clear + /// previously specified packages with `:none:`. #[arg(long, conflicts_with = "no_build")] pub only_binary: Option>, @@ -1461,8 +1453,8 @@ pub struct PipSyncArgs { #[arg(long, overrides_with("allow_empty_requirements"))] pub no_allow_empty_requirements: bool, - /// The minimum Python version that should be supported by the requirements (e.g., - /// `3.7` or `3.7.9`). + /// The minimum Python version that should be supported by the requirements (e.g., `3.7` or + /// `3.7.9`). /// /// If a patch version is omitted, the minimum patch version is assumed. For example, `3.7` is /// mapped to `3.7.0`. @@ -1515,8 +1507,8 @@ 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 - /// extract the requirements for the relevant project. + /// 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. #[arg(long, short, alias = "requirement", group = "sources", value_parser = parse_file_path)] @@ -1630,13 +1622,11 @@ pub struct PipInstallArgs { /// The Python interpreter into which packages should be installed. /// - /// By default, installation requires a virtual environment. A path to an - /// alternative Python can be provided, but it is only recommended in - /// continuous integration (CI) environments and should be used with - /// caution, as it can modify the system Python installation. + /// By default, installation requires a virtual environment. A path to an alternative Python can + /// be provided, but it is only recommended in continuous integration (CI) environments and + /// should be used with caution, as it can modify the system Python installation. /// - /// See `uv help python` for details on Python discovery and supported - /// request formats. + /// See `uv help python` for details on Python discovery and supported request formats. #[arg( long, short, @@ -1649,9 +1639,9 @@ pub struct PipInstallArgs { /// Install packages into the system Python environment. /// - /// By default, uv installs into the virtual environment in the current working directory or - /// any parent directory. The `--system` option instructs uv to instead use the first Python - /// found in the system `PATH`. + /// By default, uv installs into the virtual environment in the current working directory or any + /// parent directory. The `--system` option instructs uv to instead use the first Python found + /// in the system `PATH`. /// /// WARNING: `--system` is intended for use in continuous integration (CI) environments and /// should be used with caution, as it can modify the system Python installation. @@ -1727,24 +1717,24 @@ pub struct PipInstallArgs { /// The given packages will be built and installed from source. The resolver will still use /// pre-built wheels to extract package metadata, if available. /// - /// Multiple packages may be provided. Disable binaries for all packages with `:all:`. - /// Clear previously specified packages with `:none:`. + /// Multiple packages may be provided. Disable binaries for all packages with `:all:`. Clear + /// previously specified packages with `:none:`. #[arg(long, conflicts_with = "no_build")] pub no_binary: Option>, /// Only use pre-built wheels; don't build source distributions. /// - /// When enabled, resolving will not run code from the given packages. The cached wheels of already-built - /// source distributions will be reused, but operations that require building distributions will - /// exit with an error. + /// When enabled, resolving will not run code from the given packages. The cached wheels of + /// already-built source distributions will be reused, but operations that require building + /// distributions will exit with an error. /// - /// Multiple packages may be provided. Disable binaries for all packages with `:all:`. - /// Clear previously specified packages with `:none:`. + /// Multiple packages may be provided. Disable binaries for all packages with `:all:`. Clear + /// previously specified packages with `:none:`. #[arg(long, conflicts_with = "no_build")] pub only_binary: Option>, - /// The minimum Python version that should be supported by the requirements (e.g., - /// `3.7` or `3.7.9`). + /// The minimum Python version that should be supported by the requirements (e.g., `3.7` or + /// `3.7.9`). /// /// If a patch version is omitted, the minimum patch version is assumed. For example, `3.7` is /// mapped to `3.7.0`. @@ -1811,13 +1801,11 @@ pub struct PipUninstallArgs { /// The Python interpreter from which packages should be uninstalled. /// - /// By default, uninstallation requires a virtual environment. A path to an - /// alternative Python can be provided, but it is only recommended in - /// continuous integration (CI) environments and should be used with - /// caution, as it can modify the system Python installation. + /// By default, uninstallation requires a virtual environment. A path to an alternative Python + /// can be provided, but it is only recommended in continuous integration (CI) environments and + /// should be used with caution, as it can modify the system Python installation. /// - /// See `uv help python` for details on Python discovery and supported - /// request formats. + /// See `uv help python` for details on Python discovery and supported request formats. #[arg( long, short, @@ -1830,8 +1818,8 @@ 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 - /// use the `keyring` CLI to handle authentication. + /// At present, only `--keyring-provider subprocess` is supported, which configures uv to use + /// the `keyring` CLI to handle authentication. /// /// Defaults to `disabled`. #[arg(long, value_enum, env = EnvVars::UV_KEYRING_PROVIDER)] @@ -1906,12 +1894,10 @@ pub struct PipFreezeArgs { /// The Python interpreter for which packages should be listed. /// - /// By default, uv lists packages in a virtual environment but will show - /// packages in a system Python environment if no virtual environment is - /// found. + /// By default, uv lists packages in a virtual environment but will show packages in a system + /// Python environment if no virtual environment is found. /// - /// See `uv help python` for details on Python discovery and supported - /// request formats. + /// See `uv help python` for details on Python discovery and supported request formats. #[arg( long, short, @@ -1988,12 +1974,10 @@ pub struct PipListArgs { /// The Python interpreter for which packages should be listed. /// - /// By default, uv lists packages in a virtual environment but will show - /// packages in a system Python environment if no virtual environment is - /// found. + /// By default, uv lists packages in a virtual environment but will show packages in a system + /// Python environment if no virtual environment is found. /// - /// See `uv help python` for details on Python discovery and supported - /// request formats. + /// See `uv help python` for details on Python discovery and supported request formats. #[arg( long, short, @@ -2029,12 +2013,10 @@ pub struct PipListArgs { pub struct PipCheckArgs { /// The Python interpreter for which packages should be checked. /// - /// By default, uv checks packages in a virtual environment but will check - /// packages in a system Python environment if no virtual environment is - /// found. + /// By default, uv checks packages in a virtual environment but will check packages in a system + /// Python environment if no virtual environment is found. /// - /// See `uv help python` for details on Python discovery and supported - /// request formats. + /// See `uv help python` for details on Python discovery and supported request formats. #[arg( long, short, @@ -2082,12 +2064,10 @@ pub struct PipShowArgs { /// The Python interpreter to find the package in. /// - /// By default, uv looks for packages in a virtual environment but will look - /// for packages in a system Python environment if no virtual environment is - /// found. + /// By default, uv looks for packages in a virtual environment but will look for packages in a + /// system Python environment if no virtual environment is found. /// - /// See `uv help python` for details on Python discovery and supported - /// request formats. + /// See `uv help python` for details on Python discovery and supported request formats. #[arg( long, short, @@ -2141,12 +2121,10 @@ pub struct PipTreeArgs { /// The Python interpreter for which packages should be listed. /// - /// By default, uv lists packages in a virtual environment but will show - /// packages in a system Python environment if no virtual environment is - /// found. + /// By default, uv lists packages in a virtual environment but will show packages in a system + /// Python environment if no virtual environment is found. /// - /// See `uv help python` for details on Python discovery and supported - /// request formats. + /// See `uv help python` for details on Python discovery and supported request formats. #[arg( long, short, @@ -2247,8 +2225,7 @@ pub struct BuildArgs { #[arg(long, conflicts_with = "list")] pub force_pep517: bool, - /// Constrain build dependencies using the given requirements files when building - /// distributions. + /// Constrain build dependencies using the given requirements files when building distributions. /// /// Constraints files are `requirements.txt`-like files that only control the _version_ of a /// build dependency that's installed. However, including a package in a constraints file will @@ -2300,9 +2277,9 @@ pub struct BuildArgs { /// The Python interpreter to use for the build environment. /// - /// By default, builds are executed in isolated virtual environments. The - /// discovered interpreter will be used to create those environments, and - /// will be symlinked or copied in depending on the platform. + /// By default, builds are executed in isolated virtual environments. The discovered interpreter + /// will be used to create those environments, and will be symlinked or copied in depending on + /// the platform. /// /// See `uv help python` to view supported request formats. #[arg( @@ -2330,11 +2307,10 @@ pub struct BuildArgs { pub struct VenvArgs { /// The Python interpreter to use for the virtual environment. /// - /// During virtual environment creation, uv will not look for Python - /// interpreters in virtual environments. + /// During virtual environment creation, uv will not look for Python interpreters in virtual + /// environments. /// - /// See `uv help python` for details on Python discovery and supported - /// request formats. + /// See `uv help python` for details on Python discovery and supported request formats. #[arg( long, short, @@ -2359,8 +2335,8 @@ pub struct VenvArgs { /// This flag is included for compatibility only, it has no effect. /// - /// uv will never search for interpreters in virtual environments when - /// creating a virtual environment. + /// uv will never search for interpreters in virtual environments when creating a virtual + /// environment. #[arg(long, overrides_with("system"), hide = true)] pub no_system: bool, @@ -2385,8 +2361,8 @@ pub struct VenvArgs { /// `--allow-existing` option will instead write to the given path, regardless of its contents, /// and without clearing it beforehand. /// - /// WARNING: This option can lead to unexpected behavior if the existing virtual environment - /// and the newly-created virtual environment are linked to different Python interpreters. + /// WARNING: This option can lead to unexpected behavior if the existing virtual environment and + /// the newly-created virtual environment are linked to different Python interpreters. #[clap(long)] pub allow_existing: bool, @@ -2399,34 +2375,33 @@ pub struct VenvArgs { /// Provide an alternative prompt prefix for the virtual environment. /// - /// By default, the prompt is dependent on whether a path was provided to - /// `uv venv`. If provided (e.g, `uv venv project`), the prompt is set to - /// the directory name. If not provided (`uv venv`), the prompt is set to - /// the current directory's name. + /// By default, the prompt is dependent on whether a path was provided to `uv venv`. If provided + /// (e.g, `uv venv project`), the prompt is set to the directory name. If not provided + /// (`uv venv`), the prompt is set to the current directory's name. /// - /// If "." is provided, the current directory name will be used regardless - /// of whether a path was provided to `uv venv`. + /// If "." is provided, the current directory name will be used regardless of whether a path was + /// provided to `uv venv`. #[arg(long, verbatim_doc_comment)] pub prompt: Option, /// 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 - /// _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 will not affect the - /// behavior of uv commands. + /// _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 will not affect the behavior of + /// uv commands. #[arg(long)] pub system_site_packages: bool, /// Make the virtual environment relocatable. /// - /// A relocatable virtual environment can be moved around and redistributed without - /// invalidating its associated entrypoint and activation scripts. + /// A relocatable virtual environment can be moved around and redistributed without invalidating + /// its associated entrypoint and activation scripts. /// /// Note that this can only be guaranteed for standard `console_scripts` and `gui_scripts`. - /// Other scripts may be adjusted if they ship with a generic `#!python[w]` shebang, - /// and binaries are left as-is. + /// Other scripts may be adjusted if they ship with a generic `#!python[w]` shebang, and + /// binaries are left as-is. /// /// As a result of making the environment relocatable (by way of writing relative, rather than /// absolute paths), the entrypoints and scripts themselves will _not_ be relocatable. In other @@ -2449,8 +2424,8 @@ pub struct VenvArgs { /// Attempt to use `keyring` for authentication for index URLs. /// - /// At present, only `--keyring-provider subprocess` is supported, which configures uv to - /// use the `keyring` CLI to handle authentication. + /// At present, only `--keyring-provider subprocess` is supported, which configures uv to use + /// the `keyring` CLI to handle authentication. /// /// Defaults to `disabled`. #[arg(long, value_enum, env = EnvVars::UV_KEYRING_PROVIDER)] @@ -2528,12 +2503,12 @@ pub enum AuthorFrom { pub struct InitArgs { /// The path to use for the project/script. /// - /// Defaults to the current working directory when initializing an app or library; - /// required when initializing a script. Accepts relative and absolute paths. + /// Defaults to the current working directory when initializing an app or library; required when + /// initializing a script. Accepts relative and absolute paths. /// - /// If a `pyproject.toml` is found in any of the parent directories of the - /// target path, the project will be added as a workspace member of the - /// parent, unless `--no-workspace` is provided. + /// If a `pyproject.toml` is found in any of the parent directories of the target path, the + /// project will be added as a workspace member of the parent, unless `--no-workspace` is + /// provided. #[arg(required_if_eq("script", "true"))] pub path: Option, @@ -2621,24 +2596,22 @@ pub struct InitArgs { /// Fill in the `authors` field in the `pyproject.toml`. /// - /// By default, uv will attempt to infer the author information from some sources (e.g., Git) (`auto`). - /// Use `--author-from git` to only infer from Git configuration. - /// Use `--author-from none` to avoid inferring the author information. + /// By default, uv will attempt to infer the author information from some sources (e.g., Git) + /// (`auto`). Use `--author-from git` to only infer from Git configuration. Use `--author-from + /// none` to avoid inferring the author information. #[arg(long, value_enum)] pub author_from: Option, /// Do not create a `.python-version` file for the project. /// - /// By default, uv will create a `.python-version` file containing the minor version of - /// the discovered Python interpreter, which will cause subsequent uv commands to use that - /// version. + /// By default, uv will create a `.python-version` file containing the minor version of the + /// discovered Python interpreter, which will cause subsequent uv commands to use that version. #[arg(long)] pub no_pin_python: bool, /// Avoid discovering a workspace and create a standalone project. /// - /// By default, uv searches for workspaces in the current directory or any - /// parent directory. + /// By default, uv searches for workspaces in the current directory or any parent directory. #[arg(long, alias = "no-project")] pub no_workspace: bool, @@ -2663,8 +2636,7 @@ pub struct RunArgs { /// /// May be provided more than once. /// - /// Optional dependencies are defined via `project.optional-dependencies` in - /// a `pyproject.toml`. + /// Optional dependencies are defined via `project.optional-dependencies` in a `pyproject.toml`. /// /// This option is only available when running in a project. #[arg(long, conflicts_with = "all_extras", value_parser = extra_name_with_clap_error)] @@ -2672,8 +2644,7 @@ pub struct RunArgs { /// Include all optional dependencies. /// - /// Optional dependencies are defined via `project.optional-dependencies` in - /// a `pyproject.toml`. + /// Optional dependencies are defined via `project.optional-dependencies` in a `pyproject.toml`. /// /// This option is only available when running in a project. #[arg(long, conflicts_with = "extra")] @@ -2764,15 +2735,15 @@ pub struct RunArgs { /// Perform an exact sync, removing extraneous packages. /// - /// When enabled, uv will remove any extraneous packages from the environment. - /// By default, `uv run` will make the minimum necessary changes to satisfy the requirements. + /// When enabled, uv will remove any extraneous packages from the environment. By default, `uv + /// run` will make the minimum necessary changes to satisfy the requirements. #[arg(long, overrides_with("inexact"))] pub exact: bool, /// Load environment variables from a `.env` file. /// - /// Can be provided multiple times, with subsequent files overriding values defined in - /// previous files. + /// Can be provided multiple times, with subsequent files overriding values defined in previous + /// files. #[arg(long, env = EnvVars::UV_ENV_FILE)] pub env_file: Vec, @@ -2789,17 +2760,17 @@ pub struct RunArgs { /// Run with the given packages installed. /// - /// When used in a project, these dependencies will be layered on top of - /// the project environment in a separate, ephemeral environment. These - /// dependencies are allowed to conflict with those specified by the project. + /// When used in a project, these dependencies will be layered on top of the project environment + /// in a separate, ephemeral environment. These dependencies are allowed to conflict with those + /// specified by the project. #[arg(long)] pub with: Vec, /// Run with the given packages installed as editables. /// - /// When used in a project, these dependencies will be layered on top of - /// the project environment in a separate, ephemeral environment. These - /// dependencies are allowed to conflict with those specified by the project. + /// When used in a project, these dependencies will be layered on top of the project environment + /// in a separate, ephemeral environment. These dependencies are allowed to conflict with those + /// specified by the project. #[arg(long)] pub with_editable: Vec, @@ -2813,14 +2784,14 @@ pub struct RunArgs { /// Run the command in an isolated virtual environment. /// - /// Usually, the project environment is reused for performance. This option - /// forces a fresh environment to be used for the project, enforcing strict - /// isolation between dependencies and declaration of requirements. + /// Usually, the project environment is reused for performance. This option forces a fresh + /// environment to be used for the project, enforcing strict isolation between dependencies and + /// declaration of requirements. /// /// An editable installation is still used for the project. /// - /// When used with `--with` or `--with-requirements`, the additional - /// dependencies will still be layered in a second environment. + /// When used with `--with` or `--with-requirements`, the additional dependencies will still be + /// layered in a second environment. #[arg(long)] pub isolated: bool, @@ -2840,11 +2811,10 @@ pub struct RunArgs { /// Run without updating the `uv.lock` file. /// - /// Instead of checking if the lockfile is up-to-date, uses the versions in - /// the lockfile as the source of truth. If the lockfile is missing, uv will - /// exit with an error. If the `pyproject.toml` includes changes to - /// dependencies that have not been included in the lockfile yet, they will - /// not be present in the environment. + /// Instead of checking if the lockfile is up-to-date, uses the versions in the lockfile as the + /// source of truth. If the lockfile is missing, uv will exit with an error. If the + /// `pyproject.toml` includes changes to dependencies that have not been included in the + /// lockfile yet, they will not be present in the environment. #[arg(long, env = EnvVars::UV_FROZEN, value_parser = clap::builder::BoolishValueParser::new(), conflicts_with = "locked")] pub frozen: bool, @@ -2857,8 +2827,8 @@ pub struct RunArgs { /// Run the given path as a Python GUI script. /// - /// Using `--gui-script` will attempt to parse the path as a PEP 723 script and run it with pythonw.exe, - /// irrespective of its extension. Only available on Windows. + /// Using `--gui-script` will attempt to parse the path as a PEP 723 script and run it with + /// `pythonw.exe`, irrespective of its extension. Only available on Windows. #[arg(long, conflicts_with_all = ["script", "module"])] pub gui_script: bool, @@ -2873,11 +2843,10 @@ pub struct RunArgs { /// Run the command with all workspace members installed. /// - /// The workspace's environment (`.venv`) is updated to include all workspace - /// members. + /// The workspace's environment (`.venv`) is updated to include all workspace members. /// - /// Any extras or groups specified via `--extra`, `--group`, or related options - /// will be applied to all workspace members. + /// Any extras or groups specified via `--extra`, `--group`, or related options will be applied + /// to all workspace members. #[arg(long, conflicts_with = "package")] pub all_packages: bool, @@ -2889,19 +2858,18 @@ pub struct RunArgs { /// Avoid discovering the project or workspace. /// - /// Instead of searching for projects in the current directory and parent - /// directories, run in an isolated, ephemeral environment populated by the - /// `--with` requirements. + /// Instead of searching for projects in the current directory and parent directories, run in an + /// isolated, ephemeral environment populated by the `--with` requirements. /// - /// If a virtual environment is active or found in a current or parent - /// directory, it will be used as if there was no project or workspace. + /// If a virtual environment is active or found in a current or parent directory, it will be + /// used as if there was no project or workspace. #[arg(long, alias = "no_workspace", conflicts_with = "package")] pub no_project: bool, /// The Python interpreter to use for the run environment. /// - /// If the interpreter request is satisfied by a discovered environment, the - /// environment will be used. + /// If the interpreter request is satisfied by a discovered environment, the environment will be + /// used. /// /// See `uv help python` to view supported request formats. #[arg( @@ -2928,8 +2896,8 @@ pub struct SyncArgs { /// /// May be provided more than once. /// - /// When multiple extras or groups are specified that appear in - /// `tool.uv.conflicts`, uv will report an error. + /// When multiple extras or groups are specified that appear in `tool.uv.conflicts`, uv will + /// report an error. /// /// Note that all optional dependencies are always included in the resolution; this option only /// affects the selection of packages to install. @@ -2938,8 +2906,8 @@ pub struct SyncArgs { /// Include all optional dependencies. /// - /// When two or more extras are declared as conflicting in - /// `tool.uv.conflicts`, using this flag will always result in an error. + /// When two or more extras are declared as conflicting in `tool.uv.conflicts`, using this flag + /// will always result in an error. /// /// Note that all optional dependencies are always included in the resolution; this option only /// affects the selection of packages to install. @@ -3029,10 +2997,10 @@ pub struct SyncArgs { /// Do not install the current project. /// /// By default, the current project is installed into the environment with all of its - /// dependencies. The `--no-install-project` option allows the project to be excluded, but all of - /// its dependencies are still installed. This is particularly useful in situations like - /// building Docker images where installing the project separately from its dependencies - /// allows optimal layer caching. + /// dependencies. The `--no-install-project` option allows the project to be excluded, but all + /// of its dependencies are still installed. This is particularly useful in situations like + /// building Docker images where installing the project separately from its dependencies allows + /// optimal layer caching. #[arg(long)] pub no_install_project: bool, @@ -3056,18 +3024,17 @@ pub struct SyncArgs { /// Assert that the `uv.lock` will remain unchanged. /// - /// Requires that the lockfile is up-to-date. If the lockfile is missing or - /// needs to be updated, uv will exit with an error. + /// Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, + /// uv will exit with an error. #[arg(long, env = EnvVars::UV_LOCKED, value_parser = clap::builder::BoolishValueParser::new(), conflicts_with_all = ["frozen", "upgrade"])] pub locked: bool, /// Sync without updating the `uv.lock` file. /// - /// Instead of checking if the lockfile is up-to-date, uses the versions in - /// the lockfile as the source of truth. If the lockfile is missing, uv will - /// exit with an error. If the `pyproject.toml` includes changes to dependencies - /// that have not been included in the lockfile yet, they will not be - /// present in the environment. + /// Instead of checking if the lockfile is up-to-date, uses the versions in the lockfile as the + /// source of truth. If the lockfile is missing, uv will exit with an error. If the + /// `pyproject.toml` includes changes to dependencies that have not been included in the + /// lockfile yet, they will not be present in the environment. #[arg(long, env = EnvVars::UV_FROZEN, value_parser = clap::builder::BoolishValueParser::new(), conflicts_with = "locked")] pub frozen: bool, @@ -3082,18 +3049,17 @@ pub struct SyncArgs { /// Sync all packages in the workspace. /// - /// The workspace's environment (`.venv`) is updated to include all workspace - /// members. + /// The workspace's environment (`.venv`) is updated to include all workspace members. /// - /// Any extras or groups specified via `--extra`, `--group`, or related options - /// will be applied to all workspace members. + /// Any extras or groups specified via `--extra`, `--group`, or related options will be applied + /// to all workspace members. #[arg(long, conflicts_with = "package")] pub all_packages: bool, /// Sync for a specific package in the workspace. /// - /// The workspace's environment (`.venv`) is updated to reflect the subset - /// of dependencies declared by the specified workspace member package. + /// The workspace's environment (`.venv`) is updated to reflect the subset of dependencies + /// declared by the specified workspace member package. /// /// If the workspace member does not exist, uv will exit with an error. #[arg(long, conflicts_with = "all_packages")] @@ -3101,15 +3067,14 @@ pub struct SyncArgs { /// The Python interpreter to use for the project environment. /// - /// By default, the first interpreter that meets the project's - /// `requires-python` constraint is used. + /// By default, the first interpreter that meets the project's `requires-python` constraint is + /// used. /// - /// If a Python interpreter in a virtual environment is provided, the - /// packages will not be synced to the given environment. The interpreter - /// will be used to create a virtual environment in the project. + /// If a Python interpreter in a virtual environment is provided, the packages will not be + /// synced to the given environment. The interpreter will be used to create a virtual + /// environment in the project. /// - /// See `uv help python` for details on Python discovery and supported - /// request formats. + /// See `uv help python` for details on Python discovery and supported request formats. #[arg( long, short, @@ -3164,14 +3129,13 @@ pub struct LockArgs { /// The Python interpreter to use during resolution. /// - /// A Python interpreter is required for building source distributions to - /// determine package metadata when there are not wheels. + /// A Python interpreter is required for building source distributions to determine package + /// metadata when there are not wheels. /// - /// The interpreter is also used as the fallback value for the minimum - /// Python version if `requires-python` is not set. + /// The interpreter is also used as the fallback value for the minimum Python version if + /// `requires-python` is not set. /// - /// See `uv help python` for details on Python discovery and supported - /// request formats. + /// See `uv help python` for details on Python discovery and supported request formats. #[arg( long, short, @@ -3203,8 +3167,7 @@ pub struct AddArgs { /// Add the requirements to the package's optional dependencies for the specified extra. /// - /// The group may then be activated when installing the project with the - /// `--extra` flag. + /// The group may then be activated when installing the project with the `--extra` flag. /// /// To enable an optional extra for this requirement instead, see `--extra`. #[arg(long, conflicts_with("dev"), conflicts_with("group"))] @@ -3263,8 +3226,8 @@ pub struct AddArgs { /// Assert that the `uv.lock` will remain unchanged. /// - /// Requires that the lockfile is up-to-date. If the lockfile is missing or - /// needs to be updated, uv will exit with an error. + /// Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, + /// uv will exit with an error. #[arg(long, env = EnvVars::UV_LOCKED, value_parser = clap::builder::BoolishValueParser::new(), conflicts_with_all = ["frozen", "upgrade"])] pub locked: bool, @@ -3289,11 +3252,10 @@ pub struct AddArgs { /// Add the dependency to the specified Python script, rather than to a project. /// - /// If provided, uv will add the dependency to the script's inline metadata - /// table, in adherence with PEP 723. If no such inline metadata table is present, - /// a new one will be created and added to the script. When executed via `uv run`, - /// uv will create a temporary environment for the script with all inline - /// dependencies installed. + /// If provided, uv will add the dependency to the script's inline metadata table, in adherence + /// with PEP 723. If no such inline metadata table is present, a new one will be created and + /// added to the script. When executed via `uv run`, uv will create a temporary environment for + /// the script with all inline dependencies installed. #[arg( long, conflicts_with = "dev", @@ -3304,8 +3266,7 @@ pub struct AddArgs { /// The Python interpreter to use for resolving and syncing. /// - /// See `uv help python` for details on Python discovery and supported - /// request formats. + /// See `uv help python` for details on Python discovery and supported request formats. #[arg( long, short, @@ -3344,8 +3305,8 @@ pub struct RemoveArgs { /// Assert that the `uv.lock` will remain unchanged. /// - /// Requires that the lockfile is up-to-date. If the lockfile is missing or - /// needs to be updated, uv will exit with an error. + /// Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, + /// uv will exit with an error. #[arg(long, env = EnvVars::UV_LOCKED, value_parser = clap::builder::BoolishValueParser::new(), conflicts_with_all = ["frozen", "upgrade"])] pub locked: bool, @@ -3370,15 +3331,14 @@ pub struct RemoveArgs { /// Remove the dependency from the specified Python script, rather than from a project. /// - /// If provided, uv will remove the dependency from the script's inline metadata - /// table, in adherence with PEP 723. + /// If provided, uv will remove the dependency from the script's inline metadata table, in + /// adherence with PEP 723. #[arg(long)] pub script: Option, /// The Python interpreter to use for resolving and syncing. /// - /// See `uv help python` for details on Python discovery and supported - /// request formats. + /// See `uv help python` for details on Python discovery and supported request formats. #[arg( long, short, @@ -3395,9 +3355,8 @@ pub struct RemoveArgs { pub struct TreeArgs { /// Show a platform-independent dependency tree. /// - /// Shows resolved package versions for all Python versions and platforms, - /// rather than filtering to those that are relevant for the current - /// environment. + /// Shows resolved package versions for all Python versions and platforms, rather than filtering + /// to those that are relevant for the current environment. /// /// Multiple versions may be shown for a each package. #[arg(long)] @@ -3463,8 +3422,8 @@ pub struct TreeArgs { /// Assert that the `uv.lock` will remain unchanged. /// - /// Requires that the lockfile is up-to-date. If the lockfile is missing or - /// needs to be updated, uv will exit with an error. + /// Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, + /// uv will exit with an error. #[arg(long, env = EnvVars::UV_LOCKED, value_parser = clap::builder::BoolishValueParser::new(), conflicts_with_all = ["frozen", "upgrade"])] pub locked: bool, @@ -3490,8 +3449,8 @@ pub struct TreeArgs { /// The Python version to use when filtering the tree. /// - /// For example, pass `--python-version 3.10` to display the dependencies - /// that would be included when installing on Python 3.10. + /// For example, pass `--python-version 3.10` to display the dependencies that would be included + /// when installing on Python 3.10. /// /// Defaults to the version of the discovered Python interpreter. #[arg(long, conflicts_with = "universal")] @@ -3499,24 +3458,22 @@ pub struct TreeArgs { /// The platform to use when filtering the tree. /// - /// For example, pass `--platform windows` to display the dependencies that - /// would be included when installing on Windows. + /// For example, pass `--platform windows` to display the dependencies that would be included + /// when installing on Windows. /// - /// Represented as a "target triple", a string that describes the target - /// platform in terms of its CPU, vendor, and operating system name, like - /// `x86_64-unknown-linux-gnu` or `aarch64-apple-darwin`. + /// Represented as a "target triple", a string that describes the target platform in terms of + /// its CPU, vendor, and operating system name, like `x86_64-unknown-linux-gnu` or + /// `aarch64-apple-darwin`. #[arg(long, conflicts_with = "universal")] pub python_platform: Option, /// The Python interpreter to use for locking and filtering. /// - /// By default, the tree is filtered to match the platform as reported by - /// the Python interpreter. Use `--universal` to display the tree for all - /// platforms, or use `--python-version` or `--python-platform` to override - /// a subset of markers. + /// By default, the tree is filtered to match the platform as reported by the Python + /// interpreter. Use `--universal` to display the tree for all platforms, or use + /// `--python-version` or `--python-platform` to override a subset of markers. /// - /// See `uv help python` for details on Python discovery and supported - /// request formats. + /// See `uv help python` for details on Python discovery and supported request formats. #[arg( long, short, @@ -3539,11 +3496,11 @@ pub struct ExportArgs { /// Export the entire workspace. /// - /// The dependencies for all workspace members will be included in the - /// exported requirements file. + /// The dependencies for all workspace members will be included in the exported requirements + /// file. /// - /// Any extras or groups specified via `--extra`, `--group`, or related options - /// will be applied to all workspace members. + /// Any extras or groups specified via `--extra`, `--group`, or related options will be applied + /// to all workspace members. #[arg(long, conflicts_with = "package")] pub all_packages: bool, @@ -3657,9 +3614,9 @@ pub struct ExportArgs { /// Do not emit the current project. /// - /// By default, the current project is included in the exported requirements file with all of its - /// dependencies. The `--no-emit-project` option allows the project to be excluded, but all of - /// its dependencies to remain included. + /// By default, the current project is included in the exported requirements file with all of + /// its dependencies. The `--no-emit-project` option allows the project to be excluded, but all + /// of its dependencies to remain included. #[arg(long, alias = "no-install-project")] pub no_emit_project: bool, @@ -3680,8 +3637,8 @@ pub struct ExportArgs { /// Assert that the `uv.lock` will remain unchanged. /// - /// Requires that the lockfile is up-to-date. If the lockfile is missing or - /// needs to be updated, uv will exit with an error. + /// Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, + /// uv will exit with an error. #[arg(long, env = EnvVars::UV_LOCKED, value_parser = clap::builder::BoolishValueParser::new(), conflicts_with_all = ["frozen", "upgrade"])] pub locked: bool, @@ -3710,14 +3667,13 @@ pub struct ExportArgs { /// The Python interpreter to use during resolution. /// - /// A Python interpreter is required for building source distributions to - /// determine package metadata when there are not wheels. + /// A Python interpreter is required for building source distributions to determine package + /// metadata when there are not wheels. /// - /// The interpreter is also used as the fallback value for the minimum - /// Python version if `requires-python` is not set. + /// The interpreter is also used as the fallback value for the minimum Python version if + /// `requires-python` is not set. /// - /// See `uv help python` for details on Python discovery and supported - /// request formats. + /// See `uv help python` for details on Python discovery and supported request formats. #[arg( long, short, @@ -3742,22 +3698,18 @@ pub enum ToolCommand { /// /// By default, the package to install is assumed to match the command name. /// - /// The name of the command can include an exact version in the format - /// `@`, e.g., `uv tool run ruff@0.3.0`. If more complex - /// version specification is desired or if the command is provided by a - /// different package, use `--from`. + /// The name of the command can include an exact version in the format `@`, + /// e.g., `uv tool run ruff@0.3.0`. If more complex version specification is desired or if the + /// command is provided by a different package, use `--from`. /// - /// If the tool was previously installed, i.e., via `uv tool install`, the - /// installed version will be used unless a version is requested or the - /// `--isolated` flag is used. + /// If the tool was previously installed, i.e., via `uv tool install`, the installed version + /// will be used unless a version is requested or the `--isolated` flag is used. /// - /// `uvx` is provided as a convenient alias for `uv tool run`, their - /// behavior is identical. + /// `uvx` is provided as a convenient alias for `uv tool run`, their behavior is identical. /// /// If no command is provided, the installed tools are displayed. /// - /// Packages are installed into an ephemeral virtual environment in the uv - /// cache directory. + /// Packages are installed into an ephemeral virtual environment in the uv cache directory. #[command( after_help = "Use `uvx` as a shortcut for `uv tool run`.\n\n\ Use `uv help tool run` for more details.", @@ -3775,23 +3727,20 @@ pub enum ToolCommand { Uvx(ToolRunArgs), /// Install commands provided by a Python package. /// - /// Packages are installed into an isolated virtual environment in the uv - /// tools directory. The executables are linked the tool executable - /// directory, which is determined according to the XDG standard and can be - /// retrieved with `uv tool dir --bin`. + /// Packages are installed into an isolated virtual environment in the uv tools directory. The + /// executables are linked the tool executable directory, which is determined according to the + /// XDG standard and can be retrieved with `uv tool dir --bin`. /// - /// If the tool was previously installed, the existing tool will generally - /// be replaced. + /// If the tool was previously installed, the existing tool will generally be replaced. Install(ToolInstallArgs), /// Upgrade installed tools. /// - /// If a tool was installed with version constraints, they will be respected - /// on upgrade — to upgrade a tool beyond the originally provided - /// constraints, use `uv tool install` again. + /// If a tool was installed with version constraints, they will be respected on upgrade — to + /// upgrade a tool beyond the originally provided constraints, use `uv tool install` again. /// - /// If a tool was installed with specific settings, they will be respected - /// on upgraded. For example, if `--prereleases allow` was provided during - /// installation, it will continue to be respected in upgrades. + /// If a tool was installed with specific settings, they will be respected on upgraded. For + /// example, if `--prereleases allow` was provided during installation, it will continue to be + /// respected in upgrades. #[command(alias = "update")] Upgrade(ToolUpgradeArgs), /// List installed tools. @@ -3801,15 +3750,14 @@ pub enum ToolCommand { Uninstall(ToolUninstallArgs), /// Ensure that the tool executable directory is on the `PATH`. /// - /// If the tool executable directory is not present on the `PATH`, uv will - /// attempt to add it to the relevant shell configuration files. + /// If the tool executable directory is not present on the `PATH`, uv will attempt to add it to + /// the relevant shell configuration files. /// - /// If the shell configuration files already include a blurb to add the - /// executable directory to the path, but the directory is not present on - /// the `PATH`, uv will exit with an error. + /// If the shell configuration files already include a blurb to add the executable directory to + /// the path, but the directory is not present on the `PATH`, uv will exit with an error. /// - /// The tool executable directory is determined according to the XDG standard - /// and can be retrieved with `uv tool dir --bin`. + /// The tool executable directory is determined according to the XDG standard and can be + /// retrieved with `uv tool dir --bin`. #[command(alias = "ensurepath")] UpdateShell, /// Show the path to the uv tools directory. @@ -3817,8 +3765,7 @@ pub enum ToolCommand { /// The tools directory is used to store environments and metadata for installed tools. /// /// By default, tools are stored in the uv data directory at `$XDG_DATA_HOME/uv/tools` or - /// `$HOME/.local/share/uv/tools` on Unix and `%APPDATA%\uv\data\tools` on - /// Windows. + /// `$HOME/.local/share/uv/tools` on Unix and `%APPDATA%\uv\data\tools` on Windows. /// /// The tool installation directory may be overridden with `$UV_TOOL_DIR`. /// @@ -3847,9 +3794,9 @@ pub struct ToolRunArgs { /// Run with the given packages installed as editables /// - /// When used in a project, these dependencies will be layered on top of - /// the uv tool's environment in a separate, ephemeral environment. These - /// dependencies are allowed to conflict with those specified. + /// When used in a project, these dependencies will be layered on top of the uv tool's + /// environment in a separate, ephemeral environment. These dependencies are allowed to conflict + /// with those specified. #[arg(long)] pub with_editable: Vec, @@ -3872,8 +3819,7 @@ pub struct ToolRunArgs { /// The Python interpreter to use to build the run environment. /// - /// See `uv help python` for details on Python discovery and supported - /// request formats. + /// See `uv help python` for details on Python discovery and supported request formats. #[arg( long, short, @@ -3960,8 +3906,7 @@ pub struct ToolInstallArgs { /// The Python interpreter to use to build the tool environment. /// - /// See `uv help python` for details on Python discovery and supported - /// request formats. + /// See `uv help python` for details on Python discovery and supported request formats. #[arg( long, short, @@ -4034,11 +3979,10 @@ pub struct ToolUpgradeArgs { #[arg(long, conflicts_with("name"))] pub all: bool, - /// Upgrade a tool, and specify it to use the given Python interpreter - /// to build its environment. Use with `--all` to apply to all tools. + /// Upgrade a tool, and specify it to use the given Python interpreter to build its environment. + /// Use with `--all` to apply to all tools. /// - /// See `uv help python` for details on Python discovery and supported - /// request formats. + /// See `uv help python` for details on Python discovery and supported request formats. #[arg( long, short, @@ -4049,8 +3993,8 @@ pub struct ToolUpgradeArgs { )] pub python: Option>, - // The following is equivalent to flattening `ResolverInstallerArgs`, with the `--upgrade`, - // and `--upgrade-package` options hidden, and the `--no-upgrade` option removed. + // The following is equivalent to flattening `ResolverInstallerArgs`, with the `--upgrade`, and + // `--upgrade-package` options hidden, and the `--no-upgrade` option removed. /// Allow package upgrades, ignoring pinned versions in any existing output file. Implies /// `--refresh`. #[arg(hide = true, long, short = 'U', help_heading = "Resolver options")] @@ -4089,10 +4033,10 @@ pub struct ToolUpgradeArgs { /// The strategy to use when resolving against multiple index URLs. /// - /// By default, uv will stop at the first index on which a given package is available, and - /// limit resolutions to those present on that first index (`first-index`). This prevents - /// "dependency confusion" attacks, whereby an attacker can upload a malicious package under the - /// same name to an alternate index. + /// By default, uv will stop at the first index on which a given package is available, and limit + /// resolutions to those present on that first index (`first-index`). This prevents "dependency + /// confusion" attacks, whereby an attacker can upload a malicious package under the same name + /// to an alternate index. #[arg( long, value_enum, @@ -4103,8 +4047,8 @@ pub struct ToolUpgradeArgs { /// Attempt to use `keyring` for authentication for index URLs. /// - /// At present, only `--keyring-provider subprocess` is supported, which configures uv to - /// use the `keyring` CLI to handle authentication. + /// At present, only `--keyring-provider subprocess` is supported, which configures uv to use + /// the `keyring` CLI to handle authentication. /// /// Defaults to `disabled`. #[arg( @@ -4129,9 +4073,9 @@ pub struct ToolUpgradeArgs { /// The strategy to use when considering pre-release versions. /// - /// 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`). + /// 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, @@ -4265,12 +4209,11 @@ pub struct PythonNamespace { pub enum PythonCommand { /// List the available Python installations. /// - /// By default, installed Python versions and the downloads for latest - /// available patch version of each supported Python major version are - /// shown. + /// By default, installed Python versions and the downloads for latest available patch version + /// of each supported Python major version are shown. /// - /// The displayed versions are filtered by the `--python-preference` option, - /// i.e., if using `only-system`, no managed Python versions will be shown. + /// The displayed versions are filtered by the `--python-preference` option, i.e., if using + /// `only-system`, no managed Python versions will be shown. /// /// Use `--all-versions` to view all available patch versions. /// @@ -4289,8 +4232,8 @@ pub enum PythonCommand { /// python dir`. /// /// A `python` executable is not made globally available, managed Python versions are only used - /// in uv commands or in active virtual environments. There is experimental support for - /// adding Python executables to the `PATH` — use the `--preview` flag to enable this behavior. + /// in uv commands or in active virtual environments. There is experimental support for adding + /// Python executables to the `PATH` — use the `--preview` flag to enable this behavior. /// /// See `uv help python` to view supported request formats. Install(PythonInstallArgs), @@ -4299,8 +4242,7 @@ pub enum PythonCommand { /// /// Displays the path to the Python executable. /// - /// See `uv help python` to view supported request formats and details on - /// discovery behavior. + /// See `uv help python` to view supported request formats and details on discovery behavior. Find(PythonFindArgs), /// Pin to a specific Python version. @@ -4398,8 +4340,8 @@ pub struct PythonDirArgs { pub struct PythonInstallArgs { /// The directory to store the Python installation in. /// - /// If provided, `UV_PYTHON_INSTALL_DIR` will need to be set for subsequent operations for - /// uv to discover the Python installation. + /// If provided, `UV_PYTHON_INSTALL_DIR` will need to be set for subsequent operations for uv to + /// discover the Python installation. /// /// See `uv python dir` to view the current Python installation directory. Defaults to /// `~/.local/share/uv/python`. @@ -4408,17 +4350,18 @@ pub struct PythonInstallArgs { /// The Python version(s) to install. /// - /// If not provided, the requested Python version(s) will be read from the - /// `.python-versions` or `.python-version` files. If neither file is - /// present, uv will check if it has installed any Python versions. If not, - /// it will install the latest stable version of Python. + /// If not provided, the requested Python version(s) will be read from the `.python-versions` or + /// `.python-version` files. If neither file is present, uv will check if it has installed any + /// Python versions. If not, it will install the latest stable version of Python. /// /// See `uv help python` to view supported request formats. pub targets: Vec, /// Set the URL to use as the source for downloading Python installations. /// - /// The provided URL will replace `https://github.com/astral-sh/python-build-standalone/releases/download` in, e.g., `https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz`. + /// The provided URL will replace + /// `https://github.com/astral-sh/python-build-standalone/releases/download` in, e.g., + /// `https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz`. /// /// Distributions can be read from a local directory by using the `file://` URL scheme. #[arg(long, env = EnvVars::UV_PYTHON_INSTALL_MIRROR)] @@ -4426,7 +4369,8 @@ pub struct PythonInstallArgs { /// Set the URL to use as the source for downloading 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`. + /// 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. #[arg(long, env = EnvVars::UV_PYPY_INSTALL_MIRROR)] @@ -4520,9 +4464,9 @@ pub struct PythonFindArgs { pub struct PythonPinArgs { /// The Python version request. /// - /// uv supports more formats than other tools that read `.python-version` - /// files, i.e., `pyenv`. If compatibility with those tools is needed, only - /// use version numbers instead of complex requests such as `cpython@3.10`. + /// uv supports more formats than other tools that read `.python-version` files, i.e., `pyenv`. + /// If compatibility with those tools is needed, only use version numbers instead of complex + /// requests such as `cpython@3.10`. /// /// If no request is provided, the currently pinned version will be shown. /// @@ -4533,8 +4477,8 @@ pub struct PythonPinArgs { /// /// Ensures that the exact same interpreter is used. /// - /// This option is usually not safe to use when committing the - /// `.python-version` file to version control. + /// This option is usually not safe to use when committing the `.python-version` file to version + /// control. #[arg(long, overrides_with("resolved"))] pub resolved: bool, @@ -4598,8 +4542,8 @@ pub struct IndexArgs { /// directory laid out in the same format. /// /// All indexes provided via this flag take priority over the index specified by - /// `--default-index` (which defaults to PyPI). When multiple `--index` flags are - /// provided, earlier values take priority. + /// `--default-index` (which defaults to PyPI). When multiple `--index` flags are provided, + /// earlier values take priority. #[arg(long, env = EnvVars::UV_INDEX, value_delimiter = ' ', value_parser = parse_index, help_heading = "Index options")] pub index: Option>>, @@ -4613,24 +4557,26 @@ pub struct IndexArgs { #[arg(long, env = EnvVars::UV_DEFAULT_INDEX, value_parser = parse_default_index, help_heading = "Index options")] pub default_index: Option>, - /// (Deprecated: use `--default-index` instead) The URL of the Python package index (by default: ). + /// (Deprecated: use `--default-index` instead) The URL of the Python package index (by default: + /// ). /// /// Accepts either a repository compliant with PEP 503 (the simple repository API), or a local /// directory laid out in the same format. /// - /// The index given by this flag is given lower priority than all other - /// indexes specified via the `--extra-index-url` flag. + /// The index given by this flag is given lower priority than all other indexes specified via + /// the `--extra-index-url` flag. #[arg(long, short, env = EnvVars::UV_INDEX_URL, value_parser = parse_index_url, help_heading = "Index options")] pub index_url: Option>, - /// (Deprecated: use `--index` instead) Extra URLs of package indexes to use, in addition to `--index-url`. + /// (Deprecated: use `--index` instead) Extra URLs of package indexes to use, in addition to + /// `--index-url`. /// /// Accepts either a repository compliant with PEP 503 (the simple repository API), or a local /// directory laid out in the same format. /// - /// All indexes provided via this flag take priority over the index specified by - /// `--index-url` (which defaults to PyPI). When multiple `--extra-index-url` flags are - /// provided, earlier values take priority. + /// All indexes provided via this flag take priority over the index specified by `--index-url` + /// (which defaults to PyPI). When multiple `--extra-index-url` flags are provided, earlier + /// values take priority. #[arg(long, env = EnvVars::UV_EXTRA_INDEX_URL, value_delimiter = ' ', value_parser = parse_extra_index_url, help_heading = "Index options")] pub extra_index_url: Option>>, @@ -4759,10 +4705,10 @@ 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 - /// limit resolutions to those present on that first index (`first-index`). This prevents - /// "dependency confusion" attacks, whereby an attacker can upload a malicious package under the - /// same name to an alternate index. + /// By default, uv will stop at the first index on which a given package is available, and limit + /// resolutions to those present on that first index (`first-index`). This prevents "dependency + /// confusion" attacks, whereby an attacker can upload a malicious package under the same name + /// to an alternate index. #[arg( long, value_enum, @@ -4773,8 +4719,8 @@ pub struct InstallerArgs { /// Attempt to use `keyring` for authentication for index URLs. /// - /// At present, only `--keyring-provider subprocess` is supported, which configures uv to - /// use the `keyring` CLI to handle authentication. + /// At present, only `--keyring-provider subprocess` is supported, which configures uv to use + /// the `keyring` CLI to handle authentication. /// /// Defaults to `disabled`. #[arg( @@ -4901,10 +4847,10 @@ 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 - /// limit resolutions to those present on that first index (`first-index`). This prevents - /// "dependency confusion" attacks, whereby an attacker can upload a malicious package under the - /// same name to an alternate index. + /// By default, uv will stop at the first index on which a given package is available, and limit + /// resolutions to those present on that first index (`first-index`). This prevents "dependency + /// confusion" attacks, whereby an attacker can upload a malicious package under the same name + /// to an alternate index. #[arg( long, value_enum, @@ -4915,8 +4861,8 @@ pub struct ResolverArgs { /// Attempt to use `keyring` for authentication for index URLs. /// - /// At present, only `--keyring-provider subprocess` is supported, which configures uv to - /// use the `keyring` CLI to handle authentication. + /// At present, only `--keyring-provider subprocess` is supported, which configures uv to use + /// the `keyring` CLI to handle authentication. /// /// Defaults to `disabled`. #[arg( @@ -4941,9 +4887,9 @@ pub struct ResolverArgs { /// The strategy to use when considering pre-release versions. /// - /// 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`). + /// 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, @@ -5061,8 +5007,8 @@ pub struct ResolverInstallerArgs { )] pub no_upgrade: bool, - /// Allow upgrades for a specific package, ignoring pinned versions in any existing output - /// file. Implies `--refresh-package`. + /// Allow upgrades for a specific package, ignoring pinned versions in any existing output file. + /// Implies `--refresh-package`. #[arg(long, short = 'P', help_heading = "Resolver options")] pub upgrade_package: Vec>, @@ -5091,10 +5037,10 @@ 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 - /// limit resolutions to those present on that first index (`first-index`). This prevents - /// "dependency confusion" attacks, whereby an attacker can upload a malicious package under the - /// same name to an alternate index. + /// By default, uv will stop at the first index on which a given package is available, and limit + /// resolutions to those present on that first index (`first-index`). This prevents "dependency + /// confusion" attacks, whereby an attacker can upload a malicious package under the same name + /// to an alternate index. #[arg( long, value_enum, @@ -5105,8 +5051,8 @@ pub struct ResolverInstallerArgs { /// Attempt to use `keyring` for authentication for index URLs. /// - /// At present, only `--keyring-provider subprocess` is supported, which configures uv to - /// use the `keyring` CLI to handle authentication. + /// At present, only `--keyring-provider subprocess` is supported, which configures uv to use + /// the `keyring` CLI to handle authentication. /// /// Defaults to `disabled`. #[arg( @@ -5131,9 +5077,9 @@ pub struct ResolverInstallerArgs { /// The strategy to use when considering pre-release versions. /// - /// 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`). + /// 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, @@ -5262,10 +5208,10 @@ pub struct FetchArgs { /// The strategy to use when resolving against multiple index URLs. /// - /// By default, uv will stop at the first index on which a given package is available, and - /// limit resolutions to those present on that first index (`first-index`). This prevents - /// "dependency confusion" attacks, whereby an attacker can upload a malicious package under the - /// same name to an alternate index. + /// By default, uv will stop at the first index on which a given package is available, and limit + /// resolutions to those present on that first index (`first-index`). This prevents "dependency + /// confusion" attacks, whereby an attacker can upload a malicious package under the same name + /// to an alternate index. #[arg( long, value_enum, @@ -5276,8 +5222,8 @@ pub struct FetchArgs { /// Attempt to use `keyring` for authentication for index URLs. /// - /// At present, only `--keyring-provider subprocess` is supported, which configures uv to - /// use the `keyring` CLI to handle authentication. + /// At present, only `--keyring-provider subprocess` is supported, which configures uv to use + /// the `keyring` CLI to handle authentication. /// /// Defaults to `disabled`. #[arg( @@ -5310,11 +5256,10 @@ pub struct DisplayTreeArgs { #[arg(long)] pub package: Vec, - /// Do not de-duplicate repeated dependencies. - /// Usually, when a package has already displayed its dependencies, - /// further occurrences will not re-display its dependencies, - /// and will include a (*) to indicate it has already been shown. - /// This flag will cause those duplicates to be repeated. + /// Do not de-duplicate repeated dependencies. Usually, when a package has already displayed its + /// dependencies, further occurrences will not re-display its dependencies, and will include a + /// (*) to indicate it has already been shown. This flag will cause those duplicates to be + /// repeated. #[arg(long)] pub no_dedupe: bool, @@ -5395,8 +5340,8 @@ pub struct PublishArgs { /// Attempt to use `keyring` for authentication for remote requirements files. /// - /// At present, only `--keyring-provider subprocess` is supported, which configures uv to - /// use the `keyring` CLI to handle authentication. + /// At present, only `--keyring-provider subprocess` is supported, which configures uv to use + /// the `keyring` CLI to handle authentication. /// /// Defaults to `disabled`. #[arg(long, value_enum, env = EnvVars::UV_KEYRING_PROVIDER)] diff --git a/docs/reference/cli.md b/docs/reference/cli.md index bf6e1364ce20..cd69b60181d9 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -205,7 +205,7 @@ uv run [OPTIONS] [COMMAND]
--gui-script

Run the given path as a Python GUI script.

-

Using --gui-script will attempt to parse the path as a PEP 723 script and run it with pythonw.exe, irrespective of its extension. Only available on Windows.

+

Using --gui-script will attempt to parse the path as a PEP 723 script and run it with pythonw.exe, irrespective of its extension. Only available on Windows.

--help, -h

Display the concise help for this command