Skip to content

Add set relations and difference to VersionRange - #1298

Merged
notatallshaw merged 2 commits into
pypa:mainfrom
notatallshaw:version-range-relations-difference
Jun 27, 2026
Merged

notatallshaw merged 2 commits into
pypa:mainfrom
notatallshaw:version-range-relations-difference

Conversation

@notatallshaw

@notatallshaw notatallshaw commented Jun 26, 2026 •

Copy link
Copy Markdown
Member

Trying to adapt VersionRange to my pubgrub-based resolver nab I found two issues:

  1. In a few places I had incorrectly implemented subset and disjoint checks

Solved by adding direct helper methods to avoid the footgun of implementing them wrong

  1. Excluding a range using a & ~b introduced an unwanted pre-release policy: a didn't imply pre-releases but b did

This needs some new method. My proposal is the set operation difference where a - b will take the pre-release policy of a and discard b's.

This could also be solved with something like with_prerelease(prerelease), a class method that returns a new VersionRange object, but this pushes handling of PEP 440 pre-release policy logic up to the user, which is exactly what I'm trying to avoid with VersionRange.

Here's a worked example of the problem:

# foo is required >=1.0; a rejected branch that needed foo >=2.0b1 left behind
# a negative term excluding >=2.0b1. Available: foo 1.9 (final), 2.0a1 (pre-release).
required = SpecifierSet(">=1.0").to_range()
excluded = SpecifierSet(">=2.0b1").to_range()

list((required - excluded).filter(["1.9", "2.0a1"]))    # ['1.9']
list((required & ~excluded).filter(["1.9", "2.0a1"]))   # ['1.9', '2.0a1']

Changing A & ~B's policy instead of adding - would not work: & and ~ have their own correct behavior. Intersection must combine two requirements' policies (folding one as full() & req keeps its policy), and complement must stay an involution (~~r == r). Neither knows it is part of a difference, so - is the operation that treats B as a bare exclusion.

@henryiii

Copy link
Copy Markdown
Contributor

GPT 5.5:

ðŸĪ– AI text below ðŸĪ–

The new difference operation mishandles ranges with arbitrary-string or non-version === admissions, breaking basic set-difference identities for supported VersionRange members.

Review comment:

  • [P2] Preserve non-version admissions in difference — /Users/henryfs/git/pypa/packaging/src/packaging/ranges.py:669-671
    When self admits non-version strings, implementing difference via other.complement() drops those admissions even when the subtrahend is empty. For example, VersionRange.full() - VersionRange.empty() no longer contains "garbage", and SpecifierSet("===wat").to_range() - VersionRange.empty() becomes empty, so a - empty is not an identity for ranges that the existing API says can match arbitrary/=== strings.

@notatallshaw

Copy link
Copy Markdown
Member Author

The new difference operation mishandles ranges with arbitrary-string or non-version === admissions, breaking basic set-difference identities for supported VersionRange members.

Fixed

@henryiii henryiii left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems quite reasonable.

@notatallshaw

notatallshaw commented Jun 27, 2026 •

Copy link
Copy Markdown
Member Author

I'm confident this is correct.

But I'm also going to experiment with representing the pre-release policy itself as a range. I realized at the moment the union of two ranges such as >=1.0 and >=2.0b1 implies pre-relesaes between 1.0 and 2.0b1 even when there are final releases available, e.g. all of 1.0, 1.5b1, 2.0, and 2.0b1 are selected. I don't think this is a blocker but it is worth understanding if it can be fairly simple fixed.

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.

2 participants