When inferring a generic call or collection literal against a union
declared type, we currently attempt to narrow the call to the first
member of the union to which the call/literal is assignable when
inferred using that member as type context.
```py
x: list[int] | list[int | str] = list((1,))
reveal_type(x) # revealed: list[int]
y: list[int] | list[int | str] = [1]
reveal_type(y) # revealed: list[int]
```
However, choosing the first member is somewhat arbitrary, as there may
be multiple valid specializations of the call for multiple members of
the union. Notably, this behavior is inconsistent with two other
heuristics:
1. When inferring a dictionary literal against a union of `TypedDict`
types, we infer the valid subset of the union as opposed to the first
matching element.
2. When inferring the specialization of a type variable `T <: A | ...`,
we choose the entire union as opposed to an arbitrary element.
This can lead to issues where wrapping an existing call or dictionary
literal in an identity function (such as `reveal_type`) can trigger
fixpoint iteration, and narrow what was previously a union to an
arbitrary element of that union. Note that this is not necessarily
incorrect (and perhaps even more permissive behavior), but it can be
somewhat unintuitive (see
https://github.com/astral-sh/ruff/pull/26680#discussion_r4229611697),
and I think it has become clear that we should be consistent here.
This PR changes all our generic call/collection literal narrowing logic
to infer the union of all valid narrowing attempts, as opposed to
choosing the first attempt arbitrarily.
```py
x: list[int] | list[int | str] = list((1,))
reveal_type(x) # revealed: list[int] | list[int | str]
y: list[int] | list[int | str] = [1]
reveal_type(y) # revealed: list[int] | list[int | str]
```
Resolves https://github.com/astral-sh/ty/issues/3053.
Resolves https://github.com/astral-sh/ty/issues/4829.
Partially addresses https://github.com/astral-sh/ty/issues/3935.
Use `# ok` as the marker for mdtest statements whose expectation is that
no diagnostic is emitted. Update the guidance in `AGENTS.md` and replace
existing `# no diagnostic` comments in Ruff and ty mdtests.
For `["x"] if flag else []`, ty currently infers `list[Unknown]`.
Similarly, `{"x": 1} if flag else {}` is inferred as `dict[Unknown,
Unknown]`.
Infer the nonempty branch first when the other branch is an empty
literal of the same kind. This lets the empty branch use its peer’s type
as context, so both branch orders infer `list[str]` and `dict[str, int]`
for these examples.
Adapted from @tamird's [original
change](https://github.com/tamird/ruff/commit/7914a959af9d50fed9b741052d0f02d49d3689fa).
---------
Co-authored-by: Tamir Duberstein <tamird@gmail.com>
## Summary
We now recognize exhaustive class patterns over tuple subclasses,
including `NamedTuple`. For example, this function no longer produces an
`invalid-return-type` error:
```python
from typing import NamedTuple
class Point(NamedTuple):
x: bool
def handle(value: Point) -> int:
match value:
case Point():
return 42
```
Tuple expansion now intersects each expanded tuple with the original
subclass, preserving its class identity during reachability analysis and
overload resolution.
Closes https://github.com/astral-sh/ty/issues/4659.
ty can incorrectly treat a branch guarded by an impossible compound
condition as reachable when an operand has potentially mutable
truthiness. For example, `if value and False:` always skips its body in
CPython; the first falsy operand selects the control-flow path
immediately, it doesn't fully evaluate `value and False` and then
re-evaluate the truthiness of the result. Saving `value and False` to a
variable and then testing the saved object can instead call
`value.__bool__` twice and get different answers.
Distinguish expressions consumed directly as conditions from expressions
that produce values. Evaluate direct boolean and conditional expressions
structurally, and retain the combined truthiness of chained comparisons
even when a comparison returns an arbitrary object. Operands with types
equivalent to `Never` cannot produce a result; preserve that distinction
from ambiguous truthiness while composing conditions. Value contexts
continue to allow repeated truthiness checks to disagree.
To limit retained memory, comparison truthiness uses sparse overrides in
optional inference metadata, stored as boxed slices. Ordinary comparison
chains use the truthiness of their inferred value type, and root
chained-comparison conditions reuse expression inference without a
separate condition-analysis memo. Cycle widening preserves overrides
when needed to keep the effective truthiness monotonic. Tracking
operands that cannot produce a result adds only transient evaluation
state.
Prerequisite for #28045, which addresses astral-sh/ty#4380.
## Ecosystem results
Five expected diagnostic removals across pwndbg, pytest, and Spark; no
additions. Each comes from a branch that is unreachable under the
checked platform or declared types. See the [Codex ecosystem
analysis](https://github.com/astral-sh/ruff/pull/28082#issuecomment-5434341797)
for details and minimized reproducers.
## Test plan
- Mdtests cover compound conditions, nested boolean operations and
`not`, conditional expressions, and chained comparisons across branches,
loops, assertions, comprehension filters, and match guards.
- Reachability assertions use revealed variable types, including
reachable saved results, assignment expressions, nested value
expressions, and call arguments whose truthiness can be tested again.
- Cases with operands narrowed to `Never`, aliases and unions of aliases
of `Never`, and type variables bounded by `Never` assert branch
reachability using unrelated variables and check precise
conditional-expression result types.
- Additional cases cover unreachable loop assignments and conditional
expressions in stringified `Annotated` metadata.
- A Rust invariant test covers sparse comparison-truthiness overrides
appearing or disappearing across inference-cycle results, including
preservation of previous-only overrides.
## Summary
Previously, optimistic equality narrowing introduced `True` when
narrowing an `int` against `1` and `False` when narrowing against `0`.
```python
def narrow(value: int) -> None:
assert value in [1, 2]
reveal_type(value) # Literal[1, 2]
```
We now narrow to the integer literals themselves across equality checks,
membership tests, and `match` patterns. Enabling
`strict-equality-semantics` still preserves the original broad type, and
comparisons between known integer and boolean literals retain their
existing behavior.
## Summary
Prior to this change, equality and membership narrowing preserved
otherwise-incompatible union members because a subclass could override
`__eq__`. By default, we now assume that subclasses of a non-final class
do not override the inherited comparison method:
```py
class Foo: ...
def f(value: Foo | None, other: Foo) -> None:
reveal_type(None == other) # Literal[False]
if value == other:
reveal_type(value) # Foo
if value in [other]:
reveal_type(value) # Foo
```
The behavior is intentionally unsound. Users who want conservative
equality behavior can enable the single `strict-equality-narrowing`
setting, which also preserves broad builtin types instead of narrowing
them to literals:
```toml
[tool.ty.analysis]
strict-equality-narrowing = true
```
For compatibility, `strict-literal-narrowing` remains supported as an
alias for `strict-equality-narrowing`.
Closes https://github.com/astral-sh/ty/issues/3419.
## Summary
We already infer the types of captures and aliases in sequence patterns
by following the values passed from each pattern node to its children.
This PR extends the same recursive analysis to class and mapping
patterns.
```python
from dataclasses import dataclass
from typing import Literal, TypedDict
class IntPayload(TypedDict):
tag: Literal["int"]
value: int
class StrPayload(TypedDict):
tag: Literal["str"]
value: str
@dataclass
class Box:
payload: IntPayload | StrPayload
def handle(box: Box) -> None:
match box:
case Box({"tag": "int", "value": value}) as whole:
reveal_type(value) # int
reveal_type(whole) # Box
```
A class pattern passes the selected instance member to each child
pattern. Positional patterns resolve that member through
`__match_args__`; keyword patterns use the named attribute. A mapping
pattern passes the value associated with each matched key, while
`**rest` receives the new dictionary built from the remaining entries.
## Summary
This is the first of three stacked PRs split from #26010.
On `main`, we consider a class pattern exhaustive whenever its
subpatterns are irrefutable. We do not check whether the attributes
requested by the pattern are actually present:
```python
class Base: ...
class Child(Base):
x: int = 0
def missing_attribute(value: Base) -> int:
match value:
case Base(x=_):
return 1
def subject_attribute(value: Child) -> int:
match value:
case Base(x=_):
return 1
```
`main` accepts both functions. This is wrong for `missing_attribute`: a
`Base` instance may not have `x`, so the pattern can fail and the
function can return `None`. However, `subject_attribute` is exhaustive
because its static subject type is `Child`, which guarantees that `x` is
present.
(This isn't exactly right -- Pyright requires that `Child` is `@final`,
but I think this is more consistent with our semantics elsewhere.)
This PR retains the attributes requested by a class pattern and checks
them against the static subject type. With this change,
`missing_attribute` reports `invalid-return-type`, while
`subject_attribute` remains accepted. Nested attribute patterns use the
same check recursively, including inside sequence, `or`, and `as`
patterns.
## Summary
This PR infers the types of names introduced by match patterns.
```python
def unpack(value: tuple[int, str]) -> None:
match value:
case [first, second] as whole:
reveal_type(first) # int
reveal_type(second) # str
reveal_type(whole) # tuple[int, str]
```
The implementation analyzes a successful match recursively: each pattern
receives the type of the value it is matching, computes the type that
can successfully match, and passes the appropriate extracted type to its
children. A capture binds the type it receives; an `as` pattern binds
the successful type of its complete nested pattern.
The analysis also distinguishes facts established while a pattern is
being evaluated from the stable type assigned to an alias. An alias for
a mutable sequence keeps only its sequence type, because later mutation
can invalidate the observed shape; exact tuples can retain facts learned
from their children. For example, we don't narrow here:
```python
def f(value: list[int | str]) -> None:
match value:
case [int(), str()] as whole:
reveal_type(whole) # list[int | str]
reveal_type(len(whole)) # int, not Literal[2]
reveal_type(whole[0]) # int | str, not int
reveal_type(whole[1]) # int | str, not str
```
But we do narrow for an exact tuple:
```python
def f(value: tuple[int | str, int | str]) -> None:
match value:
case [int(), str()] as whole:
reveal_type(len(whole)) # Literal[2]
reveal_type(whole[0]) # int
reveal_type(whole[1]) # str
```
## Summary
Starred sequence patterns currently do not contribute a definite matched
type to negative narrowing. After a case such as `[first, second,
*rest]`, we retain only the sequence protocol constraints even though
the pattern definitely consumes tuples with at least two elements.
This matters for APIs that accept either text or a fixed-shape
structured value:
```python
def normalize_version(
version: str | tuple[int, int] | tuple[int, int, int],
) -> str:
match version:
case [major, minor, *_rest]:
return f"{major}.{minor}"
return version.strip()
```
The starred case consumes every tuple alternative, so the fallback can
narrow `version` to `str` and use string methods normally.
## Summary
https://github.com/astral-sh/ty/issues/887
As titled. Covers:
- Validating proper use in the class pattern, including disallowing
positional sub-patterns
- Reachability analysis
- Narrowing
## Test Plan
New mdtests
---------
Co-authored-by: Carl Meyer <carl@astral.sh>
## 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:
```python
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 https://github.com/astral-sh/ty/issues/561.
Remember when we wrote `x = 1 if flag else None` because we couldn't
infer types from annotated parameters and/or couldn't understand union
type annotations? This PR modernizes our mdtests to simply use annotated
function parameters in those cases (I manually rejected some rewrites
when the new style was less clear, for example when the generated union
type itself was hard to spell).
The motivation for this is to set a better precedent for agents, as I've
seen them repeating that `x if flag else y` pattern, which is really
unnecessary, longer and harder to read in most cases.
## Summary
Any `type` type can only be inhabited by class objects; any `type |
<dynamic type>` union could materialize to a class object; and any
`<class object> & <dynamic type>` intersection is a subtype of a class
object. So using a value that inhabits any of these types as a class
pattern should not cause us to emit the `invalid-match-pattern`
diagnostic.
This PR fixes several false positives that showed up in the ecosystem
report in https://github.com/astral-sh/ruff/pull/22939
## Test Plan
mdtests added
## Summary
Fixes: https://github.com/astral-sh/ty/issues/2592
Adds a new diagnostic to flag called match patterns where the called
object is not a class literal.
## Test Plan
New mdtests
## Ecosystem changes
---------
Co-authored-by: David Peter <mail@david-peter.de>
- Updated the `prek` hook to replace `blacken-docs` with ruff
- Added some formatting directives to preserve obvious intentional
formatting choices
- Made some choice edits to content for better readability with new format
- Formatted md tests and updated snapshots
## Summary
If we match on an `TestEnum | None`, then when adding a case like
`~Literal[TestEnum.FOO]` (i.e., after `if value == TestEnum.FOO:
return`), we'd distribute `Literal[TestEnum.BAR]` on the entire builder,
creating `None & Literal[TestEnum.BAR]` which simplified to `Never`.
Instead, we should only expand to the remaining members for pieces of
the intersection that contain the enum.
Now, `(TestEnum | None) & ~Literal[TestEnum.FOO] &
~Literal[TestEnum.BAR]` correctly simplifies to `None` instead of
`Never`.
Closes https://github.com/astral-sh/ty/issues/2260.
## Summary
Support `as` patterns in reachability analysis:
```py
from typing import assert_never
def f(subject: str | int):
match subject:
case int() as x:
pass
case str():
pass
case _:
assert_never(subject) # would previously emit an error
```
Note that we still don't support inferring correct types for the bound
name (`x`).
Closes https://github.com/astral-sh/ty/issues/928
## Test Plan
New Markdown tests
## Summary
Implements proper reachability analysis and — in effect — exhaustiveness
checking for `match` statements. This allows us to check the following
code without any errors (leads to *"can implicitly return `None`"* on
`main`):
```py
from enum import Enum, auto
class Color(Enum):
RED = auto()
GREEN = auto()
BLUE = auto()
def hex(color: Color) -> str:
match color:
case Color.RED:
return "#ff0000"
case Color.GREEN:
return "#00ff00"
case Color.BLUE:
return "#0000ff"
```
Note that code like this already worked fine if there was a
`assert_never(color)` statement in a catch-all case, because we would
then consider that `assert_never` call terminal. But now this also works
without the wildcard case. Adding a member to the enum would still lead
to an error here, if that case would not be handled in `hex`.
What needed to happen to support this is a new way of evaluating match
pattern constraints. Previously, we would simply compare the type of the
subject expression against the patterns. For the last case here, the
subject type would still be `Color` and the value type would be
`Literal[Color.BLUE]`, so we would infer an ambiguous truthiness.
Now, before we compare the subject type against the pattern, we first
generate a union type that corresponds to the set of all values that
would have *definitely been matched* by previous patterns. Then, we
build a "narrowed" subject type by computing `subject_type &
~already_matched_type`, and compare *that* against the pattern type. For
the example here, `already_matched_type = Literal[Color.RED] |
Literal[Color.GREEN]`, and so we have a narrowed subject type of `Color
& ~(Literal[Color.RED] | Literal[Color.GREEN]) = Literal[Color.BLUE]`,
which allows us to infer a reachability of `AlwaysTrue`.
<details>
<summary>A note on negated reachability constraints</summary>
It might seem that we now perform duplicate work, because we also record
*negated* reachability constraints. But that is still important for
cases like the following (and possibly also for more realistic
scenarios):
```py
from typing import Literal
def _(x: int | str):
match x:
case None:
pass # never reachable
case _:
y = 1
y
```
</details>
closes https://github.com/astral-sh/ty/issues/99
## Test Plan
* I verified that this solves all examples from the linked ticket (the
first example needs a PEP 695 type alias, because we don't support
legacy type aliases yet)
* Verified that the ecosystem changes are all because of removed false
positives
* Updated tests
## Summary
I noticed that our type narrowing and reachability analysis was
incorrect for class patterns that are not irrefutable. The test cases
below compare the old and the new behavior:
```py
from dataclasses import dataclass
@dataclass
class Point:
x: int
y: int
class Other: ...
def _(target: Point):
y = 1
match target:
case Point(0, 0):
y = 2
case Point(x=0, y=1):
y = 3
case Point(x=1, y=0):
y = 4
reveal_type(y) # revealed: Literal[1, 2, 3, 4] (previously: Literal[2])
def _(target: Point | Other):
match target:
case Point(0, 0):
reveal_type(target) # revealed: Point
case Point(x=0, y=1):
reveal_type(target) # revealed: Point (previously: Never)
case Point(x=1, y=0):
reveal_type(target) # revealed: Point (previously: Never)
case Other():
reveal_type(target) # revealed: Other (previously: Other & ~Point)
```
## Test Plan
New Markdown test
## Summary
Add a new `Type::EnumLiteral(…)` variant and infer this type for member
accesses on enums.
**Example**: No more `@Todo` types here:
```py
from enum import Enum
class Answer(Enum):
YES = 1
NO = 2
def is_yes(self) -> bool:
return self == Answer.YES
reveal_type(Answer.YES) # revealed: Literal[Answer.YES]
reveal_type(Answer.YES == Answer.NO) # revealed: Literal[False]
reveal_type(Answer.YES.is_yes()) # revealed: bool
```
## Test Plan
* Many new Markdown tests for the new type variant
* Added enum literal types to property tests, ran property tests
## Ecosystem analysis
Summary:
Lots of false positives removed. All of the new diagnostics are
either new true positives (the majority) or known problems. Click for
detailed analysis</summary>
Details:
```diff
AutoSplit (https://github.com/Toufool/AutoSplit)
+ error[call-non-callable] src/capture_method/__init__.py:137:9: Method `__getitem__` of type `bound method CaptureMethodDict.__getitem__(key: Never, /) -> type[CaptureMethodBase]` is not callable on object of type `CaptureMethodDict`
+ error[call-non-callable] src/capture_method/__init__.py:147:9: Method `__getitem__` of type `bound method CaptureMethodDict.__getitem__(key: Never, /) -> type[CaptureMethodBase]` is not callable on object of type `CaptureMethodDict`
+ error[call-non-callable] src/capture_method/__init__.py:148:1: Method `__getitem__` of type `bound method CaptureMethodDict.__getitem__(key: Never, /) -> type[CaptureMethodBase]` is not callable on object of type `CaptureMethodDict`
```
New true positives. That `__getitem__` method is apparently annotated
with `Never` to prevent developers from using it.
```diff
dd-trace-py (https://github.com/DataDog/dd-trace-py)
+ error[invalid-assignment] ddtrace/vendor/psutil/_common.py:29:5: Object of type `None` is not assignable to `Literal[AddressFamily.AF_INET6]`
+ error[invalid-assignment] ddtrace/vendor/psutil/_common.py:33:5: Object of type `None` is not assignable to `Literal[AddressFamily.AF_UNIX]`
```
Arguably true positives:
https://github.com/DataDog/dd-trace-py/blob/e0a772c28bc3897a4b5df73125274999e0f58f30/ddtrace/vendor/psutil/_common.py#L29
```diff
ignite (https://github.com/pytorch/ignite)
+ error[invalid-argument-type] tests/ignite/engine/test_custom_events.py:190:34: Argument to bound method `__call__` is incorrect: Expected `((...) -> Unknown) | None`, found `Literal["123"]`
+ error[invalid-argument-type] tests/ignite/engine/test_custom_events.py:220:37: Argument to function `default_event_filter` is incorrect: Expected `Engine`, found `None`
+ error[invalid-argument-type] tests/ignite/engine/test_custom_events.py:220:43: Argument to function `default_event_filter` is incorrect: Expected `int`, found `None`
+ error[call-non-callable] tests/ignite/engine/test_custom_events.py:561:9: Object of type `CustomEvents` is not callable
+ error[invalid-argument-type] tests/ignite/metrics/test_frequency.py:50:38: Argument to bound method `attach` is incorrect: Expected `Events`, found `CallableEventWithFilter`
```
All true positives. Some of them are inside `pytest.raises(TypeError,
…)` blocks 🙃
```diff
meson (https://github.com/mesonbuild/meson)
+ error[invalid-argument-type] unittests/internaltests.py:243:51: Argument to bound method `__init__` is incorrect: Expected `bool`, found `Literal[MachineChoice.HOST]`
+ error[invalid-argument-type] unittests/internaltests.py:271:51: Argument to bound method `__init__` is incorrect: Expected `bool`, found `Literal[MachineChoice.HOST]`
```
New true positives. Enum literals can not be assigned to `bool`, even if
their value types are `0` and `1`.
```diff
poetry (https://github.com/python-poetry/poetry)
+ error[invalid-assignment] src/poetry/console/exceptions.py:101:5: Object of type `Literal[""]` is not assignable to `InitVar[str]`
```
New false positive, missing support for `InitVar`.
```diff
prefect (https://github.com/PrefectHQ/prefect)
+ error[invalid-argument-type] src/integrations/prefect-dask/tests/test_task_runners.py:193:17: Argument is incorrect: Expected `StateType`, found `Literal[StateType.COMPLETED]`
```
This is confusing. There are two definitions
([one](https://github.com/PrefectHQ/prefect/blob/74d8cd93eef68600d0c193fa8c4513cf9ac7fdb8/src/prefect/client/schemas/objects.py#L89-L100),
[two](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L40))
of the `StateType` enum. Here, we're trying to assign one to the other.
I don't think that should be allowed, so this is a true positive (?).
```diff
python-htmlgen (https://github.com/srittau/python-htmlgen)
+ error[invalid-assignment] test_htmlgen/form.py:51:9: Object of type `str` is not assignable to attribute `autocomplete` of type `Autocomplete | None`
+ error[invalid-assignment] test_htmlgen/video.py:38:9: Object of type `str` is not assignable to attribute `preload` of type `Preload | None`
```
True positives. [The stubs are
wrong](https://github.com/srittau/python-htmlgen/blob/01e3b911ac282d067850bb324b913e3594bc0e23/htmlgen/form.pyi#L8-L10).
These should not contain type annotations, but rather just `OFF = ...`.
```diff
rotki (https://github.com/rotki/rotki)
+ error[invalid-argument-type] rotkehlchen/tests/unit/test_serialization.py:62:30: Argument to bound method `deserialize` is incorrect: Expected `str`, found `Literal[15]`
```
New true positive.
```diff
vision (https://github.com/pytorch/vision)
+ error[unresolved-attribute] test/test_extended_models.py:302:17: Type `type[WeightsEnum]` has no attribute `DEFAULT`
+ error[unresolved-attribute] test/test_extended_models.py:302:58: Type `type[WeightsEnum]` has no attribute `DEFAULT`
```
Also new true positives. No `DEFAULT` member exists on `WeightsEnum`.