From d6c587c21c5da338746762a0862c4ffecd2eec61 Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Fri, 9 Aug 2024 14:46:21 -0500 Subject: [PATCH] Improve the `uv python` CLI documentation (#5961) --- clippy.toml | 2 ++ crates/uv-cli/src/lib.rs | 63 +++++++++++++++++++++++++++++++++++++--- crates/uv/tests/help.rs | 23 +++++++++++++-- docs/reference/cli.md | 61 ++++++++++++++++++++++++++++++++------ 4 files changed, 134 insertions(+), 15 deletions(-) diff --git a/clippy.toml b/clippy.toml index c001d2ee6..7d1593c64 100644 --- a/clippy.toml +++ b/clippy.toml @@ -2,6 +2,8 @@ doc-valid-idents = [ "PyPI", "PubGrub", "PyPy", + "CPython", + "GraalPy", ".." # Include the defaults ] diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs index 8d210c0d7..49c833954 100644 --- a/crates/uv-cli/src/lib.rs +++ b/crates/uv-cli/src/lib.rs @@ -246,6 +246,7 @@ pub enum Commands { /// Manage Python projects. #[command(flatten)] Project(Box), + /// Run and manage tools provided by Python packages (experimental). #[command( after_help = "Use `uv help tool` for more details.", @@ -293,6 +294,11 @@ pub enum Commands { /// e.g., if `pypy` is requested, uv will first check if the virtual /// environment contains a PyPy interpreter then check if each executable in /// the path is a PyPy interpreter. + /// + /// uv supports discovering CPython, PyPy, and GraalPy interpreters. + /// Unsupported interpreters will be skipped during discovery. If an + /// unsupported interpreter implementation is requested, uv will exit with + /// an error. #[clap(verbatim_doc_comment)] #[command( after_help = "Use `uv help python` for more details.", @@ -2773,15 +2779,49 @@ pub struct PythonNamespace { #[derive(Subcommand)] 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. + /// + /// 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. + /// + /// Use `--only-installed` to omit available downloads. List(PythonListArgs), /// Download and install Python versions. + /// + /// Multiple Python versions may be requested. + /// + /// Supports CPython and PyPy. + /// + /// CPython distributions are downloaded from the `python-build-standalone` project. + /// + /// Python versions are installed into the uv Python directory, which can be + /// retrieved with `uv python dir`. A `python` executable is not made + /// globally available, managed Python versions are only used in uv + /// commands or in active virtual environments. + /// + /// See `uv help python` to view supported request formats. Install(PythonInstallArgs), /// Search for a Python installation. + /// + /// Displays the path to the Python executable. + /// + /// See `uv help python` to view supported request formats and details on + /// discovery behavior. Find(PythonFindArgs), /// Pin to a specific Python version. + /// + /// Writes the pinned version to a `.python-version` file, which is then + /// read by other uv commands when determining the required Python version. + /// + /// See `uv help python` to view supported request formats. Pin(PythonPinArgs), /// Show the uv Python installation directory. @@ -2794,15 +2834,21 @@ pub enum PythonCommand { #[derive(Args)] #[allow(clippy::struct_excessive_bools)] pub struct PythonListArgs { - /// List all Python versions, including outdated patch versions. + /// List all Python versions, including old patch versions. + /// + /// By default, only the latest patch version is shown for each minor version. #[arg(long)] pub all_versions: bool, - /// List Python installations for all platforms. + /// List Python downloads for all platforms. + /// + /// By default, only downloads for the current platform are shown. #[arg(long)] pub all_platforms: bool, /// Only show installed Python versions, exclude available downloads. + /// + /// By default, available downloads for the current platform are shown. #[arg(long)] pub only_installed: bool, } @@ -2821,6 +2867,9 @@ pub struct PythonInstallArgs { pub targets: Vec, /// Reinstall the requested Python version, if it's already installed. + /// + /// By default, uv will exit successfully if the version is already + /// installed. #[arg(long, short, alias = "force")] pub reinstall: bool, } @@ -2863,14 +2912,20 @@ pub struct PythonPinArgs { /// Write the resolved Python interpreter path instead of the request. /// /// 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. #[arg(long, overrides_with("resolved"))] pub resolved: bool, #[arg(long, overrides_with("no_resolved"), hide = true)] pub no_resolved: bool, - /// Avoid validating the Python pin against the workspace in the current directory or any parent - /// directory. + /// Avoid validating the Python pin is compatible with the workspace. + /// + /// By default, a workspace is discovered in the current directory or any parent + /// directory. If a workspace is found, the Python pin is validated against + /// the workspace's `requires-python` constraint. #[arg(long)] pub no_workspace: bool, } diff --git a/crates/uv/tests/help.rs b/crates/uv/tests/help.rs index 91976512e..e7b549972 100644 --- a/crates/uv/tests/help.rs +++ b/crates/uv/tests/help.rs @@ -237,6 +237,11 @@ fn help_subcommand() { environment contains a PyPy interpreter then check if each executable in the path is a PyPy interpreter. + uv supports discovering CPython, PyPy, and GraalPy interpreters. + Unsupported interpreters will be skipped during discovery. If an + unsupported interpreter implementation is requested, uv will exit with + an error. + Usage: uv python [OPTIONS] Commands: @@ -362,7 +367,19 @@ fn help_subsubcommand() { success: true exit_code: 0 ----- stdout ----- - Download and install Python versions + Download and install Python versions. + + Multiple Python versions may be requested. + + Supports CPython and PyPy. + + CPython distributions are downloaded from the `python-build-standalone` project. + + Python versions are installed into the uv Python directory, which can be retrieved with `uv python + dir`. A `python` executable is not made globally available, managed Python versions are only used in + uv commands or in active virtual environments. + + See `uv help python` to view supported request formats. Usage: uv python install [OPTIONS] [TARGETS]... @@ -378,7 +395,9 @@ fn help_subsubcommand() { Options: -r, --reinstall - Reinstall the requested Python version, if it's already installed + Reinstall the requested Python version, if it's already installed. + + By default, uv will exit successfully if the version is already installed. Cache options: -n, --no-cache diff --git a/docs/reference/cli.md b/docs/reference/cli.md index ca3a20d1d..1bee5247b 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -2836,6 +2836,11 @@ e.g., if `pypy` is requested, uv will first check if the virtual environment contains a PyPy interpreter then check if each executable in the path is a PyPy interpreter. +uv supports discovering CPython, PyPy, and GraalPy interpreters. +Unsupported interpreters will be skipped during discovery. If an +unsupported interpreter implementation is requested, uv will exit with +an error. +

Usage

``` @@ -2860,7 +2865,15 @@ uv python [OPTIONS] ### uv python list -List the available Python installations +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. + +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. + +Use `--only-installed` to omit available downloads.

Usage

@@ -2870,9 +2883,13 @@ uv python list [OPTIONS]

Options

-
--all-platforms

List Python installations for all platforms

+
--all-platforms

List Python downloads for all platforms.

-
--all-versions

List all Python versions, including outdated patch versions

+

By default, only downloads for the current platform are shown.

+ +
--all-versions

List all Python versions, including old patch versions.

+ +

By default, only the latest patch version is shown for each minor version.

--cache-dir cache-dir

Path to the cache directory.

@@ -2918,7 +2935,9 @@ uv python list [OPTIONS]

When disabled, uv will only use locally cached data and locally available files.

-
--only-installed

Only show installed Python versions, exclude available downloads

+
--only-installed

Only show installed Python versions, exclude available downloads.

+ +

By default, available downloads for the current platform are shown.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

@@ -2947,7 +2966,17 @@ uv python list [OPTIONS] ### uv python install -Download and install Python versions +Download and install Python versions. + +Multiple Python versions may be requested. + +Supports CPython and PyPy. + +CPython distributions are downloaded from the `python-build-standalone` project. + +Python versions are installed into the uv Python directory, which can be retrieved with `uv python dir`. A `python` executable is not made globally available, managed Python versions are only used in uv commands or in active virtual environments. + +See `uv help python` to view supported request formats.

Usage

@@ -3028,7 +3057,9 @@ uv python install [OPTIONS] [TARGETS]...
--quiet, -q

Do not print any output

-
--reinstall, -r

Reinstall the requested Python version, if it’s already installed

+
--reinstall, -r

Reinstall the requested Python version, if it’s already installed.

+ +

By default, uv will exit successfully if the version is already installed.

--verbose, -v

Use verbose output.

@@ -3040,7 +3071,11 @@ uv python install [OPTIONS] [TARGETS]... ### uv python find -Search for a Python installation +Search for a Python installation. + +Displays the path to the Python executable. + +See `uv help python` to view supported request formats and details on discovery behavior.

Usage

@@ -3129,7 +3164,11 @@ uv python find [OPTIONS] [REQUEST] ### uv python pin -Pin to a specific Python version +Pin to a specific Python version. + +Writes the pinned version to a `.python-version` file, which is then read by other uv commands when determining the required Python version. + +See `uv help python` to view supported request formats.

Usage

@@ -3189,7 +3228,9 @@ uv python pin [OPTIONS] [REQUEST]
--no-python-downloads

Disable automatic downloads of Python

-
--no-workspace

Avoid validating the Python pin against the workspace in the current directory or any parent directory

+
--no-workspace

Avoid validating the Python pin is compatible with the workspace.

+ +

By default, a workspace is discovered in the current directory or any parent directory. If a workspace is found, the Python pin is validated against the workspace’s requires-python constraint.

--offline

Disable network access.

@@ -3216,6 +3257,8 @@ uv python pin [OPTIONS] [REQUEST]

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.

+
--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)