uv: expose conflicts in tool.uv in pyproject.toml

Author: BurntSushi

crates/uv-workspace/src/pyproject.rs

@@ -460,7 +460,7 @@ pub struct ToolUv {
     )]
     pub environments: Option<SupportedEnvironments>,
 
-    /// Conflicting extras may be declared here.
+    /// Conflicting extras or groups may be declared here.
     ///
     /// It's useful to declare conflicting extras when the extras have mutually
     /// incompatible dependencies. For example, extra `foo` might depend on
@@ -481,12 +481,8 @@ pub struct ToolUv {
     /// fail.
     #[cfg_attr(
         feature = "schemars",
-        // Skipped for now while we iterate on this feature.
-        schemars(skip, description = "A list sets of conflicting groups or extras.")
+        schemars(description = "A list sets of conflicting groups or extras.")
     )]
-    /*
-    This is commented out temporarily while we finalize its
-    functionality and naming. This avoids it showing up in docs.
     #[option(
         default = r#"[]"#,
         value_type = "list[list[dict]]",
@@ -500,9 +496,16 @@ pub struct ToolUv {
                     { extra = "test2" },
                 ]
             ]
+
+            # Or, to declare conflicting groups:
+            conflicts = [
+                [
+                    { group = "test1" },
+                    { group = "test2" },
+                ]
+            ]
         "#
     )]
-    */
     pub conflicts: Option<SchemaConflicts>,
 }
 

docs/reference/settings.md

@@ -1,4 +1,55 @@
 ## Project metadata
+### [`conflicts`](#conflicts) {: #conflicts }
+
+Conflicting extras or groups may be declared here.
+
+It's useful to declare conflicting extras when the extras have mutually
+incompatible dependencies. For example, extra `foo` might depend on
+`numpy==2.0.0` while extra `bar` might depend on `numpy==2.1.0`. These
+extras cannot be activated at the same time. This usually isn't a
+problem for pip-style workflows, but when using uv project support
+with universal resolution, it will try to produce a resolution that
+satisfies both extras simultaneously.
+
+When this happens, resolution will fail, because one cannot install
+both `numpy 2.0.0` and `numpy 2.1.0` into the same environment.
+
+To work around this, you may specify `foo` and `bar` as conflicting
+extras. When doing universal resolution in project mode, these extras
+will get their own "forks" distinct from one another in order to permit
+conflicting dependencies. In exchange, if one tries to install from the
+lock file with both conflicting extras activated, installation will
+fail.
+
+**Default value**: `[]`
+
+**Type**: `list[list[dict]]`
+
+**Example usage**:
+
+```toml title="pyproject.toml"
+[tool.uv]
+# Require that `package[test1]` and `package[test2]`
+# requirements are resolved in different forks so that they
+# cannot conflict with one another.
+conflicts = [
+    [
+        { extra = "test1" },
+        { extra = "test2" },
+    ]
+]
+
+# Or, to declare conflicting groups:
+conflicts = [
+    [
+        { group = "test1" },
+        { group = "test2" },
+    ]
+]
+```
+
+---
+
 ### [`constraint-dependencies`](#constraint-dependencies) {: #constraint-dependencies }
 
 Constraints to apply when resolving the project's dependencies.