From 2e028cd3b69a76470cfa1fa1c9c391e343997a13 Mon Sep 17 00:00:00 2001 From: Charlie Marsh Date: Tue, 22 Oct 2024 10:18:16 -0400 Subject: [PATCH] Rewrite some references to "optional groups" (#8454) ## Summary We generally want to avoid references to "optional groups" now that dependency groups are a first-class, standardized concept. --- CHANGELOG.md | 3 +-- crates/uv-cli/src/lib.rs | 20 +++++++++----------- crates/uv-resolver/src/lock/mod.rs | 2 +- crates/uv-settings/src/settings.rs | 2 +- docs/concepts/projects.md | 6 +++--- docs/reference/cli.md | 18 +++++++++--------- docs/reference/settings.md | 2 +- uv.schema.json | 2 +- 8 files changed, 26 insertions(+), 29 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ecede3f41..cd4a862a1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1932,8 +1932,7 @@ and `uv tool run` ([#4717](https://github.com/astral-sh/uv/pull/4717)) - Add `uv tool uninstall` ([#4641](https://github.com/astral-sh/uv/pull/4641)) - Add support for specifying `name@version` in `uv tool run` ([#4572](https://github.com/astral-sh/uv/pull/4572)) - Allow `uv add` to specify optional dependency groups ([#4607](https://github.com/astral-sh/uv/pull/4607)) -- Allow the package spec to be passed positionally -in `uv tool install` ([#4564](https://github.com/astral-sh/uv/pull/4564)) +- Allow the package spec to be passed positionally in `uv tool install` ([#4564](https://github.com/astral-sh/uv/pull/4564)) - Avoid infinite loop for cyclic installs ([#4633](https://github.com/astral-sh/uv/pull/4633)) - Indent wheels like dependencies in the lockfile ([#4582](https://github.com/astral-sh/uv/pull/4582)) - Sync all packages in a virtual workspace ([#4636](https://github.com/astral-sh/uv/pull/4636)) diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs index 14e3c0b16..b6dfbf137 100644 --- a/crates/uv-cli/src/lib.rs +++ b/crates/uv-cli/src/lib.rs @@ -945,7 +945,7 @@ pub struct PipCompileArgs { #[arg(long, short, env = EnvVars::UV_BUILD_CONSTRAINT, value_delimiter = ' ', value_parser = parse_maybe_file_path)] pub build_constraint: Vec>, - /// Include optional dependencies from the extra group name; may be provided more than once. + /// Include optional dependencies from the specified extra 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)] @@ -1494,7 +1494,7 @@ pub struct PipInstallArgs { #[arg(long, short, env = EnvVars::UV_BUILD_CONSTRAINT, value_delimiter = ' ', value_parser = parse_maybe_file_path)] pub build_constraint: Vec>, - /// Include optional dependencies from the extra group name; may be provided more than once. + /// Include optional dependencies from the specified extra 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)] @@ -2573,7 +2573,7 @@ pub struct InitArgs { #[derive(Args)] #[allow(clippy::struct_excessive_bools)] pub struct RunArgs { - /// Include optional dependencies from the extra group name. + /// Include optional dependencies from the specified extra name. /// /// May be provided more than once. /// @@ -2769,7 +2769,7 @@ pub struct RunArgs { #[derive(Args)] #[allow(clippy::struct_excessive_bools)] pub struct SyncArgs { - /// Include optional dependencies from the extra group name. + /// Include optional dependencies from the specified extra name. /// /// May be provided more than once. /// @@ -2984,13 +2984,12 @@ pub struct AddArgs { #[arg(long, conflicts_with("optional"), conflicts_with("group"))] pub dev: bool, - /// Add the requirements to the specified optional dependency group. + /// 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. /// - /// To enable an optional dependency group for this requirement instead, see - /// `--extra`. + /// To enable an optional extra for this requirement instead, see `--extra`. #[arg(long, conflicts_with("dev"), conflicts_with("group"))] pub optional: Option, @@ -3037,8 +3036,7 @@ pub struct AddArgs { /// /// May be provided more than once. /// - /// To add this dependency to an optional group in the current project - /// instead, see `--optional`. + /// To add this dependency to an optional extra instead, see `--optional`. #[arg(long)] pub extra: Option>, @@ -3108,7 +3106,7 @@ pub struct RemoveArgs { #[arg(long, conflicts_with("optional"), conflicts_with("group"))] pub dev: bool, - /// Remove the packages from the specified optional dependency group. + /// Remove the packages from the project's optional dependencies for the specified extra. #[arg(long, conflicts_with("dev"), conflicts_with("group"))] pub optional: Option, @@ -3289,7 +3287,7 @@ pub struct ExportArgs { #[arg(long)] pub package: Option, - /// Include optional dependencies from the extra group name. + /// Include optional dependencies from the specified extra name. /// /// May be provided more than once. #[arg(long, conflicts_with = "all_extras", value_parser = extra_name_with_clap_error)] diff --git a/crates/uv-resolver/src/lock/mod.rs b/crates/uv-resolver/src/lock/mod.rs index 73d878371..c16f96106 100644 --- a/crates/uv-resolver/src/lock/mod.rs +++ b/crates/uv-resolver/src/lock/mod.rs @@ -3884,7 +3884,7 @@ enum LockErrorKind { /// The ID of the package for which a duplicate dependency was /// found. id: PackageId, - /// The name of the optional dependency group. + /// The name of the extra. extra: ExtraName, /// The ID of the conflicting dependency. dependency: Dependency, diff --git a/crates/uv-settings/src/settings.rs b/crates/uv-settings/src/settings.rs index ec880f390..e40f4401f 100644 --- a/crates/uv-settings/src/settings.rs +++ b/crates/uv-settings/src/settings.rs @@ -921,7 +921,7 @@ pub struct PipOptions { "# )] pub strict: Option, - /// Include optional dependencies from the extra group name; may be provided more than once. + /// Include optional dependencies from the specified extra; may be provided more than once. /// /// Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources. #[option( diff --git a/docs/concepts/projects.md b/docs/concepts/projects.md index 382635740..253ad210b 100644 --- a/docs/concepts/projects.md +++ b/docs/concepts/projects.md @@ -481,7 +481,7 @@ same time. uv requires that all optional dependencies ("extras") declared by the project are compatible with each other and resolves all optional dependencies together when creating the lockfile. -If optional dependencies declared in one group are not compatible with those in another group, uv +If optional dependencies declared in one extra are not compatible with those in another extra, uv will fail to resolve the requirements of the project with an error. !!! note @@ -727,8 +727,8 @@ no-build-isolation-package = ["cchardet"] Installing packages without build isolation requires that the package's build dependencies are installed in the project environment _prior_ to installing the package itself. This can be achieved -by separating out the build dependencies and the packages that require them into distinct optional -groups. For example: +by separating out the build dependencies and the packages that require them into distinct extras. +For example: ```toml title="pyproject.toml" [project] diff --git a/docs/reference/cli.md b/docs/reference/cli.md index f29b4af9c..1046ccde5 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -136,7 +136,7 @@ uv run [OPTIONS] [COMMAND]

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system’s configured time zone.

May also be set with the UV_EXCLUDE_NEWER environment variable.

-
--extra extra

Include optional dependencies from the extra group name.

+
--extra extra

Include optional dependencies from the specified extra name.

May be provided more than once.

@@ -743,7 +743,7 @@ uv add [OPTIONS] >

May be provided more than once.

-

To add this dependency to an optional group in the current project instead, see --optional.

+

To add this dependency to an optional extra instead, see --optional.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

@@ -886,11 +886,11 @@ uv add [OPTIONS] >

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

-
--optional optional

Add the requirements to the specified optional dependency group.

+
--optional optional

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.

-

To enable an optional dependency group for this requirement instead, see --extra.

+

To enable an optional extra for this requirement instead, see --extra.

--package package

Add the dependency to a specific package in the workspace

@@ -1222,7 +1222,7 @@ uv remove [OPTIONS] ...

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

-
--optional optional

Remove the packages from the specified optional dependency group

+
--optional optional

Remove the packages from the project’s optional dependencies for the specified extra

--package package

Remove the dependencies from a specific package in the workspace

@@ -1401,7 +1401,7 @@ uv sync [OPTIONS]

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system’s configured time zone.

May also be set with the UV_EXCLUDE_NEWER environment variable.

-
--extra extra

Include optional dependencies from the extra group name.

+
--extra extra

Include optional dependencies from the specified extra name.

May be provided more than once.

@@ -2033,7 +2033,7 @@ uv export [OPTIONS]

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system’s configured time zone.

May also be set with the UV_EXCLUDE_NEWER environment variable.

-
--extra extra

Include optional dependencies from the extra group name.

+
--extra extra

Include optional dependencies from the specified extra name.

May be provided more than once.

@@ -4957,7 +4957,7 @@ uv pip compile [OPTIONS] ...

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system’s configured time zone.

May also be set with the UV_EXCLUDE_NEWER environment variable.

-
--extra extra

Include optional dependencies from the extra group name; may be provided more than once.

+
--extra extra

Include optional dependencies from the specified extra name; may be provided more than once.

Only applies to pyproject.toml, setup.py, and setup.cfg sources.

@@ -5721,7 +5721,7 @@ uv pip install [OPTIONS] |--editable Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system’s configured time zone.

May also be set with the UV_EXCLUDE_NEWER environment variable.

-
--extra extra

Include optional dependencies from the extra group name; may be provided more than once.

+
--extra extra

Include optional dependencies from the specified extra name; may be provided more than once.

Only applies to pyproject.toml, setup.py, and setup.cfg sources.

diff --git a/docs/reference/settings.md b/docs/reference/settings.md index cad97ebb2..ff63da20e 100644 --- a/docs/reference/settings.md +++ b/docs/reference/settings.md @@ -1876,7 +1876,7 @@ system's configured time zone. #### [`extra`](#pip_extra) {: #pip_extra } -Include optional dependencies from the extra group name; may be provided more than once. +Include optional dependencies from the specified extra; may be provided more than once. Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources. diff --git a/uv.schema.json b/uv.schema.json index 9891e2173..a423bd1cd 100644 --- a/uv.schema.json +++ b/uv.schema.json @@ -841,7 +841,7 @@ ] }, "extra": { - "description": "Include optional dependencies from the extra group name; may be provided more than once.\n\nOnly applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources.", + "description": "Include optional dependencies from the specified extra; may be provided more than once.\n\nOnly applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources.", "type": [ "array", "null"