Mypy Extensions

1.1.0 · active · verified Sat Mar 28

mypy-extensions provides specific type system extensions for programs checked with the mypy type checker and the mypyc compiler. It acts as a bridge for experimental or mypy-specific typing features that may eventually be standardized in Python's `typing` module or `typing_extensions`, but are supported early by mypy. The library follows mypy's active development and releases are tied to mypy's needs, which typically sees multiple releases per month for the main mypy project.

Warnings

breaking The main `mypy` type checker, which `mypy-extensions` supports, has removed support for targeting Python 3.8 and now requires `--python-version 3.9` or greater. This means that while `mypy-extensions` 1.1.0 itself requires Python >=3.8, using `mypy` on projects targeting Python 3.8 with these extensions will lead to issues.
Fix: Ensure your project targets Python 3.9 or newer when using recent versions of mypy. Update your `pyproject.toml` or `mypy.ini` with `python_version = 3.9` or higher.
deprecated Mypy's 'Extended Callable types', which provided advanced ways to specify keyword and optional arguments in `Callable` types (and were historically a motivation for such extensions), are now deprecated. Users should migrate to 'callback protocols' instead.
Fix: Refactor advanced `Callable` type definitions to use callback protocols. Consult the mypy documentation on 'callback protocols' for migration guides.
gotcha Setting `non_interactive = True` in your `mypy.ini` or `setup.cfg` can silently prevent the Visual Studio Code Mypy extension (and potentially other IDE integrations) from displaying type checking errors in the editor, even though `mypy` itself reports them in its raw output.
Fix: Avoid `non_interactive = True` when using IDE integrations. If necessary for specific CI/CD environments, ensure it's not enabled in development configurations.
gotcha Many types initially provided by `mypy_extensions` (e.g., `TypedDict`, `Literal`, `Protocol`, `TypeGuard`, `Unpack`, `Required`, `NotRequired`, `override`) have since been moved into the standard library `typing` module or `typing_extensions` for broader compatibility across Python versions. Importing from `mypy_extensions` when `typing` or `typing_extensions` suffices can lead to unnecessary dependencies or confusion.
Fix: Prioritize imports from `typing` (for your target Python version) first, then `typing_extensions`, and finally `mypy_extensions` only for mypy-specific features or for backporting types to older Python versions where `typing_extensions` doesn't cover them. Regularly refactor imports to use `typing` once types are standardized.

Install

pip install mypy-extensions Install latest version

Imports

override
```
from mypy_extensions import override
```
While `typing.override` exists in Python 3.12+, `mypy_extensions.override` provides support for earlier Python versions when using mypy.
Required
```
from mypy_extensions import Required
```
For `TypedDict` keys, `mypy_extensions.Required` provides support for mypy, especially for Python versions older than 3.11 where `typing.Required` was introduced.
NotRequired
```
from mypy_extensions import NotRequired
```
Similar to `Required`, `mypy_extensions.NotRequired` provides support for `TypedDict` optional keys in mypy for Python versions older than 3.11.

Quickstart

This quickstart demonstrates the use of the `override` decorator from `mypy_extensions`. Run `mypy your_file_name.py` to type-check this example. If `SpecificAnalyzer.analyze` did not correctly override `BaseAnalyzer.analyze`, mypy would report an error. Note that for Python 3.12+, `typing.override` should generally be preferred if `mypy-extensions` is not otherwise needed. The core functionality of `mypy-extensions` is to provide types for mypy to check, not to execute specific runtime logic itself.

from mypy_extensions import override
from typing import Dict, Any, List

class BaseAnalyzer:
    def analyze(self, data: Dict[str, Any]) -> List[str]:
        raise NotImplementedError

class SpecificAnalyzer(BaseAnalyzer):
    @override
    def analyze(self, data: Dict[str, Any]) -> List[str]:
        if "items" in data:
            return [str(item) for item in data["items"]]
        return []

# Example usage for mypy checking
def process_data(analyzer: BaseAnalyzer, input_data: Dict[str, Any]) -> List[str]:
    return analyzer.analyze(input_data)

if __name__ == "__main__":
    analyzer_instance = SpecificAnalyzer()
    results = process_data(analyzer_instance, {"items": [1, "two", 3.0]})
    print(f"Analysis results: {results}")

# To type-check this file:
# mypy your_file_name.py

view raw JSON →