mypy-extensions

In practice, mypy-extensions is one of those packages you install once and rarely think about again - which is exactly what you want. It provides crucial type system features like TypedDict, Literal, and Protocol that have become standard in modern Python typing. The learning curve is minimal because you're mostly learning Python's typing system itself, not package-specific APIs.

The documentation is sparse, but that's actually okay since most of the extensions are well-documented in PEP specifications and mypy's own docs. When you need TypedDict for structured dictionaries or Protocol for structural subtyping, you just import and use them - they work exactly as expected with excellent mypy integration. Error messages come from mypy itself, so they're as good as your type checker.

The main gotcha is understanding that many of these features have been backported to typing or typing_extensions, so you might occasionally wonder which package to import from. For new projects targeting Python 3.8+, you'll increasingly use typing_extensions instead, but mypy-extensions remains relevant for specific mypy features like NewType and other checker-specific functionality.

Using mypy-extensions feels less like learning a new library and more like unlocking features that should have been in Python's typing module all along. The APIs like TypedDict, Literal, and Protocol are intuitive if you already understand Python type hints. Most developers will use this package without even realizing it, as it's pulled in as a dependency by mypy itself.

The learning curve is gentle because the package is small and focused. When you need something like @mypyc_attr or NewType extensions, the use cases are straightforward once you've read the brief docstrings. Error messages are handled by mypy itself, so you get the usual type-checking feedback. The main challenge is that documentation is minimal—mostly just type stubs and brief comments. You'll often need to reference mypy's documentation or look at real-world examples on GitHub to understand advanced features.

Debugging is rarely an issue since the package mostly provides primitive building blocks. When something goes wrong, it's usually a mypy configuration problem rather than a mypy-extensions issue. Community support exists primarily through mypy's channels, which are reasonably responsive.

mypy-extensions provides a small set of typing utilities that fill gaps in Python's standard typing module. In daily use, you'll primarily encounter TypedDict (now in typing since 3.8), Arg/DefaultArg for callable signatures, and the @mypyc_attr decorator. The package is deliberately minimal - there's no complex API to learn, just import what you need.

The DX is straightforward because these are simple type constructors that integrate seamlessly with mypy and other type checkers. IDE autocomplete works perfectly since these are just classes and decorators. Error messages come from mypy itself, not this package, so you get standard type checking feedback. Documentation is sparse but each utility is self-explanatory with clear docstrings.

The main friction point is knowing when you actually need this package versus stdlib typing. Many features have migrated to typing proper over Python versions, so you'll find yourself checking compatibility matrices. For modern Python 3.9+ projects, you might only need this as a transitive dependency through mypy itself.