docs(specifiers): add is_unsatisfiable() usage example (#1166)

r266-tech · web-flow · commit 66e34a80256c · 2026-04-21T10:21:41.000-04:00
* docs(specifiers): add is_unsatisfiable() usage example * docs(specifiers): add compound SpecifierSet & is_unsatisfiable example Per review feedback from @henryiii and @notatallshaw, adds a compound example using the & operator to show how combining two SpecifierSets can produce an unsatisfiable set — closer to how users actually build specifiers from requires-python plus other constraints.
diff --git a/docs/specifiers.rst b/docs/specifiers.rst
@@ -49,6 +49,16 @@ Usage
     >>> # contained within our specifier.
     >>> list(combined_spec.filter([v1, v2, "1.4"]))
     [<Version('1.0')>, '1.4']
+    >>> # We can check if a specifier set can never be satisfied
+    >>> SpecifierSet(">=2.0,<1.0").is_unsatisfiable()
+    True
+    >>> SpecifierSet(">=1.0,<2.0").is_unsatisfiable()
+    False
+    >>> # Compound sets built with ``&`` may also become unsatisfiable
+    >>> (SpecifierSet(">=3.9,<4.0") & SpecifierSet("==3.12.*")).is_unsatisfiable()
+    False
+    >>> (SpecifierSet(">=3.13,<4.0") & SpecifierSet("==3.12.*")).is_unsatisfiable()
+    True
 
 
 Reference
