Advanced `TypedDict` support

[carljm]

• Introduce a new Type variant, basic support for class-based TypedDict syntax
  • Parse a TypedDict specification from the class body
  • Implement / test assignability to Mapping[str, object]
  • Make sure that TypedDict-based objects do not behave like instances of that class. For example, attribute access should not work.
  • Implement fallback to _typeshed._type_checker_internals.TypedDictFallback
• Type inference for key accesses (movie['directory'] -> str)
• Validation of writes to keys (synthesized __setitem__ method with key: Literal["key1"], value: ValueType1?)
• Validation of constructor calls (Movie(name="Blade Runner", year=1982))
• Validation of {…} literals to TypedDict types
• Totality
  • Required and NotRequired
• Implement / write tests for generic TypedDicts
• Implement / write tests for recursive TypedDicts
• Support type inference for instance.get("known_key")?
• PEP 705 support (ReadOnly)
• Implement structural assignability for TypedDicts #1387
• Implement disjointness for TypedDict.
• Support TypedDicts in all contexts (return position, function call arguments, etc) => type context (bidirectional checking) #168
• Implement .normalize() for TypeDictType.
• Investigate Pydantic-specific performance problems introduced in #21467.
• Submit a correction to the upstream assignability rules => Restore a missing TypedDict subtyping requirement python/typing#2119
• Support closed and extra_items for TypedDicts (PEP 728) #3096
• Functional TypedDict syntax #3095
• Support for Unpack Support typing.Unpack #1746
• Overriding of fields in inheritance Detect invalid overrides of TypedDict items #3097
• Correctness, validation
  • Implement checks based on supported and unsupported operations
  • TypedDict type objects cannot be used in isinstance checks
  • Only item definitions in the class body (no methods, for example)
  • Specifying a metaclass is not allowed
  • Can only subclass TypedDict, TypedDict- based types and Generic
  • Implement / write tests for subclassing of TypedDict-based classes including multiple inheritance
• Add TypedDict to property tests.
• LSP support (competitions, go to definitions, rename, hover, ...)
• Performance
  • Try out the optimization proposed in [ty] Infer types for key-based access on TypedDicts ruff#19763 (comment)
  • Add a micro-benchmark for large TypedDicts

[tylerlaprade]

And total=False

[JelleZijlstra]

TypedDict has a few interesting properties that may affect core concepts in the type system, so I'll be interested to see how you handle them.

The spec says that a TypedDict must be an instance of dict itself, not a subclass. I think that means these test cases should pass:

from typing import Mapping, TypedDict, assert_type

class TD(TypedDict):
    a: int

class SubDict[KT, VT](dict[KT, VT]):
    pass

def f(x: TD | dict[int, str]):
    if isinstance(x, SubDict):
        assert_type(x, SubDict[int, str])
    else:
        assert_type(x, TD | dict[int, str])

def g(x: TD | Mapping[int, str]):
    if isinstance(x, dict):
        assert_type(x, TD | dict[int, str])
    else:
        assert_type(x, Mapping[int, str])

(Neither mypy nor pyright currently pass all of this, mostly because they put Any/Unknown in type parameters. I'm not sure there's a good reason for that.)

However, a TypedDict type is not assignable to dict[T, U] for any values of T and U, not even to dict[Any, Any] (spec: https://typing.python.org/en/latest/spec/typeddict.html#assignability). This will have interesting consequences for the issues in #456: it means that narrowing from isinstance(x, dict) can't be implemented by intersecting with some version of forall K, V. dict[K, V].

[sslivkoff]

another piece of functionality that would eventually be nice here is the Unpack keyword

refs

1. https://typing.python.org/en/latest/spec/callables.html#unpack-kwargs
2. https://peps.python.org/pep-0692/

it's basically a way to use TypedDict's to type the **kwargs of a function

this ends up being very useful in practice for balancing python's flexibility with strict type checking