Type system features

This issue summarizes the support for various type system features in ty. Sections are organized to follow the structure of the Python typing specification, with some additional sections at the end.

If a top-level item is marked completed without any sub-items, you can generally expect that feature to be fully implemented (and we value any bug reports in case you find issues). If a top-level item is marked completed with open sub-items, the feature is generally working, but there might be some open issues — including but not limited to the ones listed (in this case, we also value any bug reports, but please search the issue tracker before doing so). If a top-level item is not checked, the feature is not implemented yet (it's probably not helpful to report bugs, but feel free to upvote the tracking issue or comment if you have useful information).

Special types and type qualifiers

Official documentation

tests: any.md, never.md, int_float_complex.md, final.md, classvar.md, annotated.md, union.md, instance_layout_conflict.md

• Any
• None
• NoReturn, Never
• object
• Literal[...] (strings, ints, bools, enum, None)
• LiteralString
• type[C]
• float/complex special cases (float means int | float)
• Final, Final[T]
  • Diagnostic: subclass overrides Final attribute Prevent overriding of Final attributes in subclasses #871
  • Diagnostic: Final without binding Detect if there is no binding to a symbol declared Final #872
• @final decorator
• @disjoint_base decorator
• ClassVar, ClassVar[T]
  • Diagnostic: ClassVar with type variable ClassVar shouldn't be allowed to contain type variables #518
• InitVar[T] (see Dataclasses)
• Annotated[T, ...]
• Required[T], NotRequired[T] (see TypedDict)
• ReadOnly[T] (see TypedDict)
• Union[X, Y], X | Y
• Optional[X]
• type() functional syntax Support type()'s functional syntax #740

Generics

Official documentation

tests: pep695/, legacy/, self.md, scoping.md

• TypeVar (legacy syntax)
• TypeVar (PEP 695 syntax: def f[T]())
• TypeVar upper bound (bound=)
• TypeVar constraints
• TypeVar defaults (PEP 696)
• TypeVar variance (covariant, contravariant)
• TypeVar variance inference (infer_variance)
• Generic classes (legacy and PEP 695 syntax)
• Generic functions (legacy and PEP 695 syntax)
• Generic type aliases (PEP 695)
  • Some limitations Cannot solve generics involving PEP 695 type aliases #1851
• ParamSpec (legacy and PEP 695 syntax)
  • ParamSpec usage validation Validate more usages of ParamSpec, P.args, P.kwargs #1861
• ParamSpec.args, ParamSpec.kwargs
• ParamSpec defaults
• Self
  • Self in attribute annotations support typing.Self used as attribute (or dataclass field) type #1124
  • typing.Self in staticmethods and metaclasses should be rejected #1897
  • Flag invalid locations of Self #2758
• Solve type variables in all cases improve typevar solving #623
  • Generic classes
  • Unions
  • Callables
  • Generic protocols support generic protocols in typevar solving #1714
  • Generic bounds/constraints on type variables Bounds and constraints of type variables cannot be generic #1839
• Support TypeVarTuple support TypeVarTuple #156

Protocols

Official documentation

tests: protocols.md

• Protocol class definition
• Generic protocols (legacy and PEP 695 syntax)
• Structural subtyping / assignability
• Protocol inheritance
• is_protocol(), get_protocol_members()
• @runtime_checkable decorator
• Protocol instantiation restriction
• Non-protocol class inheritance restriction
• @property members
  • Partial support Properly support @property members on protocols #1379
• Modules as protocol implementations
  • Method members have some issues Type checker fails to recognize a module as a valid implementation of a Protocol #931
• @classmethod and @staticmethod members Support @staticmethod protocol members and @classmethod protocol members #1381
• ClassVar members Support ClassVar protocol members #1380
• type[SomeProtocol] Support type[SomeProtocol] #903
• issubclass() on protocols with non-methods Emit diagnostic on issubclass calls against protocols with non-method members #1878

Type narrowing

Official documentation

tests: narrow/, type_guards.md

• isinstance() / issubclass() narrowing
• is None / is not None narrowing
• is / is not identity narrowing
• Truthiness narrowing
• assert narrowing
• match statement narrowing
• hasattr() narrowing
• callable() narrowing
• Assignment narrowing
• TypeIs[…] user-defined type guards
• TypeGuard[…] user-defined type guards Support narrowing using TypeGuard #117
• TypeIs/TypeGuard as method TypeIs does not work as a method/classmethod #1569
• Tuple length checks Support narrowing on tuple length checks #560
• Tuple match case narrowing Support narrowing on tuple match cases #561
• Narrowing after calls to functions returning Never/NoReturn better narrowing from conditional terminals and NoReturn calls #690

Tuples

Official documentation

tests: subscript/tuple.md, comparison/tuples.md, binary/tuples.md

• tuple[X, Y, Z] heterogeneous tuples
• tuple[X, ...] homogeneous tuples
• tuple[()] empty tuple
• Mixed tuples (tuple[X, *tuple[Y, ...]])
• Indexing with literal integers
• Diagnostic: index out of bounds
• Slicing tuples
• Tuple subclasses
• typing.Tuple (deprecated alias)
• Covariant element types
• Tuple inheritance
• Unpacking in assignments
• *args unpacking in calls
• Diagnostic: invalid comparisons for non-fixed-length tuples Emit diagnostics for unsupported comparisons involving non-fixed-length tuples #1741
• TypeVarTuple / Unpack support TypeVarTuple #156
• Intersection of fixed-length tuple with another type should be unpackable like the fixed-length tuple  #1978

NamedTuple

Official documentation

tests: named_tuple.md

• Class syntax (class Foo(NamedTuple): ...)
• Field access by name and index, slicing, unpacking
• Default values, diagnostic for non-default after default
• Read-only fields (assignment rejected)
• Inheritance, generic NamedTuples
• Multiple inheritance restriction
• Underscore field name restriction
• Prohibited attribute override check (_asdict, _make, …)
• _fields, _field_defaults, _make, _asdict, _replace
• Subtype of tuple[...]
• super() restriction in NamedTuple methods
• NamedTuple in type expressions
• type[NamedTuple] in type expressions
  • Not fully supported
• Functional syntax (NamedTuple("Foo", [...])) Support the functional syntax for NamedTuples #1049
• collections.namedtuple: not tested
• Subclass field conflicting with base class field: not tested

TypedDict

Official documentation

tests: typed_dict.md

• Class syntax (class Foo(TypedDict): ...)
• Key access by literal string, Final constants
• Constructor validation (missing keys, invalid types)
• total parameter
• Required[…], NotRequired[…]
• ReadOnly[…]
• Inheritance, generic TypedDicts
• Recursive TypedDict
• Structural assignability and equivalence
• Methods (get, pop, setdefault, keys, values, copy)
• __total__, __required_keys__, __optional_keys__
• Functional syntax (TypedDict("Foo", {...})) support TypedDict (and Required, NotRequired, ReadOnly) #154
• closed, extra_items (PEP 728) support TypedDict (and Required, NotRequired, ReadOnly) #154
• Unpack for **kwargs typing Support typing.Unpack #1746
• Tagged union narrowing Implement "tagged union" narrowing for namedtuples and arbitrary nominal types #1479
• Diagnostic: Invalid isinstance() check on TypedDict: not tested

Enums

Official documentation

tests: enums.md, comparison/enums.md

• Enum, IntEnum, StrEnum
• Literal[EnumMember] types
• .name, .value inference
• auto() value inference
• member(), nonmember()
  • enum.nonmember has the wrong type #1974
• Enum aliases
• _ignore_ attribute
  • List form not fully supported
• Implicitly final (subclassing restriction)
• Exhaustiveness checking (if/match)
• Custom __eq__/__ne__ methods
• Iteration over enum members
  • list(Enum) returns list[Unknown]
• Functional syntax (Enum("Name", [...])) Enums: advanced features #876
• enum.Flag expansion handling Enums: advanced features #876
• Custom __new__ or __init__ methods Enums: advanced features #876
• _generate_next_value_ support Enums: advanced features #876
• Value-based member retrieval (Color("red")) Enums: advanced features #876
• Narrowing with custom __eq__ in match Incorrect narrowing of enums with custom __eq__ methods in match statements #1454

Literals

Official documentation

tests: literal.md, literal_string.md

• Literal[0] (integer literals)
• Literal["a"] (string literals)
• Literal[b"a"] (bytes literals)
• Literal[True] (boolean literals)
• Literal[Color.RED] (enum literals)
• Literal[None]
• Nested Literal flattening
• Union of literals simplification
• Literal with type aliases
• Invalid form diagnostics
• LiteralString
• LiteralString assignability
• LiteralString narrowing
• LiteralString cannot be parameterized
• LiteralString cannot be subclassed

Callables

Official documentation

tests: callable.md, callable_instance.md

• Callable[[X, Y], R] syntax
• Callable[..., R] gradual form
• Callable with ParamSpec
• Callback protocols (__call__ method)
• Callable assignability (contra/covariance)
• Nested Callable types
• Callable in unions/intersections
• Invalid form diagnostics
• Concatenate Support Concatenate special form #1535
• Unpack for **kwargs typing Support typing.Unpack #1746

Overloads

Official documentation

tests: overloads.md, call/overloads.md

• @overload decorator
• Overload resolution
• Generic overloads
• Methods, constructors, @staticmethod, @classmethod
• Version-specific overloads
• Diagnostic: at least two overloads required
• Diagnostic: missing implementation (non-stub)
• Diagnostic: inconsistent decorators
• Diagnostic: @final/@override placement
• Variadic parameters with generics Correctly handle variadic parameters for overload step 5 filtering #1825
• Unannotated implementation validation: not tested report invalid overload implementation when implementation is unannotated #1232
• Diagnostic: overlapping overloads Check for overlapping overloads #103
• Implementation consistency check Check implementation consistency for an overloaded function #109
• @overload with other decorators No diagnostic reported for bad use of @override if the method has other decorators too #1675

Dataclasses

Official documentation

tests: dataclasses.md, fields.md

• @dataclass decorator (init, repr, eq, order, frozen, match_args, kw_only, slots, weakref_slot, unsafe_hash)
• field() (default, default_factory, init, kw_only, doc, repr, hash, compare)
• InitVar[…], ClassVar[…] exclusion, KW_ONLY sentinel
• fields(), __dataclass_fields__
• Final fields
• Inheritance, generic dataclasses, descriptor-typed fields
• replace(), __replace__
  • replace() returns Unknown
• asdict()
  • Incorrectly accepts class objects
• Diagnostic: frozen/non-frozen dataclass inheritance
• Diagnostic: non-default field after default field Advanced dataclass support #111
• Diagnostic: order=True with custom comparison methods Advanced dataclass support #111
• Diagnostic: frozen=True with __setattr__/__delattr__ Advanced dataclass support #111
• __post_init__ signature validation Advanced dataclass support #111
• Diagnostic: unsound subclassing of order=True dataclasses Add diagnostic warning about unsound subclassing of order=True dataclasses #1681
• astuple(): not tested
• make_dataclass(), is_dataclass(): not tested

dataclass_transform

Official documentation

tests: dataclass_transform.md

• Function-based transformers (decorator functions)
• Metaclass-based transformers
• Base-class-based transformers (__init_subclass__)
• eq_default parameter
• order_default parameter
• kw_only_default parameter
• frozen_default parameter
  • Metaclass override not working
• field_specifiers (init, default, default_factory, factory, kw_only, alias)
  • converter parameter dataclass_transform: feature overview #1327
• Other dataclass parameters (slots, etc.)
• Overloaded dataclass-like decorators
• Nested dataclass-transformers
• Combining with @dataclass (Home Assistant pattern)
• Custom dataclasses with __dataclass_{fields,params}__ fields are not considered DataclassInstance #1987

Constructors

Official documentation

tests: constructor.md

• __init__ signature inference
• __new__ signature inference
• Constructor inheritance from superclass
• Both __new__ and __init__ present
• Descriptor-based __new__/__init__
• Generic class constructor inference
• Type variable solving from constructor params
• Custom __new__ return type respect return type of __new__ #281
• Custom metaclass __call__ Respect signature of metaclass's __call__ #2288
• __new__/__init__ consistency validation
• Diagnostic: explicit __init__ on instance make it an error to explicitly call __init__ on an existing object #1016

Type aliases

Official documentation

tests: pep695_type_aliases.md, pep613_type_aliases.md, implicit_type_aliases.md

• Implicit type aliases (Alias = int)
• PEP 613 TypeAlias annotation
  • Fully stringified RHS not supported
• PEP 695 type statement
• Generic type aliases (PEP 695)
  • Limitations Cannot solve generics involving PEP 695 type aliases #1851
• Generic implicit/PEP 613 aliases
  • Partial support Support construction of objects based on generic implicit/PEP-613 type aliases #1739
• TypeAliasType introspection (__name__, __value__)
• Self-referential generic aliases Support self-referential generic implicit/PEP-613 type aliases #1738

Type checker directives

Official documentation

tests: directives/

• cast(T, value)
• Redundant cast diagnostic
• assert_type(value, T)
• assert_never(value)
• reveal_type(value)
• TYPE_CHECKING constant
• @no_type_check decorator
• type: ignore comments
• ty: ignore comments
• @deprecated decorator
• @override decorator
  • Diagnostic: override without @override decorator support @typing.override #155

Module resolution, imports, packages

Official documentation

tests: import/

• Stub files (.pyi)
• Stub packages (<package>-stubs)
• Partial stub packages (py.typed with partial)
• Namespace packages (PEP 420)
• Relative imports
• __all__ declarations
• __all__ mutations (.append, .extend, +=)
• __all__ with submodule __all__
• Wildcard (*) imports
• Wildcard imports in stubs re-export
• Re-export conventions (import X as X)
• Conditional re-exports in stub files
• Reachability constraints in imports
• Cyclic imports
• py.typed marker files
• conftest.py resolution (pytest)
• conda/pixi environment support
• PEP 723 inline script metadata Support single-file scripts with PEP 723 metadata #691
• Custom builtins (__builtins__.pyi) Support custom builtins #374
• Mono-repository support CLI: Mono-repository support #819
• Compiled extensions (.so files) improve diagnostics for C extension modules without stubs #487
• Per-library import suppression Support for ignoring unresolved-import per library #1354

Control flow analysis

tests: terminal_statements.md, exhaustiveness_checking.md, unreachable.md, exception/control_flow.md

• Terminal statements (return, raise)
• Loop control flow (break, continue)
• for/while loop analysis
• try/except/else/finally control flow
  • finally limitations Properly model control flow through finally suites #233
• Never/NoReturn function propagation
• Exhaustiveness checking (if/elif/else)
• Exhaustiveness checking (match)
• Advanced match pattern inference Advanced pattern matching support #887
• assert_never()
• sys.version_info comparisons
• sys.platform checks
• Statically known branches
• Return type inference Return type inference #128
• Walrus operator in boolean expressions correctly model short-circuting control flow in boolean expressions #626
• Cyclic control flow (loop back edges) cyclic control flow for loops #232
• Gray out unreachable code Gray out unreachable code #784
• Opt-in rule enforcing exhaustive match statements Rules for not exhaustive match case statements #1060
• Opt-in equivalent of mypy's strict-equality check strict-equality #576
• Warn on (accidentally) unreachable code blocks #1948

Invalid overrides

(Liskov Substitution Principle checks, etc)

tests: liskov.md, override.md

• Covariant return types
• Contravariant parameter types
• Invariant mutable attributes
• Full class hierarchy checked
• Positional/keyword parameter kind changes
• Additional optional parameters
• *args/**kwargs compatibility
• @staticmethod and @classmethod overrides
• Synthesized method overrides (dataclasses)
• Method overridden by non-method Extend invalid-method-override diagnostics to cover methods being overridden by non-methods #2156
• Non-method overridden by non-method Enforce the Liskov Substitution Principle for non-methods #2158

Abstract base classes

tests: return_type.md, overloads.md

• @abstractmethod decorator
• Empty body allowed for abstract methods
• @abstractmethod with @overload validation
• Emit diagnostic on constructor call to class with abstract methods #1877
• Emit diagnostic on unsound super() call to abstract method with trivial body #1923
• Emit diagnostic on unsound call to abstract @classmethod or @staticmethod with trivial body, when accessed on the class object itself #1927
• Emit diagnostic for unimplemented abstract method on @final class #2525

__slots__

tests: instance_layout_conflict.md

• __slots__ (string or tuple of strings)
• __slots__ (list, dict, set literals)
• Attribute resolution from __slots__ support __slots__ #1268
• Diagnostic: access outside __slots__ support __slots__ #1268
• Diagnostic: class variable shadowing __slots__ name support __slots__ #1268
• __dict__/__weakref__ presence validation support __slots__ #1268
• Diagnostic: non-empty __slots__ on builtin subclasses support __slots__ #1268

Special library features

Standard library:

• @cached_property Support cached_property #1446
• functools.partial Support functools.partial #1536
• functools.total_ordering Add support for functools.total_ordering #1202

Third-party library support (currently not decided how far we want to go here):

• Pydantic add dedicated support for pydantic #2403
• Django dedicated support for Django #1018
• attrs add dedicated support for attrs #2404