[ty] Add support for narrowing on tuple match cases by charliermarsh · Pull Request #25493 · astral-sh/ruff

charliermarsh · 2026-05-30T20:35:19Z

Summary

This PR adds precise narrowing for fixed-length sequence match patterns.

For a pattern like [int(), str()], we synthesize a protocol whose __len__ and indexed __getitem__ methods
encode the pattern’s length and element types:

def f(value: object) -> None:
    match value:
        case [int(), str()]:
            reveal_type(len(value))  # Literal[2]
            reveal_type(value[0])  # int
            reveal_type(value[1])  # str

We distinguish between the type necessary to match a pattern and the type guaranteed to match it. Positive
narrowing uses the necessary type, while negative narrowing and reachability only subtract values guaranteed to
match. This allows exact sequence patterns to participate in exhaustiveness analysis without incorrectly treating
refutable nested patterns as exhaustive.

Closes astral-sh/ty#561.

astral-sh-bot · 2026-05-30T20:38:15Z

Typing conformance results

The percentage of diagnostics emitted that were expected errors held steady at 92.16%. The percentage of expected errors that received a diagnostic held steady at 87.31%. The number of fully passing files held steady at 92/134.

Summary

How are test cases classified?

Each test case represents one expected error annotation or a group of annotations sharing a tag. Counts are per test case, not per diagnostic — multiple diagnostics on the same line count as one. Required annotations (E) are true positives when ty flags the expected location and false negatives when it does not. Optional annotations (E?) are true positives when flagged but true negatives (not false negatives) when not. Tagged annotations (E[tag]) require ty to flag exactly one of the tagged lines; tagged multi-annotations (E[tag+]) allow any number up to the tag count. Flagging unexpected locations counts as a false positive.

Metric	Old	New	Diff
True Positives	929	929	+0
False Positives	79	79	+0
False Negatives	135	135	+0
Total Diagnostics	1055	1055	+0
Precision	92.16%	92.16%	+0.00%
Recall	87.31%	87.31%	+0.00%
Passing Files	92/134	92/134	+0

True positives changed (5)

5 diagnostics

Test case	Diff
tuples_type_compat.py:101	-error[type-assertion-failure] Type `tuple[int] \| tuple[str, str] \| tuple[int, tuple[str, ...], int]` does not match asserted type `tuple[int]` +error[type-assertion-failure] Type `tuple[int] \| (tuple[int, tuple[str, ...], int] & <Protocol with members '__getitem__', '__len__'>)` does not match asserted type `tuple[int]`
tuples_type_compat.py:106	-error[type-assertion-failure] Type `tuple[int] \| tuple[str, str] \| tuple[int, tuple[str, ...], int]` does not match asserted type `tuple[str, str] \| tuple[int, int]` +error[type-assertion-failure] Type `tuple[str, str] \| (tuple[int, tuple[str, ...], int] & <Protocol with members '__getitem__', '__len__'> & ~<Protocol with members '__getitem__', '__len__'>)` does not match asserted type `tuple[str, str] \| tuple[int, int]`
tuples_type_compat.py:111	-error[type-assertion-failure] Type `tuple[int] \| tuple[str, str] \| tuple[int, tuple[str, ...], int]` does not match asserted type `tuple[int, str, int]` +error[type-assertion-failure] Type `tuple[int, tuple[str, ...], int] & <Protocol with members '__getitem__', '__len__'> & ~<Protocol with members '__getitem__', '__len__'> & ~<Protocol with members '__getitem__', '__len__'>` does not match asserted type `tuple[int, str, int]`
tuples_type_compat.py:126	-error[type-assertion-failure] Type `tuple[int \| str, int \| str]` does not match asserted type `tuple[int \| str, str]` +error[type-assertion-failure] Type `tuple[int \| str, int \| str] & <Protocol with members '__getitem__', '__len__'>` does not match asserted type `tuple[int \| str, str]`
tuples_type_compat.py:129	-error[type-assertion-failure] Type `tuple[int \| str, int \| str]` does not match asserted type `tuple[int \| str, int]` +error[type-assertion-failure] Type `tuple[int \| str, int \| str] & ~<Protocol with members '__getitem__', '__len__'>` does not match asserted type `tuple[int \| str, int]`

astral-sh-bot · 2026-05-30T20:39:01Z

Memory usage report

Memory usage unchanged ✅

astral-sh-bot · 2026-05-30T20:40:46Z

`ecosystem-analyzer` results

No diagnostic changes detected ✅

Flaky changes detected. This PR summary excludes flaky changes; see the HTML report for details.

Full report with detailed diff (timing results)

charliermarsh · 2026-06-03T18:13:17Z

(In draft due to performance regression...)

AlexWaygood

Only taken a pass at the tests so far

AlexWaygood

Great work, thank you!

AlexWaygood · 2026-06-06T14:07:19Z

+/// whether the pattern accepts additional sequence elements.
+#[derive(Debug, Clone, Hash, PartialEq, salsa::Update, get_size2::GetSize)]
+pub struct SequencePatternPredicateKind<'db> {
+    pub patterns: Vec<PatternPredicateKind<'db>>,


Suggested change

pub patterns: Vec<PatternPredicateKind<'db>>,

pub patterns: Box<[PatternPredicateKind<'db>]>,

Feels like a boxed slice here would use less memory and better reflects the fact that this is immutable data. (No other code needs to change -- you can .collect() directly into a boxed slice)

AlexWaygood · 2026-06-06T14:07:59Z

+        let star_index = self
+            .patterns
+            .iter()
+            .position(|pattern| matches!(pattern, PatternPredicateKind::Unsupported))?;


Suggested change

.position(|pattern| matches!(pattern, PatternPredicateKind::Unsupported))?;

.position(|pattern| pattern == &PatternPredicateKind::Unsupported)?;

It seems like the only kind of match pattern that remains unsupported is match-star patterns, so I think we could rename PatternPredicateKind::Unsupported to PatternPredicateKind::MatchStar at this point. It would make this function more "obviously correct" (I had to look through the code to see whether there were other still-unsupported kinds of match patterns to check whether this logic was accurate)

AlexWaygood · 2026-06-06T14:08:26Z

+        self.patterns.len() == 1 && self.has_star
+    }
+
+    pub fn is_exact_length(&self) -> bool {


Suggested change

pub fn is_exact_length(&self) -> bool {

pub const fn is_exact_length(&self) -> bool {

AlexWaygood · 2026-06-06T14:11:52Z

+                PatternPredicateKind::Sequence(SequencePatternPredicateKind {
+                    patterns: pattern
+                        .patterns
+                        .iter()
+                        .map(|pattern| self.predicate_kind(pattern))
+                        .collect(),
+                    has_star: pattern
+                        .patterns
+                        .iter()
+                        .any(|pattern| matches!(pattern, ast::Pattern::MatchStar(_))),
+                })


we can do this with one iteration

Suggested change

PatternPredicateKind::Sequence(SequencePatternPredicateKind {

patterns: pattern

.patterns

.iter()

.map(|pattern| self.predicate_kind(pattern))

.collect(),

has_star: pattern

.patterns

.iter()

.any(|pattern| matches!(pattern, ast::Pattern::MatchStar(_))),

})

let mut has_star = false;

let patterns = pattern

.patterns

.iter()

.map(|pattern| {

if matches!(pattern, ast::Pattern::MatchStar(_)) {

has_star = true;

}

self.predicate_kind(pattern)

})

.collect();

PatternPredicateKind::Sequence(SequencePatternPredicateKind { patterns, has_star })

AlexWaygood · 2026-06-06T14:40:03Z

It doesn't look like we yet have any tests for the & ~str & ~bytes & ~bytearray part of the intersection. E.g.

def f(x: str | tuple[int, int]): match x: case (a, b): reveal_type(a) # revealed: @Todo reveal_type(b) # revealed: @Todo case _: reveal_type(x) # revealed: str

We wouldn't get the correct answer in the second branch there if it weren't for the & ~str & ~bytes & ~bytearray part of the intersection. We should add similar tests for unions with bytes and bytearray too

I think this part doesn't work yet since we don't support narrowing on the assigned names?

(Gah, sorry, I missed the @Todo in your own example...)

it's the revealed: str in the second branch that already works on your PR! and it wouldn't work unless we intersected the type of x with & ~str & ~bytes & ~bytearray in the first branch

AlexWaygood · 2026-06-06T15:00:03Z

+    /// Positive narrowing uses this as a sound over-approximation: the result
+    /// may include values that fail nested refutable checks, but matching
+    /// values cannot fall outside it.


This is somewhat jargony. It would be great to add an example of Python code that demonstrates what "sound over-approximation" and "nested refutable checks" mean

AlexWaygood · 2026-06-06T18:26:08Z

+    /// For example, consider:
+    ///
+    /// ```python
+    /// case [int(real=0)]:


Suggested change

/// case [int(real=0)]:

/// def f(x: list[object]):

/// match x:

/// case [int(real=0)]:

/// reveal_type(x)

AlexWaygood · 2026-06-06T18:27:14Z

+    /// Every match is a one-element sequence containing an `int`, so the
+    /// returned type records those facts. It does not record the nested
+    /// `real=0` check, so it can also contain values such as `[1]` that fail
+    /// the pattern at runtime. This is intentional for positive narrowing:
+    /// the result may retain extra values, but cannot exclude a possible match.


(I think I understand what this is trying to say, but the wording here still feels a bit awkward to me FWIW... codex is not good at writing prose)

astral-sh#25541 (comment) astral-sh#25493

astral-sh-bot Bot added the ty Multi-file analysis & type inference label May 30, 2026

charliermarsh changed the title ~~[ty] Narrow exact sequence patterns~~ [ty] Add support for narrowing on tuple match cases May 30, 2026

charliermarsh mentioned this pull request May 30, 2026

[ty] Add support for narrowing on tuple match cases #22134

Closed

charliermarsh force-pushed the charlie/pattern-match branch from d5ead3f to 974d660 Compare May 30, 2026 20:36

charliermarsh force-pushed the charlie/pattern-match branch 7 times, most recently from 84e2755 to 26466d9 Compare May 30, 2026 21:04

charliermarsh force-pushed the charlie/tuple-match branch from aea236d to 06e0ff9 Compare June 3, 2026 14:03

charliermarsh force-pushed the charlie/pattern-match branch from 2af8f75 to 4a1649a Compare June 3, 2026 15:14

charliermarsh mentioned this pull request Jun 3, 2026

[ty] Simplify tuple intersections with finite indexed protocols #25599

Draft

Base automatically changed from charlie/tuple-match to main June 3, 2026 16:23

charliermarsh force-pushed the charlie/pattern-match branch from 90ab3f9 to c87d1de Compare June 3, 2026 17:21

charliermarsh assigned AlexWaygood Jun 3, 2026

charliermarsh marked this pull request as ready for review June 3, 2026 17:24

charliermarsh requested review from AlexWaygood, carljm, dcreager, ibraheemdev and sharkdp as code owners June 3, 2026 17:24

charliermarsh marked this pull request as draft June 3, 2026 17:52

charliermarsh force-pushed the charlie/pattern-match branch from c87d1de to 256ced0 Compare June 3, 2026 17:52

AlexWaygood reviewed Jun 3, 2026

View reviewed changes

AlexWaygood reviewed Jun 4, 2026

View reviewed changes

Comment thread crates/ty_python_semantic/src/types/match_pattern.rs Outdated

Comment thread crates/ty_python_semantic/src/types/match_pattern.rs Outdated

AlexWaygood reviewed Jun 4, 2026

View reviewed changes

Comment thread crates/ty_python_semantic/src/types/match_pattern.rs Outdated

Comment thread crates/ty_python_semantic/src/types/match_pattern.rs Outdated

carljm removed their request for review June 4, 2026 15:25

This comment was marked as resolved.

Sign in to view

charliermarsh force-pushed the charlie/pattern-match branch from 37e0039 to 6ab34ac Compare June 5, 2026 13:56

AlexWaygood approved these changes Jun 6, 2026

View reviewed changes

charliermarsh force-pushed the charlie/pattern-match branch from 6ab34ac to afa86eb Compare June 6, 2026 18:20

charliermarsh added 14 commits June 6, 2026 14:21

[ty] Narrow exact sequence patterns

f47d2cf

[ty] Unify definite sequence pattern analysis

7785d74

[ty] Move match pattern types out of reachability

49a2f85

Add star support; clean up tests

03c1144

Add more tests

5502a52

Review feedback

8ee062a

Review feedback

99307da

[ty] Avoid collecting sequence pattern types

09876b6

[ty] Store sequence pattern predicates in a boxed slice

0e34041

[ty] Make exact sequence length checks const

e35ede4

[ty] Build sequence pattern predicates in one pass

eabd929

[ty] Name star pattern predicates explicitly

8aa3964

[ty] Test exact sequence exclusions for text and bytes

e7ccd79

[ty] Explain necessary pattern types with an example

210840d

AlexWaygood approved these changes Jun 6, 2026

View reviewed changes

charliermarsh force-pushed the charlie/pattern-match branch from afa86eb to 210840d Compare June 6, 2026 18:27

Rewrite by human hand

6bc59f9

charliermarsh merged commit 757d823 into main Jun 6, 2026
58 checks passed

charliermarsh deleted the charlie/pattern-match branch June 6, 2026 18:41

thejchap mentioned this pull request Jun 7, 2026

[ty] Support Callable() in match statement class patterns #25541

Merged

thejchap added a commit to thejchap/ruff that referenced this pull request Jun 7, 2026

[ty] Narrow nested Callable class patterns

dd80fa8

astral-sh#25541 (comment) astral-sh#25493

ngnpope mentioned this pull request Jun 11, 2026

Another edge case for tuple match case not narrowing astral-sh/ty#3743

Closed

thejchap added a commit to thejchap/ruff that referenced this pull request Jun 13, 2026

[ty] Narrow nested Callable class patterns

d0ff5ed

astral-sh#25541 (comment) astral-sh#25493

	pub patterns: Vec<PatternPredicateKind<'db>>,
	pub patterns: Box<[PatternPredicateKind<'db>]>,

	.position(\|pattern\| matches!(pattern, PatternPredicateKind::Unsupported))?;
	.position(\|pattern\| pattern == &PatternPredicateKind::Unsupported)?;

	pub fn is_exact_length(&self) -> bool {
	pub const fn is_exact_length(&self) -> bool {

-    /// case [int(real=0)]:
+    /// def f(x: list[object]):
+    ///     match x:
+    ///         case [int(real=0)]:
+    ///             reveal_type(x)

Conversation

charliermarsh commented May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

astral-sh-bot Bot commented May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

True positives changed (5)

Uh oh!

astral-sh-bot Bot commented May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Memory usage report

Uh oh!

astral-sh-bot Bot commented May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

ecosystem-analyzer results

Uh oh!

charliermarsh commented Jun 3, 2026

Uh oh!

AlexWaygood left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as resolved.

AlexWaygood left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

charliermarsh commented May 30, 2026 •

edited

Loading

astral-sh-bot Bot commented May 30, 2026 •

edited

Loading

astral-sh-bot Bot commented May 30, 2026 •

edited

Loading

astral-sh-bot Bot commented May 30, 2026 •

edited

Loading

`ecosystem-analyzer` results