Skip to content

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

Merged
henryiii merged 2 commits intopypa:mainfrom
r266-tech:docs-specifiers-is-unsatisfiable-usage
Apr 21, 2026
Merged

docs(specifiers): add is_unsatisfiable() usage example#1166
henryiii merged 2 commits intopypa:mainfrom
r266-tech:docs-specifiers-is-unsatisfiable-usage

Conversation

@r266-tech
Copy link
Copy Markdown
Contributor

Fixes #1165

PR #1119 added SpecifierSet.is_unsatisfiable() but the usage examples in docs/specifiers.rst don't demonstrate it. Users scanning the Usage section have no way to discover this method without reading the full API reference.

Added a doctest example showing is_unsatisfiable() on both an unsatisfiable set (>=2.0,<1.0True) and a satisfiable one (>=1.0,<2.0False), placed after the existing filter() example.

@henryiii
Copy link
Copy Markdown
Contributor

@notatallshaw does this look fine, or would you like something else? I could see something like (SpecifierSet(">=3.9,<4.0") & SpecifierSet("==3.12.*").is_unsatisfiable() being closer to what someone might do (the first one would likely come from requires-python).

@notatallshaw
Copy link
Copy Markdown
Member

Yeah, I would expect people would be compounding specifiers, for whatever reason.

We should encourage & because it's faster than recreating a new specifier via string joining, so let's add at least one example using that.

Comment thread docs/specifiers.rst
@r266-tech
Copy link
Copy Markdown
Contributor Author

Added a compound & example per the review — shows (SpecifierSet(">=3.9,<4.0") & SpecifierSet("==3.12.*")).is_unsatisfiable() (False) and (SpecifierSet(">=3.13,<4.0") & SpecifierSet("==3.12.*")).is_unsatisfiable() (True) — closer to the real-world pattern of combining requires-python with another constraint via &. Let me know if you'd prefer different pairings or a different placement.

@henryiii henryiii requested a review from notatallshaw April 20, 2026 22:15
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.
@henryiii henryiii force-pushed the docs-specifiers-is-unsatisfiable-usage branch from 3b093d9 to 979f2fe Compare April 21, 2026 14:14
@henryiii henryiii merged commit 66e34a8 into pypa:main Apr 21, 2026
55 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs(specifiers): is_unsatisfiable() missing from usage examples

3 participants