Skip to content

Commit 7da4b8b

Browse files
authored
[ty] Respect bounds and constraints in generic materializations (#27228)
## Summary Respect declared upper bounds and constraints when materializing generic type arguments across covariance, contravariance, and invariance. Preserve constrained top and bottom materializations during type-relation checks, filter valid alternatives safely, and avoid recursively forcing lazy bounds. Narrow runtime class checks using unknown specializations instead of type-parameter defaults, fixing incorrect `Never`-default narrowing. Closes astral-sh/ty#1109. ## Test plan - Add mdtests for PEP 695 and legacy bounded and constrained generics across all variance directions, subtype and assignability relations, overlapping and gradual constraints, and partial unions and intersections. - Cover invariant attributes, getter and setter polarity, unrelated `Any`, mixed constrained and invariant type arguments, and recursive bounds. - Cover positive and negative bounded and constrained `isinstance` narrowing, tuple class information, `issubclass`, class-pattern fallthrough, and `Never`-default regressions. - Cover equivalence for gradual bounded shape aliases, invariant and covariant specializations, and defaulted nested generics. ## Ecosystem Ecosystem changes are all positive and in line with the intended semantics of this PR.
1 parent b20daf7 commit 7da4b8b

9 files changed

Lines changed: 1065 additions & 38 deletions

File tree

‎crates/ty_python_semantic/resources/mdtest/narrow/isinstance.md‎

Lines changed: 200 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -625,6 +625,73 @@ def _(x: object):
625625
reveal_type(x.get()) # revealed: object
626626
```
627627

628+
A bounded covariant generic uses its declared upper bound rather than `object`:
629+
630+
```py
631+
class BoundedCovariant[T: int]:
632+
def get(self) -> T:
633+
raise NotImplementedError
634+
635+
def _(x: object):
636+
if isinstance(x, BoundedCovariant):
637+
reveal_type(x) # revealed: BoundedCovariant[int]
638+
reveal_type(x.get()) # revealed: int
639+
```
640+
641+
Negative narrowing must exclude every specialization of a bounded generic, including a gradual one.
642+
643+
```py
644+
from typing import Any
645+
646+
def excludes_bounded_generic(value: BoundedCovariant[Any] | bool) -> bool:
647+
if isinstance(value, BoundedCovariant):
648+
reveal_type(value) # revealed: BoundedCovariant[Any]
649+
return False
650+
651+
reveal_type(value) # revealed: bool
652+
return value
653+
```
654+
655+
The same exclusion applies when the generic appears in a tuple of runtime classes.
656+
657+
```py
658+
def excludes_bounded_generic_tuple(
659+
value: BoundedCovariant[Any] | bool | bytes,
660+
) -> bool:
661+
if isinstance(value, (BoundedCovariant, bytes)):
662+
reveal_type(value) # revealed: BoundedCovariant[Any] | bytes
663+
return False
664+
665+
reveal_type(value) # revealed: bool
666+
return value
667+
```
668+
669+
Constrained type parameters preserve the materialization of the generic class while making the union
670+
of valid constraints available when reading a covariant attribute:
671+
672+
```py
673+
class ConstrainedCovariant[T: (int, str)]:
674+
def get(self) -> T:
675+
raise NotImplementedError
676+
677+
def _(x: object):
678+
if isinstance(x, ConstrainedCovariant):
679+
reveal_type(x) # revealed: Top[ConstrainedCovariant[Unknown]]
680+
reveal_type(x.get()) # revealed: int | str
681+
```
682+
683+
Constrained generics must also be excluded by negative narrowing.
684+
685+
```py
686+
def excludes_constrained_generic(value: ConstrainedCovariant[Any] | bool) -> bool:
687+
if isinstance(value, ConstrainedCovariant):
688+
reveal_type(value) # revealed: ConstrainedCovariant[Any]
689+
return False
690+
691+
reveal_type(value) # revealed: bool
692+
return value
693+
```
694+
628695
Similarly, contravariant type parameters use their lower bound of `Never`:
629696

630697
```py
@@ -686,7 +753,7 @@ class InvariantWithAny[T: int]:
686753
def _(x: object):
687754
if isinstance(x, InvariantWithAny):
688755
reveal_type(x) # revealed: Top[InvariantWithAny[Unknown]]
689-
reveal_type(x.a) # revealed: object
756+
reveal_type(x.a) # revealed: int
690757
reveal_type(x.b) # revealed: Any
691758
```
692759

@@ -726,6 +793,28 @@ def _(x: Invariant[int] | Covariant[str]):
726793
reveal_type(x) # revealed: Covariant[str] & ~Top[Invariant[Unknown]]
727794
```
728795

796+
The built-in `tuple` stores its variable-length shape separately from its generic type argument.
797+
Narrowing must preserve and materialize that shape.
798+
799+
```py
800+
def narrow_tuple(value: object) -> None:
801+
if isinstance(value, tuple):
802+
reveal_type(value) # revealed: tuple[object, ...]
803+
```
804+
805+
A tuple subclass retains its nominal type and inherits its tuple shape from its specialized base.
806+
The subclass's own type parameter is still materialized using its declared bound.
807+
808+
```py
809+
class BoundedTuple[T: int](tuple[T, str]): ...
810+
811+
def narrow_tuple_subclass(value: object) -> None:
812+
if isinstance(value, BoundedTuple):
813+
reveal_type(value) # revealed: BoundedTuple[int]
814+
reveal_type(value[0]) # revealed: int
815+
reveal_type(value[1]) # revealed: str
816+
```
817+
729818
The behavior of `issubclass()` is similar.
730819

731820
```py
@@ -738,6 +827,65 @@ def _(x: type[object], y: type[object], z: type[object]):
738827
reveal_type(z) # revealed: type[Top[Invariant[Unknown]]]
739828
```
740829

830+
Negative `issubclass()` narrowing also excludes every specialization of a bounded generic.
831+
832+
```py
833+
def excludes_bounded_generic_subclass(
834+
cls: type[BoundedCovariant[Any]] | type[bool],
835+
) -> type[bool]:
836+
if issubclass(cls, BoundedCovariant):
837+
reveal_type(cls) # revealed: type[BoundedCovariant[Any]]
838+
return bool
839+
840+
reveal_type(cls) # revealed: <class 'bool'>
841+
return cls
842+
```
843+
844+
## Narrowing recursively bounded generics
845+
846+
An `isinstance()` check must not recurse indefinitely when a generic bound refers to its own class.
847+
848+
```toml
849+
[environment]
850+
python-version = "3.12"
851+
```
852+
853+
```py
854+
from typing import Any
855+
856+
class Recursive[T: "Recursive[Any]"]: ...
857+
858+
def narrow(value: object) -> None:
859+
if isinstance(value, Recursive):
860+
reveal_type(value) # revealed: Recursive[object]
861+
```
862+
863+
A self-referential bound must also be safe when its recursion is hidden behind a type alias.
864+
865+
```py
866+
class AliasedRecursive[T: "RecursiveAlias"]: ...
867+
868+
type RecursiveAlias = AliasedRecursive[Any]
869+
870+
def narrow_alias(value: object) -> None:
871+
if isinstance(value, AliasedRecursive):
872+
reveal_type(value) # revealed: AliasedRecursive[object]
873+
```
874+
875+
The same cycle recovery must handle bounds shared by mutually recursive generic classes.
876+
877+
```py
878+
class Left[T: "Right[Any]"]: ...
879+
class Right[U: Left[Any]]: ...
880+
881+
def narrow_mutual(value: object) -> None:
882+
if isinstance(value, Left):
883+
reveal_type(value) # revealed: Left[object]
884+
885+
if isinstance(value, Right):
886+
reveal_type(value) # revealed: Right[object]
887+
```
888+
741889
## Narrowing generic defaults in Python 3.13
742890

743891
When a type parameter has a bare `Any` default, narrowing still materializes the substituted
@@ -775,6 +923,57 @@ def _(x: object):
775923
reveal_type(x.y) # revealed: tuple[A, object]
776924
```
777925

926+
`isinstance(value, Box)` checks the runtime class, not the type argument used to specialize it.
927+
Narrowing must therefore preserve the original type argument instead of substituting `Box`'s
928+
default.
929+
930+
```py
931+
from typing import assert_never
932+
933+
class Box[T: str = str]:
934+
value: T
935+
936+
def __init__(self, value: T) -> None: ...
937+
938+
def box_with_default[T: str = str](value: Box[T] | T) -> Box[T]:
939+
if isinstance(value, Box):
940+
reveal_type(value) # revealed: Box[T@box_with_default]
941+
return value
942+
943+
if not isinstance(value, Box):
944+
reveal_type(value) # revealed: T@box_with_default & ~Top[Box[Unknown]]
945+
return Box[T](value)
946+
947+
assert_never(value)
948+
```
949+
950+
When `isinstance()` narrows an unknown value to a tuple subclass, its type argument comes from the
951+
declared upper bound, not the default. Its element types are inherited from the specialized base.
952+
953+
```py
954+
class DefaultedTuple[T: int = bool](tuple[T, str]): ...
955+
956+
def narrow_defaulted_tuple(value: object) -> None:
957+
if isinstance(value, DefaultedTuple):
958+
reveal_type(value) # revealed: DefaultedTuple[int]
959+
reveal_type(value[0]) # revealed: int
960+
reveal_type(value[1]) # revealed: str
961+
```
962+
963+
Negative narrowing also excludes gradual specializations of the defaulted tuple subclass.
964+
965+
```py
966+
def excludes_defaulted_tuple(value: DefaultedTuple[Any] | bool) -> bool:
967+
if isinstance(value, DefaultedTuple):
968+
reveal_type(value) # revealed: DefaultedTuple[Any]
969+
reveal_type(value[0]) # revealed: Any
970+
reveal_type(value[1]) # revealed: str
971+
return False
972+
973+
reveal_type(value) # revealed: bool
974+
return value
975+
```
976+
778977
## Narrowing generic `classmethod`
779978

780979
After an `isinstance(..., classmethod)` branch unwraps and replaces a generic `classmethod`, the

‎crates/ty_python_semantic/resources/mdtest/narrow/match.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,63 @@ def f(x: Covariant[int]):
112112
assert_never(x)
113113
```
114114

115+
## Generic patterns ignore type parameter defaults
116+
117+
A generic class pattern matches every runtime specialization, not only the specialization described
118+
by its type parameter's default.
119+
120+
```toml
121+
[environment]
122+
python-version = "3.13"
123+
```
124+
125+
```py
126+
from typing import Any
127+
128+
class Box[T: str = str]:
129+
value: T
130+
131+
def __init__(self, value: T) -> None: ...
132+
133+
def box_with_default[T: str = str](value: Box[T] | T) -> Box[T]:
134+
match value:
135+
case Box():
136+
reveal_type(value) # revealed: Box[T@box_with_default]
137+
return value
138+
case remaining:
139+
reveal_type(remaining) # revealed: T@box_with_default & ~Top[Box[Unknown]]
140+
return Box[T](remaining)
141+
```
142+
143+
When a class pattern matches a tuple subclass, its type argument comes from the declared upper
144+
bound, not the default. Its element types are inherited from the specialized base.
145+
146+
```py
147+
class DefaultedTuple[T: int = bool](tuple[T, str]): ...
148+
149+
def match_defaulted_tuple(value: object) -> None:
150+
match value:
151+
case DefaultedTuple():
152+
reveal_type(value) # revealed: DefaultedTuple[int]
153+
reveal_type(value[0]) # revealed: int
154+
reveal_type(value[1]) # revealed: str
155+
```
156+
157+
The same pattern excludes gradual specializations from the remaining match arms.
158+
159+
```py
160+
def excludes_defaulted_tuple(value: DefaultedTuple[Any] | bool) -> bool:
161+
match value:
162+
case DefaultedTuple():
163+
reveal_type(value) # revealed: DefaultedTuple[Any]
164+
reveal_type(value[0]) # revealed: Any
165+
reveal_type(value[1]) # revealed: str
166+
return False
167+
case remaining:
168+
reveal_type(remaining) # revealed: bool
169+
return remaining
170+
```
171+
115172
## Class patterns with generic `@final` classes
116173

117174
These work the same as non-`@final` classes.

‎crates/ty_python_semantic/resources/mdtest/type_properties/is_equivalent_to.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,96 @@ static_assert(not is_equivalent_to(type, type[Any]))
8484
static_assert(not is_equivalent_to(type[object], type[Any]))
8585
```
8686

87+
## Equivalent bounded gradual specializations
88+
89+
A bounded generic specialized with a gradual type alias is equivalent to the same generic
90+
specialized with the expanded alias.
91+
92+
```toml
93+
[environment]
94+
python-version = "3.13"
95+
```
96+
97+
For a covariant bounded type parameter, this applies to aliases containing either `Any` or
98+
`Unknown`.
99+
100+
```py
101+
from typing import Any
102+
103+
from ty_extensions import Unknown, static_assert
104+
from ty_extensions._internal import is_equivalent_to
105+
106+
type AnyTuple = tuple[Any, ...]
107+
type UnknownTuple = tuple[Unknown, ...]
108+
109+
class BoundedCovariant[T: tuple[int, ...]]:
110+
def get(self) -> T:
111+
raise NotImplementedError
112+
113+
static_assert(is_equivalent_to(BoundedCovariant[AnyTuple], BoundedCovariant[tuple[Any, ...]]))
114+
static_assert(is_equivalent_to(BoundedCovariant[UnknownTuple], BoundedCovariant[AnyTuple]))
115+
```
116+
117+
The same gradual tuple alias remains equivalent when the bounded type parameter is invariant.
118+
119+
```py
120+
class BoundedInvariant[T: tuple[int, ...]]:
121+
value: T
122+
123+
static_assert(is_equivalent_to(BoundedInvariant[AnyTuple], BoundedInvariant[tuple[Any, ...]]))
124+
```
125+
126+
`Outer[int, Inner]` is equivalent to `Outer[int, Inner[Any]]` because `Inner` defaults to `Any`.
127+
`Outer[int]` is equivalent to the same explicit specialization because `Outer` defaults to
128+
`Inner[Any]`.
129+
130+
```py
131+
class Inner[T: int = Any]:
132+
def get(self) -> T:
133+
raise NotImplementedError
134+
135+
class Outer[T: int, U: Inner[Any] = Inner[Any]]:
136+
def get(self) -> U:
137+
raise NotImplementedError
138+
139+
static_assert(is_equivalent_to(Outer[int, Inner[Any]], Outer[int, Inner]))
140+
static_assert(is_equivalent_to(Outer[int, Inner[Any]], Outer[int]))
141+
```
142+
143+
## Bounded gradual specializations are distinct from upper bounds
144+
145+
A generic specialized with a gradual type argument is not equivalent to the same generic specialized
146+
with the type parameter's upper bound.
147+
148+
```toml
149+
[environment]
150+
python-version = "3.13"
151+
```
152+
153+
For a covariant type parameter:
154+
155+
```py
156+
from typing import Any
157+
158+
from ty_extensions import static_assert
159+
from ty_extensions._internal import is_equivalent_to
160+
161+
class BoundedCovariant[T: tuple[int, ...]]:
162+
def get(self) -> T:
163+
raise NotImplementedError
164+
165+
static_assert(not is_equivalent_to(BoundedCovariant[tuple[Any, ...]], BoundedCovariant[tuple[int, ...]]))
166+
```
167+
168+
The same distinction applies to an invariant type parameter.
169+
170+
```py
171+
class BoundedInvariant[T: tuple[int, ...]]:
172+
value: T
173+
174+
static_assert(not is_equivalent_to(BoundedInvariant[tuple[Any, ...]], BoundedInvariant[tuple[int, ...]]))
175+
```
176+
87177
## Unions and intersections
88178

89179
```pyi

0 commit comments

Comments
 (0)