From 1ef7dd87e139783f8ffb6fd97faaef5f2ef34851 Mon Sep 17 00:00:00 2001 From: Di-Is Date: Sun, 25 Aug 2024 08:13:44 +0000 Subject: [PATCH 1/3] Add docs for `constraint-dependecies` and `override-dependencies` --- crates/uv-workspace/src/pyproject.rs | 33 +++++++++++++++ docs/reference/settings.md | 60 ++++++++++++++++++++++++++++ uv.schema.json | 3 +- 3 files changed, 95 insertions(+), 1 deletion(-) diff --git a/crates/uv-workspace/src/pyproject.rs b/crates/uv-workspace/src/pyproject.rs index f4d86ae3b390..388f09278285 100644 --- a/crates/uv-workspace/src/pyproject.rs +++ b/crates/uv-workspace/src/pyproject.rs @@ -137,6 +137,12 @@ pub struct ToolUv { "# )] pub environments: Option, + /// The project's override dependencies. + /// + /// Overrides on dependencies must be described in PEP 508-style. + /// + /// !!! note + /// If a workspace is used, only the root configuration values are valid, member configuration values are ignored. #[cfg_attr( feature = "schemars", schemars( @@ -144,7 +150,34 @@ pub struct ToolUv { description = "PEP 508-style requirements, e.g. `ruff==0.5.0`, or `ruff @ https://...`." ) )] + #[option( + default = r#"[]"#, + value_type = "list[str]", + example = r#" + override-dependencies = ["werkzeug==2.3.0"] + "# + )] pub override_dependencies: Option>>, + #[cfg_attr( + feature = "schemars", + schemars( + with = "Option>", + description = "PEP 508-style requirements, e.g. `ruff==0.5.0`, or `ruff @ https://...`." + ) + )] + /// The project's constraint dependencies. + /// + /// Constraint on dependencies must be described in PEP 508-style. + /// + /// !!! note + /// If a workspace is used, only the root configuration values are valid, member configuration values are ignored. + #[option( + default = r#"[]"#, + value_type = "list[str]", + example = r#" + constraint-dependencies = ["grpcio<1.65"] + "# + )] pub constraint_dependencies: Option>>, } diff --git a/docs/reference/settings.md b/docs/reference/settings.md index 25f80f258d55..896aa54d5c07 100644 --- a/docs/reference/settings.md +++ b/docs/reference/settings.md @@ -168,6 +168,36 @@ specified as `KEY=VALUE` pairs. --- +#### [`constraint-dependencies`](#constraint-dependencies) {: #constraint-dependencies } + +The project's constraint dependencies. + +Constraint on dependencies must be described in PEP 508-style. + +!!! note + If a workspace is used, only the root configuration values are valid, member configuration values are ignored. + +**Default value**: `[]` + +**Type**: `list[str]` + +**Example usage**: + +=== "pyproject.toml" + + ```toml + [tool.uv] + constraint-dependencies = ["grpcio<1.65"] + ``` +=== "uv.toml" + + ```toml + + constraint-dependencies = ["grpcio<1.65"] + ``` + +--- + #### [`dev-dependencies`](#dev-dependencies) {: #dev-dependencies } The project's development dependencies. Development dependencies will be installed by @@ -772,6 +802,36 @@ Disable network access, relying only on locally cached data and locally availabl --- +#### [`override-dependencies`](#override-dependencies) {: #override-dependencies } + +The project's override dependencies. + +Overrides on dependencies must be described in PEP 508-style. + +!!! note + If a workspace is used, only the root configuration values are valid, member configuration values are ignored. + +**Default value**: `[]` + +**Type**: `list[str]` + +**Example usage**: + +=== "pyproject.toml" + + ```toml + [tool.uv] + override-dependencies = ["werkzeug==2.3.0"] + ``` +=== "uv.toml" + + ```toml + + override-dependencies = ["werkzeug==2.3.0"] + ``` + +--- + #### [`prerelease`](#prerelease) {: #prerelease } The strategy to use when considering pre-release versions. diff --git a/uv.schema.json b/uv.schema.json index 6fe0959f999b..fcb69dcd529c 100644 --- a/uv.schema.json +++ b/uv.schema.json @@ -57,12 +57,13 @@ ] }, "constraint-dependencies": { + "description": "PEP 508-style requirements, e.g. `ruff==0.5.0`, or `ruff @ https://...`.", "type": [ "array", "null" ], "items": { - "$ref": "#/definitions/Requirement" + "type": "string" } }, "dev-dependencies": { From 6bccc00b91670d462cfea66a9c6feec8d235cfea Mon Sep 17 00:00:00 2001 From: Di-Is Date: Mon, 26 Aug 2024 11:28:12 +0000 Subject: [PATCH 2/3] Modify docs --- crates/uv-workspace/src/pyproject.rs | 8 ++++++-- docs/reference/settings.md | 8 ++++++-- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/crates/uv-workspace/src/pyproject.rs b/crates/uv-workspace/src/pyproject.rs index 388f09278285..cb09fab16006 100644 --- a/crates/uv-workspace/src/pyproject.rs +++ b/crates/uv-workspace/src/pyproject.rs @@ -142,7 +142,9 @@ pub struct ToolUv { /// Overrides on dependencies must be described in PEP 508-style. /// /// !!! note - /// If a workspace is used, only the root configuration values are valid, member configuration values are ignored. + /// When using project interfaces like `uv lock`, only the settings in the pyproject.toml are valid. + /// Specifically, when using a workspace, only the settings in the pyproject.toml located at the workspace root are applied. + /// The settings in the pyproject.toml of workspace members and in uv.toml are ignored. #[cfg_attr( feature = "schemars", schemars( @@ -170,7 +172,9 @@ pub struct ToolUv { /// Constraint on dependencies must be described in PEP 508-style. /// /// !!! note - /// If a workspace is used, only the root configuration values are valid, member configuration values are ignored. + /// When using project interfaces like `uv lock`, only the settings in the pyproject.toml are valid. + /// Specifically, when using a workspace, only the settings in the pyproject.toml located at the workspace root are applied. + /// The settings in the pyproject.toml of workspace members and in uv.toml are ignored. #[option( default = r#"[]"#, value_type = "list[str]", diff --git a/docs/reference/settings.md b/docs/reference/settings.md index 896aa54d5c07..f9de90421ece 100644 --- a/docs/reference/settings.md +++ b/docs/reference/settings.md @@ -175,7 +175,9 @@ The project's constraint dependencies. Constraint on dependencies must be described in PEP 508-style. !!! note - If a workspace is used, only the root configuration values are valid, member configuration values are ignored. + When using project interfaces like `uv lock`, only the settings in the pyproject.toml are valid. + Specifically, when using a workspace, only the settings in the pyproject.toml located at the workspace root are applied. + The settings in the pyproject.toml of workspace members and in uv.toml are ignored. **Default value**: `[]` @@ -809,7 +811,9 @@ The project's override dependencies. Overrides on dependencies must be described in PEP 508-style. !!! note - If a workspace is used, only the root configuration values are valid, member configuration values are ignored. + When using project interfaces like `uv lock`, only the settings in the pyproject.toml are valid. + Specifically, when using a workspace, only the settings in the pyproject.toml located at the workspace root are applied. + The settings in the pyproject.toml of workspace members and in uv.toml are ignored. **Default value**: `[]` From b52a099ee5954716c15e71d8c4bfa1522dcbf1ea Mon Sep 17 00:00:00 2001 From: Charlie Marsh Date: Mon, 26 Aug 2024 19:25:15 -0400 Subject: [PATCH 3/3] Some tweaks --- crates/uv-settings/src/settings.rs | 10 ++----- crates/uv-workspace/src/pyproject.rs | 45 ++++++++++++++++++---------- docs/reference/settings.md | 39 +++++++++++++++++------- uv.schema.json | 4 +-- 4 files changed, 64 insertions(+), 34 deletions(-) diff --git a/crates/uv-settings/src/settings.rs b/crates/uv-settings/src/settings.rs index 8f580b9d6844..0557fb146228 100644 --- a/crates/uv-settings/src/settings.rs +++ b/crates/uv-settings/src/settings.rs @@ -40,13 +40,9 @@ pub struct Options { pub top_level: ResolverInstallerOptions, #[option_group] pub pip: Option, - #[cfg_attr( - feature = "schemars", - schemars( - with = "Option>", - description = "PEP 508 style requirements, e.g. `ruff==0.5.0`, or `ruff @ https://...`." - ) - )] + + // NOTE(charlie): These fields are shared with `ToolUv` in + // `crates/uv-workspace/src/pyproject.rs`, and the documentation lives on that struct. pub override_dependencies: Option>>, pub constraint_dependencies: Option>>, diff --git a/crates/uv-workspace/src/pyproject.rs b/crates/uv-workspace/src/pyproject.rs index cb09fab16006..559a6c931fcd 100644 --- a/crates/uv-workspace/src/pyproject.rs +++ b/crates/uv-workspace/src/pyproject.rs @@ -137,48 +137,63 @@ pub struct ToolUv { "# )] pub environments: Option, - /// The project's override dependencies. + /// Overrides to apply when resolving the project's dependencies. /// - /// Overrides on dependencies must be described in PEP 508-style. + /// Overrides are used to force selection of a specific version of a package, regardless of the + /// version requested by any other package, and regardless of whether choosing that version + /// would typically constitute an invalid resolution. + /// + /// While constraints are _additive_, in that they're combined with the requirements of the + /// constituent packages, overrides are _absolute_, in that they completely replace the + /// requirements of any constituent packages. /// /// !!! note - /// When using project interfaces like `uv lock`, only the settings in the pyproject.toml are valid. - /// Specifically, when using a workspace, only the settings in the pyproject.toml located at the workspace root are applied. - /// The settings in the pyproject.toml of workspace members and in uv.toml are ignored. + /// In `uv lock`, `uv sync`, and `uv run`, uv will only read `override-dependencies` from + /// the `pyproject.toml` at the workspace root, and will ignore any declarations in other + /// workspace members or `uv.toml` files. #[cfg_attr( feature = "schemars", schemars( with = "Option>", - description = "PEP 508-style requirements, e.g. `ruff==0.5.0`, or `ruff @ https://...`." + description = "PEP 508-style requirements, e.g., `ruff==0.5.0`, or `ruff @ https://...`." ) )] #[option( default = r#"[]"#, value_type = "list[str]", example = r#" + # Always install Werkzeug 2.3.0, regardless of whether transitive dependencies request + # a different version. override-dependencies = ["werkzeug==2.3.0"] "# )] pub override_dependencies: Option>>, + /// Constraints to apply when resolving the project's dependencies. + /// + /// Constraints are used to restrict the versions of dependencies that are selected during + /// resolution. + /// + /// Including a package as a constraint will _not_ trigger installation of the package on its + /// own; instead, the package must be requested elsewhere in the project's first-party or + /// transitive dependencies. + /// + /// !!! note + /// In `uv lock`, `uv sync`, and `uv run`, uv will only read `constraint-dependencies` from + /// the `pyproject.toml` at the workspace root, and will ignore any declarations in other + /// workspace members or `uv.toml` files. #[cfg_attr( feature = "schemars", schemars( with = "Option>", - description = "PEP 508-style requirements, e.g. `ruff==0.5.0`, or `ruff @ https://...`." + description = "PEP 508-style requirements, e.g., `ruff==0.5.0`, or `ruff @ https://...`." ) )] - /// The project's constraint dependencies. - /// - /// Constraint on dependencies must be described in PEP 508-style. - /// - /// !!! note - /// When using project interfaces like `uv lock`, only the settings in the pyproject.toml are valid. - /// Specifically, when using a workspace, only the settings in the pyproject.toml located at the workspace root are applied. - /// The settings in the pyproject.toml of workspace members and in uv.toml are ignored. #[option( default = r#"[]"#, value_type = "list[str]", example = r#" + # Ensure that the grpcio version is always less than 1.65, if it's requested by a + # transitive dependency. constraint-dependencies = ["grpcio<1.65"] "# )] diff --git a/docs/reference/settings.md b/docs/reference/settings.md index f9de90421ece..f316ebf4d4a9 100644 --- a/docs/reference/settings.md +++ b/docs/reference/settings.md @@ -170,14 +170,19 @@ specified as `KEY=VALUE` pairs. #### [`constraint-dependencies`](#constraint-dependencies) {: #constraint-dependencies } -The project's constraint dependencies. +Constraints to apply when resolving the project's dependencies. -Constraint on dependencies must be described in PEP 508-style. +Constraints are used to restrict the versions of dependencies that are selected during +resolution. + +Including a package as a constraint will _not_ trigger installation of the package on its +own; instead, the package must be requested elsewhere in the project's first-party or +transitive dependencies. !!! note - When using project interfaces like `uv lock`, only the settings in the pyproject.toml are valid. - Specifically, when using a workspace, only the settings in the pyproject.toml located at the workspace root are applied. - The settings in the pyproject.toml of workspace members and in uv.toml are ignored. + In `uv lock`, `uv sync`, and `uv run`, uv will only read `constraint-dependencies` from + the `pyproject.toml` at the workspace root, and will ignore any declarations in other + workspace members or `uv.toml` files. **Default value**: `[]` @@ -189,12 +194,16 @@ Constraint on dependencies must be described in PEP 508-style. ```toml [tool.uv] + # Ensure that the grpcio version is always less than 1.65, if it's requested by a + # transitive dependency. constraint-dependencies = ["grpcio<1.65"] ``` === "uv.toml" ```toml + # Ensure that the grpcio version is always less than 1.65, if it's requested by a + # transitive dependency. constraint-dependencies = ["grpcio<1.65"] ``` @@ -806,14 +815,20 @@ Disable network access, relying only on locally cached data and locally availabl #### [`override-dependencies`](#override-dependencies) {: #override-dependencies } -The project's override dependencies. +Overrides to apply when resolving the project's dependencies. + +Overrides are used to force selection of a specific version of a package, regardless of the +version requested by any other package, and regardless of whether choosing that version +would typically constitute an invalid resolution. -Overrides on dependencies must be described in PEP 508-style. +While constraints are _additive_, in that they're combined with the requirements of the +constituent packages, overrides are _absolute_, in that they completely replace the +requirements of any constituent packages. !!! note - When using project interfaces like `uv lock`, only the settings in the pyproject.toml are valid. - Specifically, when using a workspace, only the settings in the pyproject.toml located at the workspace root are applied. - The settings in the pyproject.toml of workspace members and in uv.toml are ignored. + In `uv lock`, `uv sync`, and `uv run`, uv will only read `override-dependencies` from + the `pyproject.toml` at the workspace root, and will ignore any declarations in other + workspace members or `uv.toml` files. **Default value**: `[]` @@ -825,12 +840,16 @@ Overrides on dependencies must be described in PEP 508-style. ```toml [tool.uv] + # Always install Werkzeug 2.3.0, regardless of whether transitive dependencies request + # a different version. override-dependencies = ["werkzeug==2.3.0"] ``` === "uv.toml" ```toml + # Always install Werkzeug 2.3.0, regardless of whether transitive dependencies request + # a different version. override-dependencies = ["werkzeug==2.3.0"] ``` diff --git a/uv.schema.json b/uv.schema.json index fcb69dcd529c..871fa0e12eb3 100644 --- a/uv.schema.json +++ b/uv.schema.json @@ -57,7 +57,7 @@ ] }, "constraint-dependencies": { - "description": "PEP 508-style requirements, e.g. `ruff==0.5.0`, or `ruff @ https://...`.", + "description": "PEP 508-style requirements, e.g., `ruff==0.5.0`, or `ruff @ https://...`.", "type": [ "array", "null" @@ -255,7 +255,7 @@ ] }, "override-dependencies": { - "description": "PEP 508-style requirements, e.g. `ruff==0.5.0`, or `ruff @ https://...`.", + "description": "PEP 508-style requirements, e.g., `ruff==0.5.0`, or `ruff @ https://...`.", "type": [ "array", "null"