mypy_extensions

mypy_extensions is a small, dependency-free Python module that defines type-system extensions on top of the standard library typing module. These extensions are understood by the mypy static type checker and the mypyc ahead-of-time compiler, letting you express typing constructs that the standard library does not (yet) provide.

It ships constructs such as TypedDict, precise callable-argument markers (Arg, DefaultArg, NamedArg, VarArg, KwArg), the trait and mypyc_attr decorators for mypyc, FlexibleAlias, and native fixed-width integer types (i64, i32, i16, u8) used when compiling Python with mypyc. It is one of the most widely installed packages on PyPI because it is a transitive dependency across the typed-Python ecosystem.

What You Get

• TypedDict for describing dictionaries with a fixed set of typed keys
• Callable-argument markers — Arg, DefaultArg, NamedArg, DefaultNamedArg, VarArg, KwArg — for precisely typing callback signatures
• mypyc helpers: the trait and mypyc_attr decorators plus native integer types i64, i32, i16, and u8
• FlexibleAlias for advanced generic-alias definitions consumed by mypy

Common Use Cases

• Annotating functions that accept callbacks with specific positional, keyword, and default argument shapes
• Compiling performance-critical Python modules with mypyc using native integer types and trait classes
• Providing structural dictionary types via TypedDict on older Python versions before it landed in typing

Under The Hood

Architecture — The entire package is a single module, mypy_extensions.py, with no runtime dependencies. It layers on top of the standard typing module, reusing internal helpers such as typing._type_check to mimic the ergonomics of built-in typing constructs. TypedDict is implemented via a _TypedDictMeta metaclass so subclassing and functional-call syntax both produce ordinary dicts at runtime, while the callable-argument markers (Arg, NamedArg, etc.) are thin factory functions that mypy reads statically. Native integer types (i64, i32, i16, u8) use a _NativeIntMeta metaclass whose __instancecheck__ treats them as plain int at runtime, deferring their real meaning to the mypyc compiler.

Tech Stack — Pure Python targeting 3.8+, built with the flit_core backend. There are no third-party runtime dependencies; development uses tox for multi-version testing and pre-commit for linting.

Code Quality — The codebase is compact and focused, with a dedicated test module (tests/testextensions.py) exercising the public constructs, a pre-commit configuration, and a tox matrix across supported Python versions. Deprecated names are handled through a module-level __getattr__ that emits DeprecationWarnings, showing attention to backward compatibility.

API Design — The public surface is deliberately small and mirrors standard-library typing conventions, so constructs like TypedDict and the argument markers feel native. Usage is a single import with no configuration, and the mypyc-specific helpers stay out of the way until you compile.