## Summary For `flags |= 2 if enabled else 0`, ty infers the right-hand side once to report diagnostics, then infers it again for each possible value of `flags`. Reuse the first result whenever a union member requests the same type context. An in-place method that supplies a different parameter type still gets its own inference. Cold checks of all 3,032 Python files in [Hydrogram 0.2.0](https://pypi.org/project/hydrogram/0.2.0/) used 11.81–11.86% fewer Cachegrind instructions in opposite orders, with identical diagnostics. Median peak RSS went from 354 to 356 MiB. On [Pyrogram 2.0.106](https://pypi.org/project/Pyrogram/2.0.106/) and [Kurigram 2.2.18](https://pypi.org/project/kurigram/2.2.18/), instructions fell by 10.77–10.90% and 12.10–12.13%, respectively. These measurements are independent of #30733. <!-- ty-pinned-project-instructions:start --> | Project | [Base instructions](https://github.com/astral-sh/ruff/commit/943f623f55c9aa625b0b1b21af731e451819accc) | [PR instructions](https://github.com/astral-sh/ruff/commit/ad41a43210dc493d619acc309c29f09a1f700b4f) | Change | Paired range | | --- | ---: | ---: | ---: | ---: | | [Black](https://github.com/psf/black/tree/55996d1fb8342725c8a19b6023cd9439c3c1d6f7) | 3,111,432,861.5 | 3,106,987,232 | -0.14% | -0.15% to -0.13% | | [discord.py](https://github.com/Rapptz/discord.py/tree/65232c38702be5844cf2ce865a4777eb1928b5d0) (inconclusive) | 7,982,824,012.5 | 7,985,919,661 | +0.04% | -0.07% to +0.15% | | [Home Assistant](https://github.com/home-assistant/core/tree/c19ae285ede74cd64c3045a3a4aa43290c224f1b) | 153,606,801,126.5 | 153,619,604,507.5 | +0.01% | 0.00% to +0.01% | | [isort](https://github.com/pycqa/isort/tree/a514c71ed86c2216d0040c7d60e302ed76a4f7ab) | 1,821,991,264 | 1,806,332,041 | -0.86% | -0.87% to -0.85% | | [Jinja](https://github.com/pallets/jinja/tree/5ef70112a1ff19c05324ff889dd30405b1002044) | 1,901,199,499 | 1,899,945,890 | -0.07% | -0.08% to -0.05% | | [pandas](https://github.com/pandas-dev/pandas/tree/a0225b65720018f4654390bb16d254daa6ee5e54) | 27,660,437,899.5 | 27,639,038,185.5 | -0.08% | -0.09% to -0.06% | | [pandas-stubs](https://github.com/pandas-dev/pandas-stubs/tree/8dd6d91b1c05b26e30f7ddbe3dc3d4042a92bdd6) (inconclusive) | 2,874,786,574 | 2,879,327,689 | +0.16% | -0.08% to +0.40% | | [Prefect](https://github.com/PrefectHQ/prefect/tree/a9452ac21852755311913cb27887b083b5007c03) (inconclusive) | 4,867,665,759 | 4,867,447,750.5 | 0.00% | -0.03% to +0.03% | | [PyTorch](https://github.com/pytorch/pytorch/tree/ab92945cea42e47ae398aead69af0872d340ea0f) (inconclusive) | 93,366,576,567 | 93,280,280,726.5 | -0.09% | -0.18% to 0.00% | | [HTTPX](https://github.com/encode/httpx/tree/b5addb64f0161ff6bfe94c124ef76f6a1fba5254) (inconclusive) | 1,651,607,300 | 1,651,951,001 | +0.02% | -0.04% to +0.09% | | [NumPy](https://github.com/numpy/numpy/tree/f9f1772ce010001208475f751d19253469788410) | 8,215,666,556 | 8,246,219,279 | +0.37% | +0.19% to +0.55% | | [FastAPI](https://github.com/fastapi/fastapi/tree/7a0a3f0b286c6c865cf4398ea0e957a87b8bffa4) (inconclusive) | 2,945,270,182 | 2,948,073,718.5 | +0.10% | +0.04% to +0.15% | | [SQLAlchemy](https://github.com/sqlalchemy/sqlalchemy/tree/10f4d1e2d706a7722ca78e79ce05b00333a7aa5b) (inconclusive) | 20,743,347,188 | 20,706,966,684 | -0.18% | -0.22% to -0.13% | | [Rich](https://github.com/Textualize/rich/tree/9d8f9a372cc5916fd4781fec207ced7ddac2f08f) (inconclusive) | 2,675,169,452 | 2,672,138,432 | -0.11% | -0.26% to +0.03% | | [Django](https://github.com/django/django/tree/b501b8493f31cf8cba31211d59b3b78642b8cb02) (inconclusive) | 13,387,668,563.5 | 13,382,950,844 | -0.04% | -0.12% to +0.05% | | [SymPy](https://github.com/sympy/sympy/tree/85d3998a4517ffbc8a9709b8efa769bb417c174a) | 44,781,928,388 | 44,515,769,040.5 | -0.59% | -0.60% to -0.59% | | [OpenAI Python SDK](https://github.com/openai/openai-python/tree/f6e8480f9a5b2a4d02b17a1da54a1e57964bc312) | 15,429,908,754 | 15,446,170,680.5 | +0.11% | +0.10% to +0.11% | | [pytest](https://github.com/pytest-dev/pytest/tree/8b005ed7f972987033ec34dc1e68b0635fb8142b) | 8,584,280,557 | 8,603,718,525 | +0.23% | +0.21% to +0.25% | | [aiohttp](https://github.com/aio-libs/aiohttp/tree/fe099491d275ef2c21bf683e024e34d51ac05d43) (inconclusive) | 4,065,516,071.5 | 4,059,651,532.5 | -0.14% | -0.24% to -0.05% | | [Ansible](https://github.com/ansible/ansible/tree/b4b2b1e82a535d27f902a71fc8396c3af138fca2) (inconclusive) | 14,018,836,842.5 | 14,003,879,311.5 | -0.11% | -0.13% to -0.08% | | [botocore](https://github.com/boto/botocore/tree/e250abbe956da791c16086575e6ddb1f2da81a78) (inconclusive) | 2,934,906,286.5 | 2,934,155,492 | -0.03% | -0.04% to -0.01% | | [Celery](https://github.com/celery/celery/tree/9c2f238334331db43f15956f131235fd3bb70fd1) (inconclusive) | 4,647,856,232.5 | 4,650,882,946.5 | +0.07% | +0.04% to +0.09% | | [Dask](https://github.com/dask/dask/tree/249a51a1db4261791b93b4ce04e67341729939c3) (inconclusive) | 32,508,616,530.5 | 32,478,415,568 | -0.09% | -0.11% to -0.08% | | [NetworkX](https://github.com/networkx/networkx/tree/6855cd586982cc2e4710b8eb87251ccf56674bf1) | 15,209,837,729.5 | 15,173,774,828.5 | -0.24% | -0.27% to -0.20% | | [Pydantic](https://github.com/pydantic/pydantic/tree/560f0f96a37d6913afdfddb2de22030ef08e68c3) (inconclusive) | 12,880,720,290.5 | 12,890,463,033 | +0.08% | +0.04% to +0.11% | | [scikit-learn](https://github.com/scikit-learn/scikit-learn/tree/ee56c8b5d809dc7b970a140ed501269b63c69cf8) | 58,213,246,251.5 | 58,037,790,726 | -0.30% | -0.30% to -0.30% | | [Scrapy](https://github.com/scrapy/scrapy/tree/e63a574c767d7a9438c21db158f605f1c44c6e6a) (inconclusive) | 8,732,083,412 | 8,736,233,365.5 | +0.05% | +0.04% to +0.05% | | [Transformers](https://github.com/huggingface/transformers/tree/3a134bc37f7c22c801b618e289b0255425f22647) | 96,550,522,801 | 96,431,491,920 | -0.12% | -0.16% to -0.09% | <!-- ty-pinned-project-instructions:end -->
113 KiB
Bidirectional type inference
ty partially supports bidirectional type inference. This is a mechanism for inferring the type of an expression "from the outside in". Normally, type inference proceeds "from the inside out". That is, in order to infer the type of an expression, the types of all sub-expressions must first be inferred. There is no reverse dependency. However, when performing complex type inference, such as when generics are involved, the type of an outer expression can sometimes be useful in inferring inner expressions. Bidirectional type inference is a mechanism that propagates such "expected types" to the inference of inner expressions.
[environment]
python-version = "3.13"
Type context sources
Type context is sourced from various places, including annotated assignments:
from typing import Literal
a: list[Literal[1]] = [1]
Function parameter annotations:
def b(x: list[Literal[1]]): ...
b([1])
Bound method parameter annotations:
class C:
def __init__(self, x: list[Literal[1]]): ...
def foo(self, x: list[Literal[1]]): ...
C([1]).foo([1])
Declared variable types:
d: list[Literal[1]]
d = [1]
Declared attribute types:
class E:
a: list[Literal[1]]
b: list[Literal[1]]
def _(e: E):
e.a = [1]
E.b = [1]
Function return types:
def f() -> list[Literal[1]]:
return [1]
Loop-carried assignment context
A declaration inside a loop provides context to assignments that reach it from an earlier iteration.
While loops
A declaration inside a while loop applies to list literals assigned in each iteration.
while True:
values: list[object]
values = [1]
reveal_type(values) # revealed: list[object]
For loops
The same declaration context applies to assignments in a for loop.
for _ in range(2):
values: list[object]
values = [1]
reveal_type(values) # revealed: list[object]
Nested dictionary values
A declaration inside a loop also provides context for values nested within a dictionary literal.
from typing import TypedDict
class Record(TypedDict):
values: list[float]
while True:
record: Record
record = {"values": [1]}
reveal_type(record) # revealed: Record
Invalid dictionary values
An incompatible dictionary item is reported at the assignment, not at the declaration.
from typing import TypedDict
class Record(TypedDict):
value: int
while True:
record: Record
record = {"value": "invalid"} # error: [invalid-argument-type]
reveal_type(record) # revealed: Record
Stringified annotations
String annotations provide their resolved type when a loop-carried assignment needs context.
while True:
values: "list[object]"
values = [1]
reveal_type(values) # revealed: list[object]
Deferred forward references
Deferred annotations resolve a TypedDict defined after the loop before inferring its dictionary
assignments.
from __future__ import annotations
from typing import TypedDict
for _ in range(2):
record: Record
record = {"value": 1}
reveal_type(record) # revealed: Record
invalid: Record
invalid = {"value": "invalid"} # error: [invalid-argument-type]
class Record(TypedDict):
value: int
Deferred forward references in overloaded calls
Selecting an overload must not recursively infer a loop-carried forward reference before its
declared TypedDict is available.
from __future__ import annotations
from typing import Never, TypedDict, overload
@overload
def inspect(value: str) -> Never: ...
@overload
def inspect(value: object) -> int: ...
def inspect(value: object) -> int:
return 1
for _ in range(2):
record: Record
record = {"value": 1}
inspect(record)
reveal_type(record) # revealed: Record
record["missing"] # error: [invalid-typed-dict-key]
class Record(TypedDict):
value: int
Deferred forward references in nested non-function loops
A loop-carried forward reference keeps its declared type when the module-level loop is nested inside a conditional.
from __future__ import annotations
from typing import Never, TypedDict, overload
@overload
def inspect(value: str) -> Never: ...
@overload
def inspect(value: object) -> int: ...
def inspect(value: object) -> int:
return 1
if bool(input()) and bool(input()):
for _ in range(2):
record: ModuleRecord
record = {"value": 1}
inspect(record)
reveal_type(record) # revealed: ModuleRecord
class ModuleRecord(TypedDict):
value: int
A statically known outer branch also preserves the loop-carried declaration.
if 1 + 1 == 2:
for _ in range(2):
record: StaticModuleRecord
record = {"value": 1}
inspect(record)
reveal_type(record) # revealed: StaticModuleRecord
class StaticModuleRecord(TypedDict):
value: int
TODO: In class-body while loops, eager collection cycle recovery loses the declared TypedDict
context.
class Container:
while bool(input()):
record: ClassRecord # error: [invalid-declaration]
record = {"value": 1}
inspect(record)
reveal_type(record) # revealed: dict[str, int]
class ClassRecord(TypedDict):
value: int
Deferred forward references on Python 3.14
Annotations are deferred by default in Python 3.14 and later.
[environment]
python-version = "3.14"
from typing import TypedDict
for _ in range(2):
record: Record
record = {"value": 1}
reveal_type(record) # revealed: Record
class Record(TypedDict):
value: int
Collection literals
Basic
import typing
a: list[int] = [1, 2, 3]
reveal_type(a) # revealed: list[int]
b: list[int | str] = [1, 2, 3]
reveal_type(b) # revealed: list[int | str]
c: typing.List[int] = [1, 2, 3]
reveal_type(c) # revealed: list[int]
d: list[typing.Any] = []
reveal_type(d) # revealed: list[Any]
e: set[int] = {1, 2, 3}
reveal_type(e) # revealed: set[int]
f: set[int | str] = {1, 2, 3}
reveal_type(f) # revealed: set[int | str]
g: typing.Set[int] = {1, 2, 3}
reveal_type(g) # revealed: set[int]
h: list[list[int]] = [[], [42]]
reveal_type(h) # revealed: list[list[int]]
i: list[typing.Any] = [1, 2, "3", ([4],)]
reveal_type(i) # revealed: list[Any]
j: list[tuple[str | int, ...]] = [(1, 2), ("foo", "bar"), ()]
reveal_type(j) # revealed: list[tuple[str | int, ...]]
k: list[tuple[list[int], ...]] = [([],), ([1, 2], [3, 4]), ([5], [6], [7])]
reveal_type(k) # revealed: list[tuple[list[int], ...]]
l: tuple[list[int], *tuple[list[typing.Any], ...], list[str]] = ([1, 2, 3], [4, 5, 6], [7, 8, 9], ["10", "11", "12"])
reveal_type(l) # revealed: tuple[list[int], list[Any], list[Any], list[str]]
type IntList = list[int]
m: IntList = [1, 2, 3]
reveal_type(m) # revealed: list[int]
n: list[typing.Literal[1, 2, 3]] = [1, 2, 3]
reveal_type(n) # revealed: list[Literal[1, 2, 3]]
o: list[typing.LiteralString] = ["a", "b", "c"]
reveal_type(o) # revealed: list[LiteralString]
p: dict[int, int] = {}
reveal_type(p) # revealed: dict[int, int]
q: dict[int | str, int] = {1: 1, 2: 2, 3: 3}
reveal_type(q) # revealed: dict[int | str, int]
r: dict[int | str, int | str] = {1: 1, 2: 2, 3: 3}
reveal_type(r) # revealed: dict[int | str, int | str]
s: dict[int | str, int | str]
s = {1: 1, 2: 2, 3: 3}
reveal_type(s) # revealed: dict[int | str, int | str]
(s := {1: 1, 2: 2, 3: 3})
reveal_type(s) # revealed: dict[int | str, int | str]
Exact float types in covariant contexts
A covariant collection context must preserve an exact float when numeric promotion would introduce
an int that the expected element type rejects.
from collections.abc import Iterable, Sequence
from ty_extensions import JustFloat
def takes_exact_sequence(values: Sequence[JustFloat]) -> None: ...
def takes_exact_iterable(values: Iterable[JustFloat]) -> None: ...
def takes_exact_list(values: list[JustFloat]) -> None: ...
takes_exact_sequence([1.0])
takes_exact_sequence((1.0,))
takes_exact_sequence([1]) # error: [invalid-argument-type]
takes_exact_iterable([1.0])
takes_exact_iterable((1.0,))
takes_exact_iterable([1]) # error: [invalid-argument-type]
takes_exact_list([1.0])
annotated: list[JustFloat] = [1.0]
takes_exact_sequence(annotated)
Ordinary float contexts and unannotated mutable lists must retain numeric promotion.
def takes_float_sequence(values: Sequence[float]) -> None: ...
takes_float_sequence([1.0])
takes_float_sequence([1])
mutable_floats = [1.0]
mutable_floats.append(1)
reveal_type(mutable_floats) # revealed: list[float]
Exact complex types in covariant contexts
The same contextual restriction applies when promoting an exact complex number would introduce int
and float.
from collections.abc import Sequence
from ty_extensions import JustComplex
def takes_exact_complexes(values: Sequence[JustComplex]) -> None: ...
takes_exact_complexes([1j])
takes_exact_complexes((1j,))
takes_exact_complexes([1]) # error: [invalid-argument-type]
takes_exact_complexes([1.0]) # error: [invalid-argument-type]
Exact-type protocols in covariant contexts
A writable __class__ property allows an invariant protocol to distinguish a runtime float from an
integer. A covariant sequence of a union containing this protocol must preserve that distinction.
from collections.abc import Sequence
from typing import Generic, Protocol, TypeVar
T = TypeVar("T")
class Just(Protocol, Generic[T]):
@property
def __class__(self, /) -> type[T]: ...
@__class__.setter
def __class__(self, value: type[T], /) -> None: ...
def takes_exact_float(value: Just[float]) -> None: ...
def takes_exact_values(values: Sequence[str | Just[float]]) -> None: ...
takes_exact_float(1.0)
takes_exact_float(1) # error: [invalid-argument-type]
takes_exact_values(["1", 1.0])
takes_exact_values(["1", float("nan")])
takes_exact_values(("1", 1.0))
takes_exact_values(["1", 1]) # error: [invalid-argument-type]
annotated: list[str | Just[float]] = ["1", 1.0]
takes_exact_values(annotated)
Optional unions
import typing
a: list[int] | None = [1, 2, 3]
reveal_type(a) # revealed: list[int]
b: list[int | str] | None = [1, 2, 3]
reveal_type(b) # revealed: list[int | str]
c: typing.List[int] | None = [1, 2, 3]
reveal_type(c) # revealed: list[int]
d: list[typing.Any] | None = []
reveal_type(d) # revealed: list[Any]
e: set[int] | None = {1, 2, 3}
reveal_type(e) # revealed: set[int]
f: set[int | str] | None = {1, 2, 3}
reveal_type(f) # revealed: set[int | str]
g: typing.Set[int] | None = {1, 2, 3}
reveal_type(g) # revealed: set[int]
h: list[list[int]] | None = [[], [42]]
reveal_type(h) # revealed: list[list[int]]
i: list[typing.Any] | None = [1, 2, "3", ([4],)]
reveal_type(i) # revealed: list[Any]
j: list[tuple[str | int, ...]] | None = [(1, 2), ("foo", "bar"), ()]
reveal_type(j) # revealed: list[tuple[str | int, ...]]
k: list[tuple[list[int], ...]] | None = [([],), ([1, 2], [3, 4]), ([5], [6], [7])]
reveal_type(k) # revealed: list[tuple[list[int], ...]]
l: tuple[list[int], *tuple[list[typing.Any], ...], list[str]] | None = ([1, 2, 3], [4, 5, 6], [7, 8, 9], ["10", "11", "12"])
reveal_type(l) # revealed: tuple[list[int], list[Any], list[Any], list[str]]
type IntList = list[int]
m: IntList | None = [1, 2, 3]
reveal_type(m) # revealed: list[int]
n: list[typing.Literal[1, 2, 3]] | None = [1, 2, 3]
reveal_type(n) # revealed: list[Literal[1, 2, 3]]
o: list[typing.LiteralString] | None = ["a", "b", "c"]
reveal_type(o) # revealed: list[LiteralString]
p: dict[int, int] | None = {}
reveal_type(p) # revealed: dict[int, int]
q: dict[int | str, int] | None = {1: 1, 2: 2, 3: 3}
reveal_type(q) # revealed: dict[int | str, int]
r: dict[int | str, int | str] | None = {1: 1, 2: 2, 3: 3}
reveal_type(r) # revealed: dict[int | str, int | str]
Starred elements and dictionary unpacking
from typing import Any
x1: list[int] = [1, 2, *(3, 4, 5)]
reveal_type(x1) # revealed: list[int]
x2: list[list[int]] = [[1], [2], *([3], [4])]
reveal_type(x2) # revealed: list[list[int]]
x3: dict[str, int] = {"a": 1, **{"b": 2}}
reveal_type(x3) # revealed: dict[str, int]
def dynamic_mapping() -> Any: ...
x4: dict[str, int] = reveal_type({**dynamic_mapping()}) # revealed: dict[str | Any, int | Any]
# error: [invalid-argument-type] "Argument expression after ** must be a mapping type"
x5: dict[str, int] = {**42}
Collection literal narrowing
When a collection literal is inferred against a union declared type, the literal expression is inferred independently against each member of the union, producing the union of all valid specializations of the literal.
from collections.abc import Mapping, Sequence
from typing import Literal
x1: list[int | str] | list[int | None] = [1, 2, 3]
reveal_type(x1) # revealed: list[int | str] | list[int | None]
x2: set[int | str] | set[int | None] = {1}
reveal_type(x2) # revealed: set[int | str] | set[int | None]
x3: dict[str, int | str] | dict[str, int | None] = {"key": 1}
reveal_type(x3) # revealed: dict[str, int | str] | dict[str, int | None]
x4: list[int] | list[int | None] | list[str | None] = ["1", "2"]
reveal_type(x4) # revealed: list[str | None]
x5: Sequence[int | str] | Sequence[int | None] = [1, 2, 3]
reveal_type(x5) # revealed: list[int]
x6: dict[str, list[int | None]] | dict[str, list[str | None]] = {"a": ["b"]}
reveal_type(x6) # revealed: dict[str, list[str | None]]
x7: Mapping[str, list[int | None]] | Mapping[str, list[str | None]] = {"a": ["b"]}
reveal_type(x7) # revealed: dict[str, list[str | None]]
def _(x8: list[dict[str, list[int] | int] | dict[str, list[int]]]):
x8.append(reveal_type({"b": 1})) # revealed: dict[str, list[int] | int]
The same narrowing applies when the union is nested behind a type alias.
type EitherList = list[int | str] | list[int | None]
x1: EitherList = [None, None]
reveal_type(x1) # revealed: list[int | None]
x2: EitherList = ["1", "2", "3"]
reveal_type(x2) # revealed: list[int | str]
type SelfOp[T] = Mapping[Literal["$eq", "$ne"], T]
type ListOp[T] = Mapping[Literal["$in", "$nin"], Sequence[T]]
type Ops[T] = SelfOp[T] | ListOp[T]
type NestedOp[T] = T | Ops[T]
x3: NestedOp[str] = {"$in": ["a", "b"]}
reveal_type(x3) # revealed: dict[Literal["$in", "$nin"], list[str]]
Comprehensions perform narrowing similarly.
x1: list[int | str] | list[int | None] = [i for i in range(3)]
reveal_type(x1) # revealed: list[int | str] | list[int | None]
x2: dict[str, int | str] | dict[str, int | None] = {str(i): i for i in range(3)}
reveal_type(x2) # revealed: dict[str, int | str] | dict[str, int | None]
As well as tuple literals.
def _(key: str):
x1: tuple[int, list[str]] | tuple[str, list[int]] = (key, [True])
reveal_type(x1) # revealed: tuple[str, list[int]]
x2: tuple[int, list[int]] | tuple[str, list[str]] = (key, [])
reveal_type(x2) # revealed: tuple[str, list[str]]
x3: tuple[list[int], list[str]] | tuple[list[str], list[int]] = ([], [])
reveal_type(x3) # revealed: tuple[list[int], list[str]] | tuple[list[str], list[int]]
When a collection literal is narrowed to a single element of the union, any diagnostics emitted use the types inferred using that element as type context.
from typing import Callable, TypedDict
# revealed: int
x1: list[Callable[[int], object]] | str = [lambda value: reveal_type(value)]
reveal_type(x1) # revealed: list[(int, /) -> object]
# revealed: int
x2: tuple[Callable[[int], object]] | str = (lambda value: reveal_type(value),)
reveal_type(x2) # revealed: tuple[(value: int) -> int]
class A(TypedDict):
value: int
x3: list[A] | str = [reveal_type({"value": 1})] # revealed: A
reveal_type(x3) # revealed: list[A]
When a literal instead produces multiple valid specializations, diagnostics fall back to the types inferred without type context.
# revealed: Unknown
x1: list[Callable[[int], object]] | list[Callable[[str], object]] = [lambda value: reveal_type(value)]
reveal_type(x1) # revealed: list[(int, /) -> object] | list[(str, /) -> object]
# revealed: Unknown
x2: tuple[Callable[[int], object]] | tuple[Callable[[str], object]] = (lambda value: reveal_type(value),)
# TODO: This should reveal `tuple[(value: int) -> int] | tuple[(value: str) -> str]`.
reveal_type(x2) # revealed: tuple[(value: int) -> object] | tuple[(value: str) -> object]
x3: list[A] | list[dict[str, int]] = [reveal_type({"value": 1})] # revealed: dict[str, int]
reveal_type(x3) # revealed: list[A] | list[dict[str, int]]
Binary operations
def singleton[T](x: T) -> list[T]:
return [x]
x1: list[list[int | str]] = [[1], [2]] * 3
reveal_type(x1) # revealed: list[list[int | str]]
x2: list[list[int | str]] = 3 * ([[1]] + [[2]])
reveal_type(x2) # revealed: list[list[int | str]]
x3: list[int | str] = 3 * ["x" for _ in range(3)]
reveal_type(x3) # revealed: list[int | str]
x4: set[int | str] = {1, 2} | {3, 4}
reveal_type(x4) # revealed: set[int | str]
x5: dict[int | str, int | str] = {1: 2} | {3: 4}
reveal_type(x5) # revealed: dict[int | str, int | str]
# TODO: We currently eagerly pass type context to collection literals on either side of a binary
# operator. That makes the cases above work, but it is not generally sound.
class X:
def __add__(self, _: list[int]) -> list[int | str]:
return []
# error: [unsupported-operator] "Operator `+` is not supported between objects of type `X` and `list[int | str]`"
x6: list[int | str] = X() + [1]
# TODO: We do not yet propagate type context through the generic call.
# error: [invalid-assignment] "Object of type `list[int]` is not assignable to `list[int | str]`"
x7: list[int | str] = singleton(42) * 3
Comprehensions
x1: set[int | str] = {42 for _ in range(3)}
reveal_type(x1) # revealed: set[int | str]
x2: dict[int | str, int | str] = {str(i): i for i in range(3)}
reveal_type(x2) # revealed: dict[int | str, int | str]
Tuple expressions
from typing import Literal
def singleton[T](x: T) -> list[T]:
return [x]
# Tuple elements are inferred individually, but type context can prevent e.g. `int` widening.
x1: tuple[list[Literal[1]]] = (singleton(1),)
reveal_type(x1) # revealed: tuple[list[Literal[1]]]
x2: tuple[list[Literal[1]], ...] = (singleton(1),) * 3
reveal_type(x2) # revealed: tuple[list[Literal[1]], ...]
x3: tuple[list[Literal[1]], ...] = 3 * ((singleton(1),) + (singleton(1),))
reveal_type(x3) # revealed: tuple[list[Literal[1]], ...]
Type context also reaches mutable elements inside a starred list literal. Preserving their positions in the resulting tuple does not discard the element annotations.
x4: tuple[list[Literal[1]], ...] = (*[[1], []],)
reveal_type(x4) # revealed: tuple[list[Literal[1]], list[Literal[1]]]
Generator expressions
from collections.abc import AsyncGenerator, AsyncIterable, Generator, Iterable
class TextContent: ...
class TagContent: ...
def expects_generator_content(content: Generator[list[TextContent | TagContent], None, None]) -> None: ...
def expects_iterable_content(content: Iterable[list[TextContent | TagContent]]) -> None: ...
def expects_optional_iterable_content(content: Iterable[list[TextContent | TagContent]] | None) -> None: ...
def generator_content() -> None:
expects_generator_content([TextContent()] for _ in range(1))
expects_iterable_content([TextContent()] for _ in range(1))
expects_optional_iterable_content([TextContent()] for _ in range(1))
expects_generator_content((reveal_type([TextContent()]) for _ in range(1))) # revealed: list[TextContent | TagContent]
def expects_int_iterable_or_str_generator(content: Generator[list[str], int, None] | Iterable[list[int]]) -> None: ...
def generator_content_with_incompatible_generator_arm() -> None:
expects_int_iterable_or_str_generator((reveal_type([]) for _ in range(1))) # revealed: list[int]
def invalid_generator_content() -> None:
expects_generator_content([object()] for _ in range(1)) # error: [invalid-argument-type]
expects_optional_iterable_content([object()] for _ in range(1)) # error: [invalid-argument-type]
async def async_texts() -> AsyncGenerator[TextContent, None]:
yield TextContent()
def expects_async_generator_content(content: AsyncGenerator[list[TextContent | TagContent], None]) -> None: ...
def expects_async_iterable_content(content: AsyncIterable[list[TextContent | TagContent]]) -> None: ...
async def async_generator_content() -> None:
expects_async_generator_content([TextContent()] async for _ in async_texts())
expects_async_iterable_content([TextContent()] async for _ in async_texts())
async def invalid_async_generator_content() -> None:
expects_async_generator_content([object()] async for _ in async_texts()) # error: [invalid-argument-type]
Generic call inference
The declared type of a generic call expression is used to infer a more assignable specialization for the callable:
from typing import Literal
def f[T](x: T) -> list[T]:
return [x]
x1 = f("a")
reveal_type(x1) # revealed: list[str]
x2: list[int | Literal["a"]] = f("a")
reveal_type(x2) # revealed: list[int | Literal["a"]]
x3: list[int | str] = f("a")
reveal_type(x3) # revealed: list[int | str]
x4: list[int | tuple[int, int]] = f((1, 2))
reveal_type(x4) # revealed: list[int | tuple[int, int]]
x5: list[int] = f(True)
reveal_type(x5) # revealed: list[int]
# error: [invalid-assignment] "Object of type `list[str]` is not assignable to `list[int]`"
x6: list[int] = f("a")
# error: [invalid-assignment] "Object of type `list[str]` is not assignable to `tuple[int]`"
x7: tuple[int] = f("a")
def f2[T: int](x: T) -> T:
return x
x8: int = f2(True)
reveal_type(x8) # revealed: Literal[True]
x9: int | str = f2(True)
reveal_type(x9) # revealed: Literal[True]
from typing import Callable, overload
def singleton[T](x: T) -> list[T]:
return [x]
x10: list[int | str] | None = singleton(1)
reveal_type(x10) # revealed: list[int | str]
def value_or_list[T](x: T, cond: bool) -> T | list[T]:
return x if cond else [x]
x11: int | list[int] = value_or_list(1, True)
reveal_type(x11) # revealed: int | list[int]
def returns_objects() -> list[object]:
reveal_type(singleton(1)) # revealed: list[int]
# `list[int]` and `list[object]` are incompatible, but the return type check passes because
# this call is inferred using the annotated return type.
return singleton(1)
def returns_optional_objects() -> list[object] | None:
return singleton(1)
def deco[T](func: Callable[[], T]) -> Callable[[], T]:
return func
def outer() -> Callable[[], list[object]]:
@deco
def inner() -> list[object]:
return singleton(1)
return inner
@overload
def overloaded(x: int) -> list[int]: ...
@overload
def overloaded(x: str) -> list[str]: ...
def overloaded(x: int | str) -> list[int] | list[str]:
# `list[int] | list[str]` is disjoint from `list[int | str]`.
if isinstance(x, int):
return singleton(x)
else:
return singleton(x)
reveal_type(overloaded(1)) # revealed: list[int]
reveal_type(overloaded("a")) # revealed: list[str]
async def async_return() -> list[int | str]:
return singleton(1)
def forward[T](x: T, cond: bool) -> T | list[T]:
return forwarded(x, cond)
def forwarded[T](x: T, cond: bool) -> T | list[T]:
return x if cond else [x]
Missing annotations do not supply declared type context
A missing annotation does not supply type context for a return or argument expression:
from ty_extensions._internal import Unknown
def identity[T](x: T) -> T:
return x
def unannotated(x):
return reveal_type(identity(1)) # revealed: Literal[1]
def annotated(x: Unknown) -> Unknown:
return reveal_type(identity(1)) # revealed: Unknown
unannotated(reveal_type(identity(1))) # revealed: Literal[1]
annotated(reveal_type(identity(1))) # revealed: Unknown
A generic call in a bare Final initializer infers its return type from its argument.
from typing import Final
ONE: Final = reveal_type(identity(1)) # revealed: Literal[1]
A call through an unannotated parameter supplies no expected type for its arguments. A callable with
a parameter annotated as Any supplies Any as context.
from collections.abc import Callable
from typing import Any
def call(sink, typed_sink: Callable[[Any], None]):
sink(reveal_type(identity(1))) # revealed: Literal[1]
typed_sink(reveal_type(identity(1))) # revealed: Any
A generator without a return annotation leaves the operands of yield and yield from to
inference. An explicit return annotation supplies its declared element type, including Any or
Unknown.
from collections.abc import Iterator
def singleton[T](x: T) -> list[T]:
return [x]
def values():
yield reveal_type(identity(1)) # revealed: Literal[1]
yield from reveal_type(singleton(1)) # revealed: list[int]
def annotated_values() -> Iterator[Any]:
yield reveal_type(identity(1)) # revealed: Any
yield from reveal_type(singleton(1)) # revealed: list[Any]
def unknown_values() -> Iterator[Unknown]:
yield reveal_type(identity(1)) # revealed: Unknown
yield from reveal_type(singleton(1)) # revealed: list[Unknown]
Upper-bound type context
The declared upper bound of a type variable provides type context for a nested generic call:
def singleton[T](value: T) -> list[T]:
return [value]
def bounded[T: list[int]](value: T) -> T:
return value
reveal_type(singleton(True)) # revealed: list[bool]
reveal_type(bounded(singleton(True))) # revealed: list[int]
Declared upper bounds also restrict the range of an inferred gradual solution:
from collections.abc import Callable, Sequence
from typing import Any
def singleton_sequence[T](value: T) -> Sequence[T]:
return [value]
def bounded_sequence[T: Sequence[int]](value: T) -> T:
return value
def consumer[T](value: T) -> Callable[[T], None]:
return lambda _: None
def bounded_consumer[T: Callable[[int], None]](value: T) -> T:
return value
def _(value: Any):
# TODO: This should be `Sequence[Any & int]`.
reveal_type(bounded_sequence(singleton_sequence(value))) # revealed: Sequence[Any]
# TODO: This should be `list[int]`.
reveal_type(bounded(singleton(value))) # revealed: list[Any | int]
reveal_type(bounded_consumer(consumer(value))) # revealed: (Any | int, /) -> None
However, it does not restrict the range of a gradual declared type:
def _[T: int](gradual: Sequence[Any], values: Sequence[T]):
x1: Sequence[Any] = reveal_type(bounded_sequence(gradual)) # revealed: Sequence[Any]
x2: Sequence[Any] = reveal_type(bounded_sequence(values)) # revealed: Sequence[Any]
The argument of a callable is narrowed based on outer type context:
def from_callback[T](f: Callable[[T], None]) -> list[T]:
return []
def _(f: Callable[[object], None]):
reveal_type(from_callback(f)) # revealed: list[object]
reveal_type(bounded(from_callback(f))) # revealed: list[int]
Upper bounds also provide context for TypedDict and lambda parameters:
from typing import TypedDict
class Payload(TypedDict):
value: int
def payload[T: Payload](value: T) -> T:
return value
def callback[T: Callable[[int], list[int]]](value: T) -> T:
return value
reveal_type(payload({"value": 1})) # revealed: Payload
reveal_type(callback(lambda value: [value])) # revealed: (value: int) -> list[int]
Declared upper bounds are also propagated through lambda bodies, without restricting the range of nested gradual types:
def _(value: Any):
f = callback(lambda _: singleton(value))
reveal_type(f(1)) # revealed: list[Any | int]
annotated: Callable[[int], list[int]] = lambda _: singleton(value)
reveal_type(annotated(1)) # revealed: list[int]
As well as through nested TypedDict literals and constructor calls:
def identity[T](value: T) -> T:
return value
def _(value: Any):
payload({"value": reveal_type(identity(value))}) # revealed: Any
literal: Payload = {"value": reveal_type(identity(value))} # revealed: int
payload(dict(value=reveal_type(identity(value)))) # revealed: Any
constructed: Payload = dict(value=reveal_type(identity(value))) # revealed: int
Upper-bound context without inference evidence
If there are no inferred or declared constraints for a given type variable, it remains unsolved, despite lower and upper validity bounds:
def empty[T]() -> T:
raise NotImplementedError
def bounded[T: int](value: T) -> T:
return value
reveal_type(bounded(empty())) # revealed: Unknown
def empty_list[T]() -> list[T]:
return []
def bounded_list[T: list[int]](value: T) -> T:
return value
reveal_type(bounded_list(empty_list())) # revealed: list[Unknown]
The type variable remains unsolved when the upper-bound context passes through another generic call:
def identity[T](value: T) -> T:
return value
reveal_type(bounded_list(identity(empty_list()))) # revealed: list[Unknown]
If an explicit default is provided, it is instead used as the fallback value:
def empty_with_default[T = bool]() -> T:
raise NotImplementedError
reveal_type(bounded(empty_with_default())) # revealed: bool
Constraints inferred against validity bounds are treated as inference evidence during fixpoint iteration:
def index_of[T](items: list[T], item: T) -> int:
return items.index(item)
def _(rows: list[list[int]]):
index_of(rows, reveal_type(list())) # revealed: list[int]
bounded(index_of(rows, reveal_type(list()))) # revealed: list[int]
Upper-bound context with constrained type variables
The solution to a constrained type variable is chosen to satisfy outer validity constraints:
def make[T: (int, str)]() -> T:
raise NotImplementedError
def number[U: int](value: U) -> U:
return value
reveal_type(number(make())) # revealed: int
A default is only used when the type variable remains unsolved:
def make_with_default[T: (int, str) = str]() -> T:
raise NotImplementedError
reveal_type(make_with_default()) # revealed: str
reveal_type(number(make_with_default())) # revealed: int
Generic constructors
The same applies to constructors of generic classes:
from typing import Any
class X[T]:
def __init__(self, value: T):
self.value = value
x1: X[int] = X(1)
reveal_type(x1) # revealed: X[int]
x2: X[int | None] = X(1)
reveal_type(x2) # revealed: X[int | None]
x3: X[int | None] | None = X(1)
reveal_type(x3) # revealed: X[int | None]
def _[T](x1: X[T]):
x2: X[T | int] = X(x1.value)
reveal_type(x2) # revealed: X[T@_ | int]
x4: X[Any] = X(1)
reveal_type(x4) # revealed: X[Any]
def _(flag: bool):
x5: X[int | None] = X(1) if flag else X(2)
reveal_type(x5) # revealed: X[int | None]
from dataclasses import dataclass
@dataclass
class Y[T]:
value: T
y1 = Y(value=1)
reveal_type(y1) # revealed: Y[int]
y2: Y[Any] = Y(value=1)
reveal_type(y2) # revealed: Y[Any]
class Z[T]:
value: T
def __new__(cls, value: T):
return super().__new__(cls)
z1 = Z(1)
reveal_type(z1) # revealed: Z[int]
z2: Z[Any] = Z(1)
reveal_type(z2) # revealed: Z[Any]
The return type should preserve the independent key and value types of a generic dict constructor:
from collections.abc import Iterable, Mapping
def dict_with_numeric_promotion(
keys: Iterable[float],
values: Iterable[int],
) -> Mapping[float, int]:
return dict(zip(keys, values))
from collections.abc import Callable, Hashable
from typing import Any
# The `dict(...)` variant is not technically allowed by the typeshed overloads, which require
# string keys for keyword arguments. We special-case it to match the literal form.
x1: dict[Hashable, Callable[..., object]] = {"x": lambda: 1}
x2: dict[Hashable, Callable[..., object]] = dict(x=lambda: 1)
Preserving literal element types in a generic call
max(..., key=len) returns one of its input tuples. When the result is annotated as Colors, ty
preserves the literal element types while inferring the list passed to max.
from typing import Literal
Colors = tuple[Literal["red", "blue"], ...]
left = ("red",)
right = ("blue", "red")
named: Colors = max([left, right], key=len) # ok
extended: Colors = max([(*left, "blue"), (*right, "red")], key=len) # ok
# error: [invalid-assignment]
invalid: Colors = max([(*left, "blue"), (*right, "green")], key=len)
Covariant constructors with outer return contexts
A bounded, defaulted, covariant constructor should use its outer return context instead of falling back to its declared default.
from __future__ import annotations
from typing import Generic
from typing_extensions import Self, TypeVar
class Client:
def no_argument(self) -> EmptyBox[Self]:
# revealed: EmptyBox[Self@no_argument]
return reveal_type(EmptyBox())
T = TypeVar("T", bound=Client, default=Client, covariant=True)
class EmptyBox(Generic[T]):
def __init__(self) -> None:
pass
Dataclass constructors with outer return contexts
A covariant dataclass argument referring to outer Self should not specialize to its declared
default.
from __future__ import annotations
from dataclasses import dataclass
from typing import Generic
from typing_extensions import Self, TypeVar
class PartialUser:
def equipped(self, present: bool) -> Equipped[Self]:
return Equipped(
first=Item(self) if present else None,
)
class User(PartialUser):
pass
UserT = TypeVar("UserT", bound=PartialUser, default=User, covariant=True)
class Item(Generic[UserT]):
def __init__(self, owner: UserT) -> None:
self.owner = owner
@dataclass
class Equipped(Generic[UserT]):
first: Item[UserT] | None
Generic dictionary factories retain contextual outer key types
A zero-argument dictionary factory uses the expected outer key type instead of introducing a
spurious dict[str, T] alternative.
from collections import defaultdict
from collections.abc import Hashable, Mapping
from dataclasses import field
class SharedMemory[K, T]:
value: dict[K, T] = field(default_factory=dict)
def nested_defaultdict[K: Hashable, K2: Hashable, T](
data: Mapping[K, Mapping[K2, T]],
) -> None:
value: defaultdict[K2, dict[K, T]] = defaultdict(dict)
Callback diagnostics retain contextual outer type variables
A constrained outer return type remains visible in an invalid callback diagnostic. The callback
itself is still invalid, but replacing its expected result with Unknown would lose useful
information.
from collections.abc import Callable
from typing import Generic, TypeVar
C = TypeVar("C", str, bytes, covariant=True)
Selector = TypeVar("Selector", bound=Callable[[int], C]) # error: [invalid-type-variable-bound]
class CallbackView(Generic[C]):
def __init__(self, callback: Callable[[int], C]) -> None:
self.callback = callback
class CallbackInterface(Generic[C]):
def __init__(self, callback: Selector) -> None:
self.callback = callback
def view(self) -> CallbackView[C]:
# error: [invalid-argument-type] "Expected `(int, /) -> C@CallbackInterface`, found `Selector@__init__`"
return CallbackView(self.callback)
Callable factories retain contextual outer element types
Narrowing a union to a callable preserves its outer iterable element type. The callable factory
argument remains invalid, but its expected result uses the outer CT instead of Unknown. After
narrowing the other branch to a sequence, its constructor accepts the same outer element type.
from collections.abc import Callable, Iterable, Iterator, Sequence
from typing import Generic, TypeVar
RT = TypeVar("RT")
CT = TypeVar("CT")
class FactoryView(Iterable[RT], Generic[RT]):
def __init__(self, factory: Callable[[], Iterable[RT]]) -> None:
self.factory = factory
def __iter__(self) -> Iterator[RT]:
return iter(self.factory())
class SequenceView(Iterable[RT], Generic[RT]):
def __init__(self, sequence: Sequence[RT]) -> None:
self.sequence = sequence
def __iter__(self) -> Iterator[RT]:
return iter(self.sequence)
def build_iter_view(matches: Iterable[CT] | Callable[[], Iterable[CT]]) -> Iterable[CT]:
if callable(matches):
# error: [invalid-argument-type] "Expected `() -> Iterable[CT@build_iter_view]`"
return FactoryView(matches)
if not isinstance(matches, Sequence):
matches = list(matches)
return SequenceView(matches)
Generic call argument inference
A function's arguments are also inferred using the type context:
from typing import Callable, TypedDict
class TD(TypedDict):
x: int
def first[T](x: list[T]) -> T:
return x[0]
type ObjectCallback = Callable[[object], None]
type IntCallback = Callable[[int], None]
def make_callback[T](callback: Callable[[T], None]) -> Callable[[T], None]:
return callback
def consume(value: int) -> None:
pass
x1: TD = first([{"x": 0}, {"x": 1}])
reveal_type(x1) # revealed: TD
x2: TD | None = first([{"x": 0}, {"x": 1}])
reveal_type(x2) # revealed: TD
# TODO: We could provide `TypedDict` key diagnostics here.
# error: [invalid-assignment] "Object of type `TD | dict[str, int]` is not assignable to `TD`"
x3: TD = first([{"y": 0}, {"x": 1}])
# TODO: We could provide `TypedDict` key diagnostics here.
# error: [invalid-assignment] "Object of type `TD | None | dict[str, int]` is not assignable to `TD | None`"
x4: TD | None = first([{"y": 0}, {"x": 1}])
# `ObjectCallback` is redundant in this union, so expanding the aliases collapses the narrowing
# target to `IntCallback`.
x5: ObjectCallback | IntCallback = make_callback(lambda value: consume(value.bit_length()))
But not in a way that leads to assignability errors:
from typing import Any, Sequence, TypedDict
class TD2(TypedDict):
x: str
def _(dt: dict[str, Any], key: str):
x1: TD = dt.get(key, {})
reveal_type(x1) # revealed: TD
x2: TD = dt.get(key, {"x": 0})
reveal_type(x2) # revealed: TD
x3: TD | None = dt.get(key, {})
reveal_type(x3) # revealed: TD | None
x4: TD | None = dt.get(key, {"x": 0})
reveal_type(x4) # revealed: TD | None
x5: TD2 = dt.get(key, {})
reveal_type(x5) # revealed: TD2
x6: TD2 = dt.get(key, {"x": 0})
reveal_type(x6) # revealed: TD2
x7: TD2 | None = dt.get(key, {})
reveal_type(x7) # revealed: TD2 | None
x8: TD2 | None = dt.get(key, {"x": 0})
reveal_type(x8) # revealed: TD2 | None
def as_sequence[T](x: T, y: list[T], z: list[T]) -> Sequence[T]:
return [x]
def _(x: int, z: list[int]):
x1: Sequence[int] = as_sequence(x, [x], z)
# TODO: A covariant type context should not cause us to unnecessarily widen call arguments.
x2: Sequence[int | str] = as_sequence(x, [x], z) # error: [invalid-argument-type]
Partially specialized type context is not ignored:
from typing import TypeVar
U = TypeVar("U", default=Any)
class X: ...
def lst[T](x: T) -> list[T]:
return [x]
def two_lists[T](x: list[T | int], y: list[T | str]) -> T:
raise NotImplementedError
def two_lists_default(x: list[U | int], y: list[U | str]) -> U:
raise NotImplementedError
def dct[K, V](k: K, v: V) -> dict[K, V]:
return {k: v}
def two_dicts[T](x: dict[T | int, Any], y: dict[T | str, Any]) -> T:
raise NotImplementedError
def two_dicts_default(x: dict[U | int, Any], y: dict[U | str, Any]) -> U:
raise NotImplementedError
def _():
# revealed: list[X | int]
# revealed: list[X | str]
x1 = two_lists(reveal_type(lst(X())), reveal_type(lst(X())))
reveal_type(x1) # revealed: X
# revealed: list[X | int]
# revealed: list[X | str]
x2 = two_lists(reveal_type([X()]), reveal_type([X()]))
reveal_type(x2) # revealed: X
# revealed: list[X | int]
# revealed: list[X | str]
x3 = two_lists_default(reveal_type(lst(X())), reveal_type(lst(X())))
reveal_type(x3) # revealed: X
# revealed: list[X | int]
# revealed: list[X | str]
x4 = two_lists_default(reveal_type([X()]), reveal_type([X()]))
reveal_type(x4) # revealed: X
# revealed: dict[X | int, Any]
# revealed: dict[X | str, Any]
x5 = two_dicts(reveal_type(dct(X(), X())), reveal_type(dct(X(), X())))
reveal_type(x5) # revealed: X
# revealed: dict[X | int, Any]
# revealed: dict[X | str, Any]
x6 = two_dicts(reveal_type({X(): X()}), reveal_type({X(): X()}))
reveal_type(x6) # revealed: X
# revealed: dict[X | int, Any]
# revealed: dict[X | str, Any]
x7 = two_dicts_default(reveal_type(dct(X(), X())), reveal_type(dct(X(), X())))
reveal_type(x7) # revealed: X
# revealed: dict[X | int, Any]
# revealed: dict[X | str, Any]
x8 = two_dicts_default(reveal_type({X(): X()}), reveal_type({X(): X()}))
reveal_type(x8) # revealed: X
Declared type preference
We prefer the declared solution of a given type variable if it is mutually assignable with the inferred solution.
from typing import Any, reveal_type
def identity[T](value: T) -> T:
return value
def _(dynamic: Any, number: int):
reveal_type(identity(number)) # revealed: int
reveal_type(identity(dynamic)) # revealed: Any
x1: Any = reveal_type(identity(number)) # revealed: Any
reveal_type(x1) # revealed: Any
x2: int = reveal_type(identity(dynamic)) # revealed: int
reveal_type(x2) # revealed: int
Otherwise, the inferred solution is preferred, if it is compatible with the declared constraints:
def _(number: int):
x1: object = reveal_type(identity(number)) # revealed: int
reveal_type(x1) # revealed: int
The same declared type heuristic applies when inferring the specialization of a generic class:
class UnusedTypeParameter[T]:
pass
def unused_type_parameter[T](x: T) -> UnusedTypeParameter[T]:
return UnusedTypeParameter()
def _(dynamic: Any):
# revealed: UnusedTypeParameter[Literal[1]]
reveal_type(unused_type_parameter(1))
# revealed: UnusedTypeParameter[Literal[1]]
x1: UnusedTypeParameter[int | None] = reveal_type(unused_type_parameter(1))
# revealed: UnusedTypeParameter[Any]
x2: UnusedTypeParameter[Any] = reveal_type(unused_type_parameter(1))
# revealed: UnusedTypeParameter[int]
x3: UnusedTypeParameter[int] = reveal_type(unused_type_parameter(dynamic))
class Covariant[T]:
def pop(self) -> T:
raise NotImplementedError
def covariant[T](x: T) -> Covariant[T]:
return Covariant()
def _(dynamic: Any):
# revealed: Covariant[Literal[1]]
reveal_type(covariant(1))
# revealed: Covariant[Literal[1]]
x1: Covariant[int | None] = reveal_type(covariant(1))
# revealed: Covariant[Any]
x2: Covariant[Any] = reveal_type(covariant(1))
# revealed: Covariant[int]
x3: Covariant[int] = reveal_type(covariant(dynamic))
class Contravariant[T]:
def push(self, value: T) -> None:
pass
def contravariant[T](x: T) -> Contravariant[T]:
return Contravariant()
def _(dynamic: Any):
# revealed: Contravariant[int]
reveal_type(contravariant(1))
# revealed: Contravariant[int | None]
x1: Contravariant[int | None] = reveal_type(contravariant(1))
# revealed: Contravariant[Any]
x2: Contravariant[Any] = reveal_type(contravariant(1))
# revealed: Contravariant[int]
x3: Contravariant[int] = reveal_type(contravariant(dynamic))
class Invariant[T]:
x: T
def invariant[T](x: T) -> Invariant[T]:
return Invariant()
def _(dynamic: Any):
# revealed: Invariant[int]
reveal_type(invariant(1))
# revealed: Invariant[int | None]
x1: Invariant[int | None] = reveal_type(invariant(1))
# revealed: Invariant[Any]
x2: Invariant[Any] = reveal_type(invariant(1))
# revealed: Invariant[int]
x3: Invariant[int] = reveal_type(invariant(dynamic))
Note that the heuristic applies independently to each type variable:
from collections.abc import Sequence
def pair[T, U](first: T, second: U) -> tuple[list[T], list[U]]:
return [first], [second]
def _(first: int, second: str):
# revealed: tuple[list[Any], list[str]]
result: tuple[Sequence[Any], Sequence[object]] = reveal_type(pair(first, second))
This behavior also applies to invariant collection types:
from typing import Any
def f[T](x: T) -> list[T]:
return [x]
def f2[T](x: T) -> list[T] | None:
return [x]
def f3[T](x: T) -> list[T] | dict[T, T]:
return [x]
# revealed: list[int]
x1 = reveal_type(f(1))
# revealed: list[Any]
x2: list[Any] = reveal_type(f(1))
# revealed: list[Any]
x3: list[Any] = reveal_type([1])
# revealed: list[Any]
x4: list[Any] | None = reveal_type(f(1))
# revealed: list[Any]
x5: list[Any] | None = reveal_type([1])
# revealed: list[Any] | None
x6: list[Any] | None = reveal_type(f2(1))
# revealed: list[Any] | dict[Any, Any]
x7: list[Any] | dict[Any, Any] = reveal_type(f3(1))
def _(dynamic: Any):
# revealed: list[int]
x1: list[int] = reveal_type(f(dynamic))
# revealed: list[int]
x2: list[int] | None = reveal_type(f(dynamic))
# revealed: list[int] | None
x3: list[int] | None = reveal_type(f2(dynamic))
# revealed: list[int] | dict[int, int]
x4: list[int] | dict[int, int] = reveal_type(f3(dynamic))
As well as constructors of generic classes:
class X[T]:
def __init__(self: "X[None]"): ...
def pop(self) -> T:
raise NotImplementedError
# revealed: X[None]
x1: X[None] = reveal_type(X())
# revealed: X[None]
x2: X[int | None] = reveal_type(X())
# revealed: X[Any]
x3: X[Any] = reveal_type(X())
And Callable parameter types, which are in contravariant position:
from typing import Callable
type AnyToBool = Callable[[Any], bool]
def wrap[**P, T](f: Callable[P, T]) -> Callable[P, T]:
return f
def make_callable[T](x: T) -> Callable[[T], bool]:
raise NotImplementedError
def maybe_make_callable[T](x: T) -> Callable[[T], bool] | None:
raise NotImplementedError
# revealed: (Any, /) -> bool
x1: Callable[[Any], bool] = reveal_type(make_callable(0))
# revealed: (Any, /) -> bool
x2: AnyToBool = reveal_type(make_callable(0))
# revealed: (list[Any], /) -> bool
x3: Callable[[list[Any]], bool] = reveal_type(make_callable([0]))
# revealed: (Any, /) -> bool
x4: Callable[[Any], bool] = reveal_type(wrap(make_callable(0)))
# revealed: ((Any, /) -> bool) | None
x5: Callable[[Any], bool] | None = reveal_type(maybe_make_callable(0))
def _(value: Any):
# revealed: (int, /) -> bool
x1: Callable[[int], bool] = reveal_type(make_callable(value))
# revealed: (int, /) -> bool
x2: Callable[[int], bool] = reveal_type(wrap(make_callable(value)))
# revealed: ((int, /) -> bool) | None
x3: Callable[[int], bool] | None = reveal_type(maybe_make_callable(value))
If the inferred solution does not satisfy the declared constraints, a narrower or wider solution may be chosen:
def takes_callable[T](callback: Callable[[T], None]) -> Covariant[T]:
raise NotImplementedError
def accepts_object(_: object) -> None: ...
# revealed: Covariant[int]
x1: Covariant[int] = reveal_type(takes_callable(accepts_object))
def _(a: int | None):
# revealed: (int | None | str, /) -> bool
x1: Callable[[str], bool] = reveal_type(make_callable(a))
Declared type preference sees through subtyping
The same declared type heuristic applies across subtyping relationships. This behavior applies to collection literals:
import builtins
from collections import defaultdict
from collections.abc import Mapping
from typing import Any, Callable, Iterable, Literal, MutableSequence, overload, Sequence
# TODO: This should be `list[Any]`.
# revealed: list[int]
x1: Sequence[Any] = reveal_type([1, 2, 3])
# revealed: list[Any]
x2: MutableSequence[Any] = reveal_type([1, 2, 3])
# TODO: This should be `list[Any]`.
# revealed: list[int]
x3: Iterable[Any] = reveal_type([1, 2, 3])
# TODO: This should be `list[list[Any]]`.
# revealed: list[list[int]]
x4: Iterable[Iterable[Any]] = reveal_type([[1, 2, 3]])
# revealed: list[Iterable[Any]]
x5: list[Iterable[Any]] = reveal_type([[1, 2, 3]])
# revealed: list[list[Any]]
x6: Iterable[list[Any]] = reveal_type([[1, 2, 3]])
# TODO: This should be `list[Any]`.
# revealed: list[int]
x7: Sequence[Any] = reveal_type([i for i in [1, 2, 3]])
# revealed: list[Any]
x8: MutableSequence[Any] = reveal_type([i for i in [1, 2, 3]])
# TODO: This should be `list[Any]`.
# revealed: list[int]
x9: Iterable[Any] = reveal_type([i for i in [1, 2, 3]])
# TODO: This should be `list[list[Any]]`.
# revealed: list[list[int]]
x10: Iterable[Iterable[Any]] = reveal_type([[i] for i in [1, 2, 3]])
# revealed: list[Iterable[Any]]
x11: list[Iterable[Any]] = reveal_type([[i] for i in [1, 2, 3]])
# revealed: list[list[Any]]
x12: Iterable[list[Any]] = reveal_type([[i] for i in [1, 2, 3]])
def _(dynamic: Any):
# TODO: This should be `list[int]`.
# revealed: list[Any]
x1: Sequence[int] = reveal_type([dynamic])
# revealed: list[int]
x2: MutableSequence[int] = reveal_type([dynamic])
# TODO: This should be `list[int]`.
# revealed: list[Any]
x3: Iterable[int] = reveal_type([dynamic])
# TODO: This should be `list[list[int]]`.
# revealed: list[list[Any]]
x4: Iterable[Iterable[int]] = reveal_type([[dynamic]])
# revealed: list[Iterable[int]]
x5: list[Iterable[int]] = reveal_type([[dynamic]])
# revealed: list[list[int]]
x6: Iterable[list[int]] = reveal_type([[dynamic]])
As well as generic calls, and constructors of generic classes:
class X[T]:
value: T
def __init__(self, value: T): ...
class A[T](X[T]): ...
def a[T](value: T) -> A[T]:
return A(value)
# revealed: A[object]
x1: A[object] = reveal_type(A(1))
# revealed: A[object]
x2: X[object] = reveal_type(A(1))
# revealed: A[object]
x3: X[object] | None = reveal_type(A(1))
# revealed: A[object]
x4: X[object] | None = reveal_type(a(1))
def f[T](x: T) -> list[list[T]]:
return [[x]]
# revealed: list[list[Any]]
x5: Sequence[Sequence[Any]] = reveal_type(f(1))
# revealed: list[list[Any]]
x6: Sequence[list[Any]] = reveal_type(f(1))
# revealed: defaultdict[int, dict[str, int]]
x7: dict[int, dict[str, int]] = reveal_type(defaultdict(dict))
def _(dynamic: Any):
# revealed: A[object]
x1: A[object] = reveal_type(A(dynamic))
# revealed: A[object]
x2: X[object] = reveal_type(A(dynamic))
# revealed: A[object]
x3: X[object] | None = reveal_type(A(dynamic))
# revealed: A[object]
x4: X[object] | None = reveal_type(a(dynamic))
# revealed: list[list[object]]
x5: Sequence[Sequence[object]] = reveal_type(f(dynamic))
# revealed: list[list[object]]
x6: Sequence[list[object]] = reveal_type(f(dynamic))
Complex subtyping relationships are solved correctly:
from typing import Hashable
def variadic(*args: Any, **kwargs: Any) -> Any: ...
# revealed: dict[Hashable, list[(...) -> Any]]
x1: Mapping[Hashable, list[Callable[..., Any]]] = reveal_type({"x": [variadic]})
# revealed: dict[Hashable, list[(...) -> Any]]
x2: Mapping[Hashable, list[Callable[..., Any]]] = reveal_type(dict(x=[variadic]))
# revealed: dict[str, Literal["+", "-"]]
x3: Mapping[str, Literal["+", "-"]] = reveal_type({
"plus": "+",
"minus": "-",
})
class DataFrame: ...
type Aggregate = Callable[[DataFrame], object] | str
type AggregateSpec = Aggregate | list[Aggregate]
def mean(data: DataFrame) -> float:
return 0.0
x4: Mapping[Hashable, AggregateSpec] = {"col1": ["sum", mean], "col2": mean}
Recursive aliases remain stable in invariant collection contexts
An invariant collection context can infer the same recursive type as both bounds. Because recursive
inference introduces Divergent, intersecting those bounds should not discard any element of the
union.
from collections.abc import MutableMapping, MutableSequence
from typing import TypeAlias, TypedDict
class Leaf(TypedDict, total=False):
path: str
RecursiveValue: TypeAlias = int | Leaf | MutableSequence["RecursiveValue | None"] | MutableMapping[str, "RecursiveValue | None"]
RecursiveMapping: TypeAlias = MutableMapping[str, RecursiveValue | None]
recursive: RecursiveMapping = {}
Implicit generic class specialization
Callable type context is also used to inform the implicit specialization of a generic class:
import builtins
from collections import defaultdict
from collections.abc import Mapping
from typing import Any, Callable, overload
x1: Mapping[str, list[str]] = reveal_type(defaultdict(list)) # revealed: defaultdict[str, list[str]]
x1["key"].append(1) # error: [invalid-argument-type]
x2: Callable[[], list[str]] = reveal_type(list) # revealed: <class 'list[str]'>
reveal_type(x2()) # revealed: list[str]
x3: Callable[[], list[str]] | None = reveal_type(list) # revealed: <class 'list[str]'>
x4: Callable[[], list[str]] = reveal_type(builtins.list) # revealed: <class 'list[str]'>
reveal_type(x4()) # revealed: list[str]
type ListFactory = Callable[[], list[str]]
x5: ListFactory = reveal_type(list) # revealed: <class 'list[str]'>
reveal_type(x5()) # revealed: list[str]
x6: Callable[..., Any] = reveal_type(list) # revealed: <class 'list'>
x7: Callable[[Any], Any] = reveal_type(list) # revealed: <class 'list'>
class Wrapped[T]:
value: T
def __new__(cls, value: T) -> "Wrapped[tuple[T]]":
raise NotImplementedError
x8: Callable[[str], Wrapped[tuple[str]]] = reveal_type(Wrapped) # revealed: <class 'Wrapped[str]'>
reveal_type(x8("x")) # revealed: Wrapped[tuple[str]]
class M[T]:
value: T
def __new__[S](cls, value: S) -> "M[tuple[S]]":
raise NotImplementedError
x9: Callable[[str], M[tuple[str]]] = reveal_type(M) # revealed: <class 'M'>
reveal_type(x9("x")) # revealed: M[tuple[str]]
class MultiPath[T]:
value: T
@overload
def __init__(self, value: T) -> None: ...
@overload
def __init__(self, value: list[T]) -> None: ...
def __init__(self, value: object) -> None: ...
# fmt: off
x10: Callable[[list[int]], MultiPath[int] | MultiPath[list[int]]] = reveal_type(MultiPath) # revealed: <class 'MultiPath'>
# fmt: on
Type context and explicitly annotated self
When self is explicitly annotated with a concrete specialization, ty uses it when inferring the
type of unspecialized constructor calls:
class Reader[T]:
def __init__(self: "Reader[int]") -> None: ...
def read(self) -> T:
raise NotImplementedError
reveal_type(Reader()) # revealed: Reader[int]
When trying to specialize explicitly, the call will fail:
Reader[str]() # error: [invalid-argument-type]
Reader[int] is also inferred if it is assignable to the assignment context (Reader is covariant
in T):
# revealed: Reader[int]
reader: Reader[int] = reveal_type(Reader())
# revealed: Reader[int]
reader: Reader[int | str] = reveal_type(Reader())
The assignment context can also narrow the inferred type argument from int to bool. Since
Reader is covariant, Reader[bool] is a valid argument for self: Reader[int].
# TODO: this should not be an error, and Reader[bool] should be inferred (see https://github.com/astral-sh/ty/issues/4993)
# revealed: Reader[int]
narrow_reader: Reader[bool] = reveal_type(Reader()) # error: [invalid-assignment]
The same is also true if the receiver is annotated with a union:
class ReaderUnion[T]:
def __init__(self: "ReaderUnion[int | str]") -> None: ...
# revealed: ReaderUnion[int | str]
reader: ReaderUnion[int | str] = reveal_type(ReaderUnion())
# revealed: ReaderUnion[int | str]
reader: ReaderUnion[int | str | None] = reveal_type(ReaderUnion())
# revealed: ReaderUnion[int]
narrow_union: ReaderUnion[int] = reveal_type(ReaderUnion())
Generic class specialization through recursive callable aliases
A recursive callable context specializes a generic class used as a factory. The returned container keeps the recursive element type.
[environment]
python-version = "3.12"
from collections.abc import Callable
Factory = Callable[[], list["Factory"]]
type ExplicitFactory = Callable[[], list[ExplicitFactory]]
factory: Factory = list
explicit_factory: ExplicitFactory = list
reveal_type(factory()) # revealed: list[Factory]
reveal_type(explicit_factory()) # revealed: list[ExplicitFactory]
Generic call narrowing
When a generic call is inferred against a union declared type, the call expression is inferred independently against each member of the union, producing the union of all valid specializations of the call.
def lst[T](x: T) -> list[T]:
return [x]
x1: list[int | str] | list[str | None] = lst(1)
reveal_type(x1) # revealed: list[int | str]
x2: list[int | str] | list[int | None] = lst(1)
reveal_type(x2) # revealed: list[int | str] | list[int | None]
The same narrowing applies to built-in collection constructors.
from collections.abc import Mapping, Sequence
from typing import Literal
x1: list[int | str] | list[int | None] = list((1, 2, 3))
reveal_type(x1) # revealed: list[int | str] | list[int | None]
x2: set[int | str] | set[int | None] = set((1,))
reveal_type(x2) # revealed: set[int | str] | set[int | None]
x3: dict[str, int | str] | dict[str, int | None] = dict([("key", 1)])
reveal_type(x3) # revealed: dict[str, int | str] | dict[str, int | None]
x4: list[int] | list[int | None] | list[str | None] = list(("1", "2"))
reveal_type(x4) # revealed: list[str | None]
x5: Sequence[int | str] | Sequence[int | None] = list((1, 2, 3))
reveal_type(x5) # revealed: list[int]
x6: dict[str, list[int | None]] | dict[str, list[str | None]] = dict([("a", ["b"])])
reveal_type(x6) # revealed: dict[str, list[str | None]]
x7: Mapping[str, list[int | None]] | Mapping[str, list[str | None]] = dict([("a", ["b"])])
reveal_type(x7) # revealed: dict[str, list[str | None]]
def _(x8: list[dict[str, list[int] | int] | dict[str, list[int]]]):
x8.append(reveal_type(dict([("b", 1)]))) # revealed: dict[str, list[int] | int]
As well as to a union nested behind a type alias.
type EitherList = list[int | str] | list[int | None]
x1: EitherList = list((None, None))
reveal_type(x1) # revealed: list[None | int]
x2: EitherList = list(("1", "2", "3"))
reveal_type(x2) # revealed: list[str | int]
type SelfOp[T] = Mapping[Literal["$eq", "$ne"], T]
type ListOp[T] = Mapping[Literal["$in", "$nin"], Sequence[T]]
type Ops[T] = SelfOp[T] | ListOp[T]
type NestedOp[T] = T | Ops[T]
x3: NestedOp[str] = dict([("$in", ["a", "b"])])
reveal_type(x3) # revealed: dict[Literal["$in", "$nin"], Sequence[str]]
The narrowed union element is used as type context when inferring the call.
from typing import TypedDict
class TD(TypedDict):
x: int
type TargetWithTD = Any | list[TD] | dict[str, TD] | Callable[[TD], None] | None
def _(target: TargetWithTD):
target = identity([{"x": 1}])
reveal_type(target) # revealed: list[TD]
def _(target: TargetWithTD):
target = identity({"x": {"x": 1}})
reveal_type(target) # revealed: dict[str, TD]
def _(target: TargetWithTD):
def make_callable[T](x: T) -> Callable[[T], None]:
raise NotImplementedError
target = identity(make_callable({"x": 1}))
reveal_type(target) # revealed: (TD, /) -> None
The declared type of a collection literal is also narrowed to each matching union member, maintaining consistency with generic calls.
def _(i: int):
x1: int | None = i
x2: int | None = identity(i)
x3: int | str | None = identity(i)
reveal_type(x1) # revealed: int
reveal_type(x2) # revealed: int
reveal_type(x3) # revealed: int
def _(i: int):
x1: list[int | None] | None = [i]
x2: list[int | None] | None = identity([i])
x3: list[int | None] | int | None = identity([i])
reveal_type(x1) # revealed: list[int | None]
reveal_type(x2) # revealed: list[int | None]
reveal_type(x3) # revealed: list[int | None]
def _(i: int):
x1: list[int | None] | None = [i]
x2: list[int | None] | None = lst(i)
x3: list[int | None] | int | None = lst(i)
reveal_type(x1) # revealed: list[int | None]
reveal_type(x2) # revealed: list[int | None]
reveal_type(x3) # revealed: list[int | None]
def _():
x1: list | None = [] # error: [missing-type-argument]
x2: list | None = identity([]) # error: [missing-type-argument]
x3: list | int | None = identity([]) # error: [missing-type-argument]
reveal_type(x1) # revealed: list[Unknown]
reveal_type(x2) # revealed: list[Unknown]
reveal_type(x3) # revealed: list[Unknown]
The narrowing behavior prevents identity calls from being widened unnecessarily.
from typing import Any, Callable, reveal_type
def identity[T](x: T) -> T:
return x
type Target = Any | list[str] | dict[str, str] | Callable[[str], None] | None
def _(narrow: dict[str, str], target: Target):
target = identity(narrow)
reveal_type(target) # revealed: dict[str, str]
def _(narrow: list[str], target: Target):
target = identity(narrow)
reveal_type(target) # revealed: list[str]
def _(narrow: Callable[[str], None], target: Target):
target = identity(narrow)
reveal_type(target) # revealed: (str, /) -> None
If the call cannot be narrowed to a specific member, it is inferred against the entire union.
def _(wide: list[str] | dict[str, str], target: Target):
target = identity(wide)
reveal_type(target) # revealed: list[str] | dict[str, str]
Nested generic calls similarly avoid widening, even if they produce invariant types.
def head[T](x: list[T]) -> T:
return x[0]
def _(a: int, b: str, c: int | str):
x1: int = head(lst(a))
reveal_type(x1) # revealed: int
x2: int | str = head(lst(a))
reveal_type(x2) # revealed: int
x3: int | None = head(lst(a))
reveal_type(x3) # revealed: int
x4: str = head(lst(b))
reveal_type(x4) # revealed: str
x5: int | str = head(lst(b))
reveal_type(x5) # revealed: str
x6: str | int = head(lst(b))
reveal_type(x6) # revealed: str
x7: str | None = head(lst(b))
reveal_type(x7) # revealed: str
x8: int | str = head(lst(c))
reveal_type(x8) # revealed: int | str
# TODO: Ideally this would reveal `int | str`. This is a known limitation of our
# call inference solver, and would require an extra inference attempt without type
# context, or with type context of subsets of the union, both of which are impractical
# for performance reasons.
x9: int | str | None = head(lst(c))
reveal_type(x9) # revealed: int | str | None
Generic calls are never narrowed to a dynamic type, which can lead to overly narrow or gradual types in the presence of unconstrained or dynamic arguments. Instead, the full declared union is preferred over a dynamic member:
def head_or[T, U](values: list[T], default: U) -> T | U:
return values[0] if values else default
def _(values: list[Any]):
result: str | Any = reveal_type(head_or(list(values), default=0)) # revealed: str | Any | Literal[0]
items: Any | list[int] = reveal_type(list()) # revealed: list[int]
When a generic call is narrowed to a single element of the union, any diagnostics emitted use the types inferred using that element as type context.
from typing import Callable, TypedDict
# revealed: int
x1: list[Callable[[int], object]] | str = lst(lambda value: reveal_type(value))
reveal_type(x1) # revealed: list[(int, /) -> object]
class A(TypedDict):
value: int
x2: list[A] | str = lst(reveal_type({"value": 1})) # revealed: A
reveal_type(x2) # revealed: list[A]
When a call instead produces multiple valid specializations, diagnostics fall back to the types inferred without type context.
# revealed: Unknown
x1: list[Callable[[int], object]] | list[Callable[[str], object]] = lst(lambda value: reveal_type(value))
reveal_type(x1) # revealed: list[(int, /) -> object] | list[(str, /) -> object]
x2: list[A] | list[dict[str, int]] = lst(reveal_type({"value": 1})) # revealed: dict[str, int]
reveal_type(x2) # revealed: list[A] | list[dict[str, int]]
If inferring a generic call against a member of the declared type produces a wider return type, that member is excluded from the result.
def make_list[U = str]() -> list[U] | list[int]:
raise NotImplementedError
def _():
x1 = make_list()
reveal_type(x1) # revealed: list[str] | list[int]
# TODO: Ideally this would return the same result as the unannotated case, but it's
# not clear which result is more desirable.
x2: list[str] | list[int] = make_list()
reveal_type(x2) # revealed: list[int]
If multiple alternatives are inferred for a given type variable during fixpoint iteration, however, they are not later narrowed unnecessarily:
def choose[T](x: T, y: T) -> T:
return x
def _(ints: list[int]):
x1 = choose(make_list(), ints)
reveal_type(x1) # revealed: list[str] | list[int]
x2 = choose(choose(make_list(), ints), ints)
reveal_type(x2) # revealed: list[str] | list[int]
Dynamic types inferred from arguments are also preserved.
def _(values: list[Any]):
x = choose(head_or(list(values), default=None), None)
reveal_type(x) # revealed: Any | None
A nested generic call still participates in narrowing if inferred against an explicit declared type.
def wrap[T, U](a: list[T], b: U) -> tuple[T]:
return (a[0],)
x1: tuple[list[str] | list[int]] = wrap(
[reveal_type(make_list())], # revealed: list[int]
reveal_type(make_list()), # revealed: list[str] | list[int]
)
def wrap_tuple[T, U](pair: tuple[T, U]) -> tuple[T]:
return (pair[0],)
x2: tuple[list[str] | list[int]] = wrap_tuple((
reveal_type(make_list()), # revealed: list[int]
# TODO: This should remain `list[str] | list[int]`.
reveal_type(make_list()), # revealed: list[int]
))
Correlated overload specializations from an expected type
A declared return type can be satisfied by correlated specializations even when merging the type arguments independently would violate the declared constraints:
from typing import Callable, overload
@overload
def callback(value: int) -> str: ...
@overload
def callback(value: str) -> int: ...
def callback(value: int | str) -> int | str:
raise NotImplementedError
def f[A, B](callback: Callable[[A], B]) -> tuple[tuple[list[A], list[B]]]:
raise NotImplementedError
type Choice = tuple[list[int], list[str]] | tuple[list[str], list[int]]
# revealed: tuple[tuple[list[int], list[str]]] | tuple[tuple[list[str], list[int]]]
result: tuple[Choice] = reveal_type(f(callback))
The same applies when the expected tuple type is inferred from a previous assignment:
def initial() -> tuple[Choice]:
return (([1], ["s"]),)
class Fields:
pair = initial()
# revealed: tuple[tuple[list[int], list[str]]] | tuple[tuple[list[str], list[int]]]
Fields.pair = reveal_type(f(callback))
Literal union context for generic calls
Narrowing a small literal union preserves the precise result of a nested generic call, including
when the return type also contains Any:
from typing import Any, Literal, assert_type
def singleton[T](value: T) -> list[T]:
return [value]
def first[T](values: list[T]) -> T:
return values[0]
def first_gradual[T](values: list[T]) -> Any | T:
return values[0]
precise: Literal["a", "b"] = first(singleton("a"))
assert_type(precise, Literal["a"])
gradual: Literal["a", "b"] = reveal_type(first_gradual(singleton("a"))) # revealed: Any | Literal["a"]
A result can contain several literal alternatives without including every member of the declared
union. The surrounding optional type does not add None to this result:
def literal_union(value: Literal["a", "b"]) -> None:
result: Literal["a", "b"] | None = first(singleton(value))
assert_type(result, Literal["a", "b"])
precise: Literal["a", "b"] | None = first(singleton("a"))
assert_type(precise, Literal["a"])
A generic collection alternative still provides context when it follows literal alternatives. The
empty list is inferred as list[str]:
type Values = Literal[0, 1, 2]
def identity[T](value: T) -> T:
return value
collection: Values | list[str] | None = identity([])
assert_type(collection, list[str])
The result also stays precise when the matching literal is the last member of the declared union:
late: Values = first(singleton(2))
assert_type(late, Literal[2])
Large literal unions are not expanded, and calls are instead inferred against the union of all literal values:
type Many = (
Literal[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]
| Literal[16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31]
| Literal[32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47]
| Literal[48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64]
)
wide: Many = first(singleton(64))
assert_type(wide, Many)
mixed: Many | list[int] | list[str] = identity([])
assert_type(mixed, list[int] | list[str])
def _(value: Any):
grouped: Many | None = first([value])
assert_type(grouped, Many | None)
Assignability diagnostics ignore declared type
The type displayed in an invalid assignment diagnostic should account for the type context, e.g., to avoid literal promotion:
from typing import Literal, TypedDict
def f[T](x: T) -> list[T]:
return [x]
# error: [invalid-assignment] "Object of type `list[Literal["hello"] | int]` is not assignable to `list[Literal["hello"] | bool]`"
x1: list[Literal["hello"] | bool] = ["hello", 1]
class A(TypedDict):
bar: int
# error: [invalid-assignment] "Object of type `list[A | int]` is not assignable to `list[A | bool]`"
x2: list[A | bool] = [{"bar": 1}, 1]
However, the declared type should be ignored if the specialization is not solvable:
from typing import Callable
def g[T](x: list[T]) -> T:
return x[0]
def _(a: int | None):
# error: [invalid-assignment] "Object of type `list[int | None]` is not assignable to `list[str]`"
x1: list[str] = f(a)
# error: [invalid-assignment] "Object of type `int | None` is not assignable to `str`"
x2: str = g(f(a))
def make_callable[T](x: T) -> Callable[[T], T]:
raise NotImplementedError
def _(a: int | None):
# error: [invalid-assignment] "Object of type `(int | None, /) -> int | None` is not assignable to `(str, /) -> str`"
x3: Callable[[str], str] = make_callable(a)
Instance attributes
Both meta and class/instance attribute annotations are used as type context:
from typing import Literal, Any
class DataDescriptor:
def __get__(self, instance: object, owner: type | None = None) -> list[Literal[1]]:
return []
def __set__(self, instance: object, value: list[Literal[1]]) -> None:
pass
def _(flag: bool):
class Meta(type):
if flag:
x: DataDescriptor = DataDescriptor()
class C(metaclass=Meta):
x: list[int | None]
def _(c: C):
c.x = reveal_type([1]) # revealed: list[int]
C.x = reveal_type([1]) # revealed: list[Literal[1]]
For union targets, each element of the union is considered as a separate type context:
from typing import Literal
class X:
x: list[int | str]
class Y:
x: list[int | None]
def _(xy: X | Y):
xy.x = reveal_type([1]) # revealed: list[int]
Unannotated lambda parameters do not prevent the inferred attribute type from providing context to the dictionary literals:
class Callbacks:
def __init__(self):
self.values = [{"x": 0}, {"x": lambda x: 0}]
self.identities = [{"x": 0}, {"x": lambda x: x}]
An inferred attribute type does not provide a declared type preference to later assignments:
def identity[T](value: T) -> T:
return value
class Fields:
class_value = None
def __init__(self, value: Any):
self.value = None
self.value = identity(value)
reveal_type(self.value) # revealed: Any
def _(value: Any):
Fields.class_value = reveal_type(identity(value)) # revealed: Any
reveal_type(Fields.class_value) # revealed: Any
The inferred attribute type is, however, used to fill in unsolved type variables:
class Collections:
numbers = [1]
items = iter([1])
def _():
Collections.numbers = reveal_type(list()) # revealed: list[int]
Collections.items = reveal_type(iter(list())) # revealed: Iterator[int]
An annotated instance attribute provides a declared type preference even if the class body conditionally annotated the same field:
def _(flag: bool, value: Any):
class Conditional:
if flag:
field: int
def __init__(self):
self.field: int = 0
obj = Conditional()
obj.field = identity(value)
reveal_type(obj.field) # revealed: int
Overload evaluation
The type context of all matching overloads are considered during argument inference:
from concurrent.futures import Future
from os.path import abspath
from typing import Awaitable, Callable, TypeVar, Union, overload, TypedDict
def int_or_str() -> int | str:
raise NotImplementedError
@overload
def f1(x: list[int | None], y: int) -> int: ...
@overload
def f1(x: list[int | str], y: str) -> str: ...
def f1(x, y) -> int | str:
raise NotImplementedError
x1 = f1(reveal_type([1]), 1) # revealed: list[int | None]
reveal_type(x1) # revealed: int
x2 = f1(reveal_type([1]), int_or_str()) # revealed: list[int]
reveal_type(x2) # revealed: int | str
@overload
def f2[T](x: T, y: int) -> T: ...
@overload
def f2(x: list[int | str], y: str) -> object: ...
def f2(x, y) -> object: ...
x3 = f2(reveal_type([1]), 1) # revealed: list[int]
reveal_type(x3) # revealed: list[int]
class TD(TypedDict):
x: list[int | str]
class TD2(TypedDict):
x: list[int | None]
@overload
def f3(x: TD, y: int) -> int: ...
@overload
def f3(x: TD2, y: str) -> str: ...
def f3(x, y) -> object: ...
x4 = f3(reveal_type({"x": [1]}), "1") # revealed: TD2
reveal_type(x4) # revealed: str
x5 = f3(reveal_type({"x": [1]}), int_or_str()) # revealed: dict[str, list[int]]
reveal_type(x5) # revealed: int | str
@overload
def f4[T](_: list[T]) -> list[T]: ...
@overload
def f4(_: list[str]) -> list[str]: ...
def f4(_: object): ...
x6 = f4(reveal_type([])) # revealed: list[Unknown]
reveal_type(x6) # revealed: list[Unknown]
@overload
def f5(_: list[int | str]) -> int: ...
@overload
def f5(_: set[int | str]) -> str: ...
def f5(_) -> object:
raise NotImplementedError
def list_or_set[T](x: T) -> list[T] | set[T]:
raise NotImplementedError
# TODO: We should reveal `list[int | str] | set[int | str]` here.
x7 = f5(reveal_type(list_or_set(1))) # revealed: list[int] | set[int]
reveal_type(x7) # revealed: int | str
@overload
def f6(_: list[int | None]) -> int: ...
@overload
def f6(_: set[int | str]) -> str: ...
def f6(_) -> object:
raise NotImplementedError
def list_or_set2[T, U](x: T, y: U) -> list[T] | set[U]:
raise NotImplementedError
# TODO: We should not error here.
# error: [no-matching-overload]
x8 = f6(reveal_type(list_or_set2(1, 1))) # revealed: list[int | None] | set[int]
reveal_type(x8) # revealed: Unknown
@overload
def f7(y: list[int | str]) -> list[int | str]: ...
@overload
def f7[T](y: list[T]) -> list[T]: ...
def f7(y: object) -> object:
raise NotImplementedError
x9 = f7(reveal_type(["Sheet1"])) # revealed: list[int | str]
reveal_type(x9) # revealed: list[int | str]
def f8(xs: tuple[str, ...]) -> tuple[str, ...]:
return tuple(map(abspath, xs))
T2 = TypeVar("T2")
def sink(func: Callable[[], Union[Awaitable[T2], T2]], future: Future[T2]) -> None:
raise NotImplementedError
def f9(func: Callable[[], Union[Awaitable[T2], T2]]) -> Future[T2]:
future: Future[T2] = Future()
sink(func, future)
return future
Variadic arguments are inferred using their matching parameter as type context.
@overload
def pair[T: int, U](*args: *tuple[list[T], list[U]]) -> tuple[T, U]: ...
@overload
def pair(first: list[str], second: list[int], /) -> tuple[str, int]: ...
def pair(*args: object) -> object:
raise NotImplementedError
reveal_type(pair([42], ["x"])) # revealed: tuple[int, str]
Class constructor parameters
The parameters of both __init__ and __new__ are used as type context sources for constructor
calls:
def f[T](x: T) -> list[T]:
return [x]
class A:
def __new__(cls, value: list[int | str]):
return super().__new__(cls)
def __init__(self, value: list[int | None]): ...
A(f(1))
# error: [invalid-argument-type] "Argument to constructor `A.__new__` is incorrect: Expected `list[int | str]`, found `list[list[Unknown]]`"
A(f([]))
Conditional expressions
The type context is propagated through both branches of conditional expressions:
def f[T](x: T) -> list[T]:
raise NotImplementedError
def _(flag: bool):
x1 = f(1) if flag else f(2)
reveal_type(x1) # revealed: list[int]
x2: list[int | None] = f(1) if flag else f(2)
reveal_type(x2) # revealed: list[int | None]
Collection literals in boolean and conditional expressions
When a boolean or conditional expression combines a fresh collection literal with another operand, the other operand can provide type context for the literal:
from collections.abc import Mapping
from dataclasses import dataclass
from typing import Literal, TypedDict, reveal_type
type Key = Literal["foo", "bar"]
class Payload(TypedDict):
required: int
def from_or(values: list[str] | None) -> None:
for value in reveal_type(values or []): # revealed: list[str]
reveal_type(value) # revealed: str
def constructor_fallback(values: list[int] | None) -> None:
# TODO: This should reveal `list[int]` based on the peer type context.
reveal_type(values or list()) # revealed: (list[int] & ~AlwaysFalsy) | list[Unknown]
def from_and(values: list[str]) -> None:
reveal_type(values and []) # revealed: list[str]
def chained_or(first: list[int], second: list[str]) -> None:
for value in first or second or []:
reveal_type(value) # revealed: int | str
def from_conditional(values: set[str], allowed: set[str] | None) -> None:
filtered = reveal_type(
sorted(value for value in values if value not in allowed) # revealed: list[str]
if allowed is not None
else []
)
for value in filtered:
reveal_type(value) # revealed: str
def collection_literal_first(values: list[str], flag: bool) -> None:
reveal_type([] if flag else values) # revealed: list[str]
def non_empty_dict_fallback(values: dict[Key, int] | None) -> None:
reveal_type(values or {"foo": 0}) # revealed: dict[Literal["foo", "bar"], int]
def non_empty_set_fallback(values: set[Key] | None) -> None:
reveal_type(values or {"foo"}) # revealed: set[Literal["foo", "bar"]]
class TextContent: ...
class TagContent: ...
def expects_list_content(content: list[TextContent | TagContent]) -> None: ...
def optional_content(content: list[TextContent | TagContent] | None) -> None:
expects_list_content(content or [TextContent()])
def invalid_fallback(content: list[TextContent | TagContent] | None) -> None:
expects_list_content(content or [object()]) # error: [invalid-argument-type]
def preserve_generic[T](value: T) -> T:
return value
def preserve_partially_specialized[T](value: list[T | int]) -> list[T | int]:
return value
def generic_type_context(values: list[int | str] | None) -> None:
reveal_type(preserve_generic(values or [])) # revealed: list[int | str]
reveal_type(preserve_partially_specialized(values or [])) # revealed: list[Unknown | int]
def widened_non_empty_fallback(values: list[int] | None) -> None:
result = values or ["x"]
reveal_type(result) # revealed: (list[int] & ~AlwaysFalsy) | list[int | str]
def incompatible_collection_kind(values: set[str] | None) -> None:
reveal_type(values or [1]) # revealed: (set[str] & ~AlwaysFalsy) | list[int]
def typed_dict_peer_is_only_a_hint(value: Payload | None, flag: bool) -> None:
value or {}
{} if flag else value
value or {"other": 1}
def stored_literal_is_not_fresh(values: dict[Key, int] | None) -> None:
fallback = {"foo": 0}
reveal_type(fallback) # revealed: dict[str, int]
result = values or fallback
reveal_type(result) # revealed: (dict[Key, int] & ~AlwaysFalsy) | dict[str, int]
@dataclass
class SortParams[F]:
field: F
direction: Literal["asc", "desc"] = "desc"
def build_sort_spec[T](
sort_params: SortParams[T] | None,
) -> dict[T, Literal[1, -1]] | None:
if sort_params is None:
return None
return {sort_params.field: 1}
type Path = Literal["name", "age", "created"]
def use_sort(value: Mapping[Path, Literal[1, -1]]) -> None: ...
params: SortParams[Path] | None = None
sort = build_sort_spec(params) or {"name": -1}
use_sort(sort)
An unspecialized collection parameter is not useful type context for a collection literal. The other operand of a conditional or boolean expression can supply it instead:
def f[T](values: list[T]) -> list[T]:
return values
def _(values: list[object], flag: bool):
reveal_type(f(values if flag else [1])) # revealed: list[object]
reveal_type(f([1] if flag else values)) # revealed: list[object]
reveal_type(f(values or [1])) # revealed: list[object]
reveal_type(f(values and [1])) # revealed: list[object]
The same applies to set literals:
def g[T](values: set[T]) -> set[T]:
return values
def _(values: set[object], flag: bool):
reveal_type(g(values if flag else {1})) # revealed: set[object]
reveal_type(g({1} if flag else values)) # revealed: set[object]
reveal_type(g(values or {1})) # revealed: set[object]
As well as generic constructors:
def _(values: dict[str | None, object], flag: bool):
reveal_type(dict(values if flag else {None: None})) # revealed: dict[str | None, object]
reveal_type(dict({None: None} if flag else values)) # revealed: dict[str | None, object]
reveal_type(dict(values or {None: None})) # revealed: dict[str | None, object]
Explicit gradual element types remain preferred over the other operand's specialization:
from typing import Any
def _(values: list[int], flag: bool):
x: list[Any] = values if flag else reveal_type([]) # revealed: list[Any]
reveal_type(x) # revealed: list[Any]
Lambda expressions
If a lambda expression is annotated as a Callable type, the body of the lambda is inferred with
the annotated return type as type context, and the annotated parameter types are respected:
from typing import Callable, TypedDict
class Bar(TypedDict):
bar: int
def id[T](x: T) -> T:
return x
f1 = lambda x: {"bar": 1}
reveal_type(f1) # revealed: (x) -> dict[str, int]
f2: Callable[[int], Bar] = lambda x: {"bar": 1}
reveal_type(f2) # revealed: (x: int) -> Bar
# error: [missing-typed-dict-key] "Missing required key 'bar' in TypedDict `Bar` constructor"
# error: [invalid-assignment] "Object of type `(x: int) -> dict[Unknown, Unknown]` is not assignable to `(int, /) -> Bar`"
f3: Callable[[int], Bar] = lambda x: {}
reveal_type(f3) # revealed: (int, /) -> Bar
f4: Callable[[str], str] = lambda x: reveal_type(x) # revealed: str
reveal_type(f4) # revealed: (x: str) -> str
f5: Callable[[str], str] = id(lambda x: reveal_type(x)) # revealed: str
reveal_type(f5) # revealed: (x: str) -> str
# The same return-context propagation works for generic calls whose context solves a ParamSpec.
def id_callable[**P, R](x: Callable[P, R]) -> Callable[P, R]:
return x
f5_paramspec: Callable[[int], int] = id_callable(lambda x: reveal_type(x)) # revealed: int
reveal_type(f5_paramspec) # revealed: (x: int) -> int
# TODO: This should not error once we support `Unpack`.
# error: [invalid-assignment]
f6: Callable[[*tuple[int, ...]], None] = lambda x, y, z: None
reveal_type(f6) # revealed: (*tuple[int, ...]) -> None
f7: Callable[[int, str], None] = lambda *args: None
reveal_type(f7) # revealed: (*args) -> None
# N.B. `Callable` annotations only support positional parameters.
# error: [invalid-assignment]
f8: Callable[[int], None] = lambda *, x=1: None
reveal_type(f8) # revealed: (int, /) -> None
# An optional keyword-only parameter does not prevent `*args` from accepting the positional
# suffix in a `Callable` annotation.
f9: Callable[[*tuple[int, ...], int], None] = lambda *args, x=1: None
reveal_type(f9) # revealed: (*args, x=1) -> None
f10: Callable[[str, int, str], tuple[str, int, str]] = lambda x, y, z: reveal_type((x, y, z)) # revealed: tuple[str, int, str]
reveal_type(f10) # revealed: (x: str, y: int, z: str) -> tuple[str, int, str]
# TODO: This should reveal `tuple[int, ...]`.
f11: Callable[[*tuple[int, ...]], tuple[int, ...]] = lambda *args: reveal_type(args) # revealed: tuple[Unknown, ...]
reveal_type(f11) # revealed: (*args) -> tuple[int, ...]
def _(x: list[int]):
f12 = list(map(lambda y: reveal_type(y) + 1, x)) # revealed: int
reveal_type(f12) # revealed: list[int]
def _() -> Callable[[int], int]:
return id(lambda x: reveal_type(x)) # revealed: int
def _():
def takes_callable(_: Callable[[int], int]): ...
takes_callable(lambda x: reveal_type(x)) # revealed: int
takes_callable(id(id(lambda x: reveal_type(x)))) # revealed: int
def _(x: bool):
signatures = {
"upper": str.upper,
"lower": str.lower,
"title": str.title,
}
# revealed: (x) -> Unknown
f = signatures.get("", reveal_type(lambda x: x))
We do not currently account for type annotations present later in the scope:
f12 = lambda: [1]
# TODO: This should not error.
_: list[int | str] = f12() # error: [invalid-assignment]
reveal_type(f12) # revealed: () -> list[int]
A partially unspecialized Callable annotation still provides useful type context for a lambda
expression:
def f[T](callback: Callable[[T], None]) -> None: ...
f(reveal_type(lambda x: None)) # revealed: (x) -> None
def consume[T](callback: Callable[[T, int], int]) -> None:
pass
consume(id(lambda x, y: reveal_type(y))) # revealed: int
consume(id(lambda x, y: y.upper())) # error: [missing-attribute]
Lambda contextual inference through type aliases
A lambda parameter is inferred from a callable behind a type alias, including aliases that resolve to unions and aliases used as elements of another union:
from typing import Callable
from typing_extensions import TypeAliasType
type IntCallback = Callable[[int], None]
type IntCallbackOrInt = Callable[[int], None] | int
IntCallbackOrIntAliasType = TypeAliasType("IntCallbackOrIntAliasType", Callable[[int], None] | int)
IntCallbackAliasType = TypeAliasType("IntCallbackAliasType", Callable[[int], None])
def consume(value: int) -> None:
pass
x1: Callable[[int], None] | str = lambda value: consume(reveal_type(value)) # revealed: int
x2: IntCallbackOrInt | str = lambda value: consume(reveal_type(value)) # revealed: int
x3: IntCallbackOrIntAliasType | str = lambda value: consume(reveal_type(value)) # revealed: int
x4: IntCallback = lambda value: consume(reveal_type(value)) # revealed: int
x5: IntCallbackAliasType = lambda value: consume(reveal_type(value)) # revealed: int
Lambda contextual inference through TypeAliasType on Python 3.11
[environment]
python-version = "3.11"
On Python 3.11, typing_extensions.TypeAliasType provides the same alias semantics without the
type statement:
from typing import Callable
from typing_extensions import TypeAliasType
IntCallbackOrInt = TypeAliasType("IntCallbackOrInt", Callable[[int], None] | int)
def consume(value: int) -> None:
pass
y1: IntCallbackOrInt | str = lambda value: consume(reveal_type(value)) # revealed: int
Unified call inference
Generic call arguments are inferred under fixpoint iteration, allowing constraints from call arguments to contribute type context to sibling arguments within a given generic call, until convergence.
from typing import Any, Callable, Literal, Sequence, TypedDict, TypeVar, overload
def combine[T](x: T, y: list[T], z: list[T]) -> T:
return x
def combine_reversed[T](x: T, z: list[T], y: list[T]) -> T:
return x
def _(x: int, y: int | str, z: int | str | None):
x1: int | str | None = combine(y, [x], [z])
reveal_type(x1) # revealed: int | str | None
x2 = combine(y, [x], [z])
reveal_type(x2) # revealed: int | str | None
x3 = combine_reversed(y, [z], [x])
reveal_type(x3) # revealed: int | str | None
def collection_pair[T](pair: tuple[T, list[T]]) -> T:
return pair[0]
x = collection_pair((1, [True]))
reveal_type(x) # revealed: int
def callable_pair[T](pair: tuple[Callable[[T], int], list[T]]) -> None:
function, values = pair
function(values[0])
callable_pair((lambda value: reveal_type(value) + 1, [1])) # revealed: int
def nested_pair[T](pair: tuple[T, list[T]]) -> T:
return pair[0]
x = nested_pair(("value", [None]))
reveal_type(x) # revealed: str | None
class A(TypedDict):
a: int
b: int
def pair_with_list[T](x: T, y: list[T]) -> T:
return x
def pair_with_sequence[T](x: T, y: Sequence[T]) -> T:
return x
def list_pair[T](x: list[T], y: list[T]) -> T:
return x[0]
def pair[T](x: T, y: T) -> T:
return x
def _(a: A, b: list[A]):
x1: A = pair_with_list(a, [{"a": 1, "b": 2}])
reveal_type(x1) # revealed: A
# TODO: This should solve to `A`.
x2 = pair_with_list(a, [{"a": 1, "b": 2}])
reveal_type(x2) # revealed: A | dict[str, int]
x3 = pair_with_sequence(a, [{"a": 1, "b": 2}])
reveal_type(x3) # revealed: A
# TODO: This should solve to `A`.
x4 = list_pair(b, [{"a": 1, "b": 2}]) # error: [invalid-argument-type]
reveal_type(x4) # revealed: A | dict[str, int]
x5 = pair({"a": 1, "b": 2}, a)
reveal_type(x5) # revealed: A
x6 = pair(a, {"a": 1, "b": 2})
reveal_type(x6) # revealed: A
A call argument contributes constraints to its siblings even if they form an arbitrary subset of its inferred type.
def copy[T](items: list[T]) -> list[T]:
return items.copy()
def copy_or_none[T](items: list[T]) -> list[T] | None:
raise NotImplementedError
def _(
rows: list[list[int] | list[str]],
optional_rows: list[list[int] | list[str] | None],
) -> None:
pair_with_list(reveal_type(copy([1])), rows) # revealed: list[int]
pair_with_list(reveal_type(copy_or_none([1])), optional_rows) # revealed: list[int] | None
def pack[T](items: list[T]) -> tuple[list[T]]:
return (items,)
def _(rows: list[tuple[list[int] | list[str]] | None]) -> None:
pair_with_list(pack([1]), rows)
from typing import TypedDict, reveal_type
class TD(TypedDict):
x: int
def f[T](x: T, y: T) -> T:
return x
def _(td: TD):
# TODO: The initial type of the dictionary literal pollutes later
# iterations, meaning we fail to narrow to `TD` here.
# revealed: TD | dict[str, int]
x = reveal_type(f(td, reveal_type({"x": 1}))) # revealed: TD | dict[str, int]
# TODO: This should also be `TD`.
x = f(td, reveal_type({"x": 1})) # revealed: TD | dict[str, int]
reveal_type(x) # revealed: TD | dict[str, int]
class ActiveInitializer[T]:
def __new__(cls, *args: object) -> "ActiveInitializer[T]":
return super().__new__(cls)
def __init__(self, value: T, values: list[T]) -> None:
pass
x = ActiveInitializer(1, [True])
reveal_type(x) # revealed: ActiveInitializer[int]
class InactiveInitializer:
def __new__[T](cls, value: T, values: list[T]) -> T:
return value
def __init__(self) -> None:
pass
x = InactiveInitializer(1, [True])
reveal_type(x) # revealed: int
def consume_and_produce[T, R](
consumer: Callable[[T], R],
producer: Callable[[], T],
value: T,
) -> T:
produced = producer()
consumer(produced)
consumer(value)
return produced
x = consume_and_produce(
lambda x: reveal_type(x), # revealed: str | int
lambda: "s",
1,
)
reveal_type(x) # revealed: Literal["s", 1]
def nested_callable[T](
value: T,
callbacks: Sequence[Callable[[Callable[[T], None]], None]],
) -> None:
pass
nested_callable(
1,
[lambda callable: print(reveal_type(callable))], # revealed: (int, /) -> None
)
class Base: ...
class Dog(Base): ...
class Cat(Base): ...
BaseType = TypeVar("BaseType", bound=Base)
def register_handlers(handlers: dict[str, type[BaseType]]) -> None: ...
register_handlers({"dog": Dog, "cat": Cat})
class X: ...
def accept_classes[T: X](classes: list[type[T]]) -> None: ...
accept_classes([X])
FloatDtype = type[float] | Literal["float"]
@overload
def overloaded_call(data: Sequence[str], dtype: object) -> str: ...
@overload
def overloaded_call(data: list[Any], dtype: FloatDtype) -> float: ...
@overload
def overloaded_call[T](data: Sequence[T], dtype: Literal["generic"]) -> T: ...
def overloaded_call(data: object, dtype: object) -> object:
return data
def _(dtype: FloatDtype):
x = overloaded_call([1.0], dtype)
reveal_type(x) # revealed: float
from typing import Protocol, runtime_checkable
@runtime_checkable
class TakesInt(Protocol):
def __call__(
self,
tag: Literal["int"],
callback: Callable[[int], int],
) -> int: ...
@runtime_checkable
class TakesStr(Protocol):
def __call__(
self,
tag: Literal["str"],
callback: Callable[[str], str],
) -> str: ...
def _(callback: TakesInt) -> None:
if isinstance(callback, TakesStr):
reveal_type(callback) # revealed: TakesInt & TakesStr
# TODO: Perform fixpoint iteration when evaluating callable intersections.
x1 = callback("int", lambda value: reveal_type(value) + 1) # revealed: Unknown
reveal_type(x1) # revealed: int
# TODO: Perform fixpoint iteration when evaluating callable intersections.
x2 = callback("str", lambda value: reveal_type(value) + "!") # revealed: Unknown
reveal_type(x2) # revealed: str
A structural type context can infer a gradual lower bound and a static upper bound before dictionary values contribute their constraints. The preliminary solution should retain the gradual lower bound.
T_co = TypeVar("T_co", covariant=True)
class DictLike(Protocol[T_co]):
def __getitem__(self, key: str, /) -> T_co: ...
def __setitem__(self, key: str, value: Any, /) -> None: ...
class Command: ...
def _(command: Any):
# revealed: dict[str, Any]
mapping: DictLike[type[Command]] = reveal_type({"command": command})
Note that long chains of callables with constraint dependencies in reverse source-order may require multiple fixpoint iterations.
from typing import Callable
def chain[A, B, C, D](
first: Callable[[C], D],
second: Callable[[B], C],
third: Callable[[A], B],
source: list[A],
) -> D:
return first(second(third(source[0])))
x = chain(
lambda c: c + 1,
lambda b: b + 1,
lambda a: a + 1,
[1, 2, 3],
)
reveal_type(x) # revealed: int
The upper bound on iterations is calculated based on the number of independent occurences of inferable type variables, not the number of arguments.
from typing import Callable
def list_to_callable[T](values: list[T]) -> Callable[[T], T]:
raise NotImplementedError
def propagate[A, B, C, D](
first: Callable[[C], D],
second: Callable[[B], C],
third: Callable[[A], B],
source: list[A],
) -> D:
return first(second(third(source[0])))
def propagate_tuple[A, B, C, D](
arguments: tuple[
Callable[[C], D],
Callable[[B], C],
Callable[[A], B],
list[A],
],
) -> D:
raise NotImplementedError
def _(seed: int):
x = propagate(
list_to_callable([]),
list_to_callable([]),
list_to_callable([]),
[seed],
)
reveal_type(x) # revealed: int
x = propagate_tuple((
list_to_callable([]),
list_to_callable([]),
list_to_callable([]),
[seed],
))
reveal_type(x) # revealed: int
An outer declared type should not widen the inferred type of a callback parameter if a sibling argument provides a narrower type:
def pick[T](
values: list[T],
key: Callable[[T], object],
default: T | None = None,
) -> T | None:
return default
def _(values: list[str]) -> str | None:
return pick(values, key=lambda value: reveal_type(value).upper()) # revealed: str
def _(values: list[list[Any]]) -> list[Any] | None:
return pick(values, key=lambda value: reveal_type(value).append(1)) # revealed: list[Any]
Similarly, the outer declared type should not pollute the inferred type of a nested generic call, if it originates from an unsatisfiable overload arm:
from typing import Callable, overload
class Parent: ...
class Child(Parent): ...
@overload
def inner[T](value: T, key: None = None) -> T: ...
@overload
def inner[T](value: T, key: Callable[[T], object]) -> T: ...
def inner[T](value: T, key: Callable[[T], object] | None = None) -> T:
return value
@overload
def outer(value: Child) -> Child: ...
@overload
def outer(value: Parent) -> Parent: ...
def outer(value: Parent) -> Parent:
return value
def _(value: Parent):
reveal_type(outer(inner(value, lambda _: None))) # revealed: Parent
Only diagnostics from the final round of iteration are preserved:
def diagnostic_pair[T](value: T, values: list[T]) -> T:
return value
# error: [unresolved-reference]
diagnostic_pair(missing_name, [1])
diagnostic_pair(suppressed_missing, [1]) # ty: ignore[unresolved-reference]
def non_generic(value: int) -> int:
return value
# error: [unresolved-reference]
diagnostic_pair(non_generic(missing_argument), [1])
diagnostic_pair(non_generic(suppressed_argument), [1]) # ty: ignore[unresolved-reference]
Dynamic type context
A lambda parameter can use type context containing Any:
from typing import Any, Callable
def callable_pair[T](pair: tuple[Callable[[T], int], list[T]]) -> None:
function, values = pair
function(values[0])
def _(values: list[list[Any]]):
callable_pair((lambda value: len(reveal_type(value)), values)) # revealed: list[Any]
List literals widen based on dynamic type context contributed from a sibling argument:
def append[T](items: list[T], value: T) -> None:
items.append(value)
def example(value: str | Any) -> None:
append([1], value)
This also applies when a generic base class contributes gradual type context:
class GenericBase[T]: ...
class Specialized(GenericBase[str]): ...
class Mixed(Specialized, GenericBase[Any]): ...
def g[T](values: list[T], base: GenericBase[T]) -> list[T]:
return values
reveal_type(g([1], Specialized())) # revealed: list[int | str]
reveal_type(g([1], Mixed())) # revealed: list[int | str | Any]
Dynamic arguments also participate when inferring the specialization for a nested collection literal:
from ty_extensions._internal import Unknown
def merge[K, V](*maps: dict[K, V]) -> tuple[K, V]:
raise NotImplementedError
def _(dynamic: Unknown):
# TODO: The key and value types should also include `Unknown`.
reveal_type(merge({"a": 1}, {2: "b"}, dynamic)) # revealed: tuple[str | int, int | str]
reveal_type(merge(dynamic, {"a": 1}, {2: "b"})) # revealed: tuple[str | int, int | str]
def _(dynamic: Any):
# TODO: The key and value types should also include `Any`.
reveal_type(merge({"a": 1}, {2: "b"}, dynamic)) # revealed: tuple[str | int, int | str]
reveal_type(merge(dynamic, {"a": 1}, {2: "b"})) # revealed: tuple[str | int, int | str]
Lambda parameter cycles
The return context can determine the types of mutually dependent identity callbacks. Unresolved
parameter types do not contribute Unknown to the inferred return type:
[environment]
python-version = "3.13"
[rules]
unsound-return = "error"
from collections.abc import Callable
def f[T, U, V](extract: Callable[[U], V], store: Callable[[V], U], key: Callable[[T], str]) -> list[V]:
raise NotImplementedError
def _[T](key: Callable[[T], str]) -> list[T]:
return f(key=key, extract=lambda x: x, store=lambda x: x)
Gradual types from arguments still propagate through an identity lambda:
from typing import Any
from ty_extensions._internal import Unknown
def apply[T, R](function: Callable[[T], R], value: T) -> R:
return function(value)
def _(value: Any):
reveal_type(apply(lambda x: x, value)) # revealed: Any
def _(value: Unknown):
reveal_type(apply(lambda x: x, value)) # revealed: Unknown
Type-variable defaults as type context
An explicit type-variable default can provide fallback context when arguments do not determine a type:
from collections.abc import Callable
class Base[T]: ...
class Child[T](Base[T]): ...
class Container[T = Base[str]]:
def __init__(self, factory: Callable[[], T] | None = None) -> None: ...
reveal_type(Container()) # revealed: Container[Base[str]]
x1 = Container(Child)
reveal_type(x1) # revealed: Container[Child[str]]
reveal_type(Container(Child)) # revealed: Container[Child[str]]
An inferred argument type takes precedence over the default:
reveal_type(Container(Child[int])) # revealed: Container[Child[int]]
def create[T = Base[str]](factory: Callable[[], T], value: T) -> T:
return factory()
def _(value: Child[int]):
reveal_type(create(Child, value)) # revealed: Child[int]
Dunder Calls
The key and value parameters types are used as type context for __setitem__ dunder calls:
from typing import TypedDict
class Bar(TypedDict):
bar: list[int | str]
class Baz(TypedDict):
bar: list[int | None]
def _(x: dict[str, Bar]):
x["foo"] = reveal_type({"bar": [2]}) # revealed: Bar
class X:
def __setitem__(self, key: Bar, value: Bar): ...
def _(x: X):
# revealed: Bar
x[reveal_type({"bar": [1]})] = reveal_type({"bar": [2]}) # revealed: Bar
If the target is a union or intersection type, the key and value expressions may be inferred multiple times for each applicable type context:
from ty_extensions import Intersection
def _(x: X | dict[Baz, Baz]):
# revealed: dict[str, list[int]]
x[reveal_type({"bar": [1]})] = reveal_type({"bar": [2]}) # revealed: dict[str, list[int]]
class Y:
def __setitem__(self, key: Baz, value: Baz): ...
def _(x: Intersection[X, Y]):
# revealed: Bar
x[reveal_type({"bar": [1, "2"]})] = reveal_type({"bar": [3, "4"]}) # revealed: Bar
# revealed: Baz
x[reveal_type({"bar": [1, None]})] = reveal_type({"bar": [2, None]}) # revealed: Baz
Similarly, the declared type of a TypedDict key is used as type context:
from typing import Literal
class TD(TypedDict):
foo: list[int | None]
bar: list[int | str]
def _(x: TD, foo_or_bar: Literal["foo", "bar"]):
x["foo"] = reveal_type([1]) # revealed: list[int | None]
x["bar"] = reveal_type([2]) # revealed: list[int | str]
x[foo_or_bar] = reveal_type([3]) # revealed: list[int]
def _(x: TD | dict[str, list[int | float]]):
x["foo"] = reveal_type([4]) # revealed: list[int]
def _(x: Bar | Baz | dict[str, list[int | float]]):
x["bar"] = reveal_type([4]) # revealed: list[int]
As well as the value parameter type of augmented assignment dunder calls:
from typing import TypedDict
def _(bar: Bar):
bar |= reveal_type({"bar": [1]}) # revealed: Bar
class X:
def __ior__(self, other: Baz):
return self
def _(x: X):
x |= reveal_type({"bar": [1]}) # revealed: Baz
def _(x: X | Bar):
x |= reveal_type({"bar": [1]}) # revealed: dict[str, list[int]]
class Fallback:
def __or__(self, other: dict[str, list[int]]):
return self
def _(x: X | Fallback):
# Only the in-place method provides a contextual type for the dictionary.
x |= reveal_type({"bar": [1]}) # revealed: dict[str, list[int]]
class Y:
def __ior__(self, other: Bar):
return self
def _(x: Intersection[X, Y]):
# TODO: Reveal `Bar` and `Baz` here.
x |= reveal_type({"bar": [1, "2"]}) # revealed: dict[str, list[int | str]]
x |= reveal_type({"bar": [1, None]}) # revealed: dict[str, list[int | None]]
await expressions
Type context is also propagated through await expressions:
from typing import Literal
async def make_lst[T](x: T) -> list[T]:
return [x]
async def _():
x1 = await make_lst(1)
reveal_type(x1) # revealed: list[int]
x2: list[Literal[1]] = await make_lst(1)
reveal_type(x2) # revealed: list[Literal[1]]
x3: list[int | None] = await make_lst(1)
reveal_type(x3) # revealed: list[int | None]
Container inference
Empty, unannotated container literals are inferred based on future uses that extend throughout the entire scope:
x1 = []
x1.append(1)
x1.append("2")
reveal_type(x1) # revealed: list[int | str]
x1_sorted = []
x1_sorted.append("x")
x1_sorted.sort()
reveal_type(x1_sorted) # revealed: list[str]
Bare empty list(), set(), and dict() calls also participate in full-scope inference. Calls
through aliases and shadowed names are deliberately not refined:
list_result = list()
list_result.append(1)
list_result.append("2")
reveal_type(list_result) # revealed: list[int | str]
set_result = set()
set_result.add(1)
set_result.add("2")
reveal_type(set_result) # revealed: set[int | str]
dict_result = dict()
dict_result["a"] = 1
dict_result["b"] = "2"
reveal_type(dict_result) # revealed: dict[str, int | str]
def make_list() -> list[str]:
result = list()
result.append(1)
reveal_type(result) # revealed: list[int | str]
return result # error: [invalid-explicit-return]
def make_set() -> set[str]:
result = set()
result.add(1)
reveal_type(result) # revealed: set[int | str]
return result # error: [invalid-explicit-return]
def make_dict() -> dict[str, str]:
result = dict()
result["x"] = 1
reveal_type(result) # revealed: dict[str, int | str]
return result # error: [invalid-explicit-return]
set_alias = set
aliased_result = set_alias()
aliased_result.add(1)
reveal_type(aliased_result) # revealed: set[Unknown]
from typing import Never
class Result:
def abort(self) -> Never:
raise RuntimeError
def shadowed_constructor() -> int:
set = Result
result = set()
reveal_type(result) # revealed: Result
result.abort()
return "unreachable"
class X:
def __init__(self):
self.x = []
self.x.append(1)
self.x.append("2")
reveal_type(self.x) # revealed: list[int | str]
reveal_type(X().x) # revealed: list[int | str]
def _(flag: bool):
if flag:
x2 = []
x2.append(1)
reveal_type(x2) # revealed: list[int]
else:
x2 = []
x2.append("2")
reveal_type(x2) # revealed: list[str]
def takes_list_int(x: list[int]): ...
x3 = []
takes_list_int(x3)
# TODO: This should reveal `list[int]`, but we do not currently record
# argument constraints for arbitrary function calls.
reveal_type(x3) # revealed: list[Unknown]
def append[T](x: list[T], y: T):
x.append(y)
x4 = []
append(x4, 1)
append(x4, "2")
# TODO: This should reveal `list[int | str]`, but we do not currently record
# argument constraints for arbitrary function calls.
reveal_type(x4) # revealed: list[Unknown]
x5 = []
_: list[int] = reveal_type(x5) # revealed: list[int]
def _() -> list[int | None]:
x6 = []
return reveal_type(x6) # revealed: list[int | None]
def _() -> int:
invalid_x6 = []
return invalid_x6 # error: [invalid-explicit-return]
A return annotation can provide a union of fixed-length tuple element types. Inferring an empty list
from this context doesn't wrongly widen the type of result to a list of variable-length tuples:
def tuples() -> list[tuple[()] | tuple[int]]:
result = []
return result
x7 = []
x7[:] = [1, "2", 3.0]
reveal_type(x7) # revealed: list[float | str]
from typing import Literal
x8 = []
one: Literal[1] = 1
x8.append(one)
reveal_type(x8) # revealed: list[Literal[1]]
x9 = []
x10 = []
x9.append(1)
x9.append("2")
x10.append(3)
reveal_type(x9) # revealed: list[int | str]
reveal_type(x10) # revealed: list[int]
x11 = []
x12 = []
x11.append(1)
x12.append(x11)
reveal_type(x11) # revealed: list[int]
reveal_type(x12) # revealed: list[list[int]]
x13 = []
x13.append(x13)
reveal_type(x13) # revealed: list[Divergent]
x14 = []
x15 = []
x14.append(x15)
x15.append(x14)
reveal_type(x14) # revealed: list[Divergent]
reveal_type(x15) # revealed: list[Divergent]
Collection-use constraints must converge when multiple collection literals are used in a container literal. This is a regression test for https://github.com/astral-sh/ty/issues/3778:
from typing import Any
def run(cond: bool, d: dict[Any, Any]) -> list[Any]:
a = {}
b = {}
if cond:
b = d
return [a.get("x", 0), b.get("x", 0)]
def assigned(cond: bool, d: dict[Any, Any]) -> list[Any]:
a = {}
b = {}
if cond:
b = d
result: list[Any] = [a.get("x", 0), b.get("x", 0)]
return result
def _(i):
x16 = []
x16.append(x16)
reveal_type(x16) # revealed: list[Divergent]
x17 = {}
x17.update(a=1)
reveal_type(x17) # revealed: dict[str, int]
x18 = {}
x18.update({"a": 1})
reveal_type(x18) # revealed: dict[str, int]
x19 = {}
x19["a"] = 1
x19["b"] = "2"
reveal_type(x19) # revealed: dict[str, int | str]
x20 = {}
x20["a"] = len(x20)
x20.setdefault("b", str(len(x20)))
reveal_type(x20) # revealed: dict[str, int | str]
x21 = []
_: list[int] = x21 # error: [invalid-assignment]
# TODO: We should error on this `append` instead of the assignment and not union
# later constraints after the element type has been fully constrained above, to
# avoid confusing error messages where the type of the collection may be unexpectedly
# influenced by uses later in the scope.
x21.append("a")
# TODO: This would then reveal `list[int]`.
reveal_type(x21) # revealed: list[int | str]
def _(flag: bool):
if flag:
x22 = []
else:
x22 = []
x22.append(1)
# TODO: This should reveal `list[int]`.
reveal_type(x22) # revealed: list[Unknown]
x23 = [None, None, None]
x23[0] = 1
x23[1] = "2"
x23[2] = 3.0
reveal_type(x23) # revealed: list[float | str | None]
x24 = {"a": 1}
x24[1] = "b"
reveal_type(x24) # revealed: dict[int | str, str | int]
Unconstrained collection use-sites
Calling a method that does not constrain a collection's element type does not affect its inferred type.
def _():
x1 = [1]
x1.reverse()
reveal_type(x1) # revealed: list[int]
x2 = {1}
x2.clear()
reveal_type(x2) # revealed: set[int]
x3 = {"a": 1}
x3.clear()
reveal_type(x3) # revealed: dict[str, int]
Calls that partially constrain the collection do not affect the type inferred for unrelated type variables.
def _():
values = {"a": 1}
values.pop("a")
reveal_type(values) # revealed: dict[str, int]
An empty collection remains unknown until another use supplies an element type:
def _():
x1 = []
x1.reverse()
reveal_type(x1) # revealed: list[Unknown]
x2 = []
x2.reverse()
x2.append(1)
reveal_type(x2) # revealed: list[int]
Gradual types that explicitly constrain a collection are preserved in the inferred type.
def _(unknown):
x1 = [1]
x1.reverse()
x1.append(unknown)
reveal_type(x1) # revealed: list[Unknown | int]
An upper bound on the element type introduced by a callback does not influence the type of the collection literal:
from typing import Any
def key(value) -> int:
return 0
def any_key(value: Any) -> int:
return 0
def _():
x1 = [(0, "a")]
x1.sort(key=lambda x: x[0])
reveal_type(x1) # revealed: list[tuple[int, str]]
x2 = [(0, "a")]
x2.sort(key=key)
# TODO: This should reveal `list[tuple[int, str]]`.
reveal_type(x2) # revealed: list[Unknown | tuple[int, str]]
x3 = [(0, "a")]
x3.sort(key=any_key)
# TODO: This should reveal `list[tuple[int, str]]`.
reveal_type(x3) # revealed: list[Any | tuple[int, str]]
Multi-inference diagnostics
Diagnostics unrelated to the type-context are only reported once:
from typing import TypedDict
def lst[T](x: T) -> list[T]:
return [x]
def takes_list_of_bool(x: list[bool], y: list[bool]): ...
def takes_list_of_int(x: list[int], y: list[int]): ...
def takes_list_of_int2(x: list[int], y: list[int]): ...
def _(x: int):
if x == 0:
y = takes_list_of_bool
elif x == 1:
y = takes_list_of_int
else:
y = takes_list_of_int2
if x == 0:
z = True
y(lst(True), [True])
# error: [possibly-unresolved-reference] "Name `z` used when possibly not defined"
y(lst(True), [z])
def g[T](x: T, y: list[T | None]) -> T:
return x
def _(flag: bool):
if flag:
x = 1
# error: [possibly-unresolved-reference]
x1: int | str = g(x, [1])
reveal_type(x1) # revealed: int
if flag:
y = "1"
# error: [possibly-unresolved-reference]
x2: list[int | None] | list[str | None] = [y]
reveal_type(x2) # revealed: list[str | None]
class Bar(TypedDict):
bar: int
class Bar2(TypedDict):
bar: int
class Bar3(TypedDict):
bar: int
def _(flag: bool, bar: Bar | Bar2 | Bar3):
if flag:
y = 1
# error: [possibly-unresolved-reference]
bar |= {"bar": y}
def _(flag: bool, x: dict[Bar, Bar] | dict[Bar2, Bar2] | dict[Bar3, Bar3]):
if flag:
y = 1
# error: [possibly-unresolved-reference]
x[{"bar": y}] = {"bar": 1}
# error: [possibly-unresolved-reference]
x[{"bar": 1}] = {"bar": y}
class TD(TypedDict):
foo: Bar
def _(flag: bool, x: TD | dict[str, Bar2] | dict[str, Bar3]):
if flag:
y = 1
# error: [possibly-unresolved-reference]
x["foo"] = {"bar": y}
def takes_str(_: str): ...
def takes_str2(_: str): ...
def _(a: object, b: object, flag: bool):
if flag:
x = takes_str
else:
x = takes_str2
# error: [unsupported-operator] "Operator `>` is not supported between two objects of type `object`"
x(f"{'a' if a > b else 'b'}")
from typing import TypedDict
class HasTD:
td: Bar
def _(has_td: HasTD, flag: bool):
if flag:
y = 1
# error: [possibly-unresolved-reference] "Name `y` used when possibly not defined"
has_td.td = {"bar": y}