flake8-modern-annotations

flake8 plugin to validate type annotations accoring to modern practices.

• Postponed Evaluations of Annotations per PEP 563.
• Standard collection generics per PEP 585.
• Union types as X | Y per PEP 604.
• Optional types when PEP 604 Unions are available.

Activation

By default the plugin activates according to the Python version used for flake8 or when it sees a future import that enables modern annoations, e.g.:

from __future__ import annotations

Options exist for each feature to override the automatic activation.

Installation

Standard python package installation:

pip install flake8-modern-annotations

Type Aliases

Note that there are some restrictions when using modern annotation proactices with type aliases:

• Forward references

  • Must use string literals
  • Unions containing forward references must use typing.Union

• Standard collection generics

  • Cannot be used in type aliases if subscripted on Python < 3.9, e.g. X: TypeAlias = dict[str, str]

• Unions

  • | unions cannot be used in type aliases on Python < 3.9

This plugin will not report errors for the above cases with the default settings.

It is recommended to use the TypeAlias type for type aliases to help this plugin detect them properly in all cases. TypeAlias is available from typing in Python 3.10+ and typing_extensions in prior versions.

Options

modern-annotations-postponed : Controls validation of postponed annotations (PEP 563), choices: auto, always, never (default: auto)

modern-annotations-deprecated : Controls validation of deprecated types (PEP 585), choices: auto, always, never (default: auto)

modern-annotations-type-alias : Use deprecated types in type aliases (required for older Python < 3.9), choices: auto, always, never (default: auto)

modern-annotations-union : Controls checks for use of typing.Union (PEP 604), choices: auto, always, never (default: auto)

modern-annotations-optional : Controls checks for use of typing.Optional, choices: auto, always, never (default: auto)

modern-annotations-include-name : Include plugin name in messages

modern-annotations-no-include-name : Do not include plugin name in messages (default setting)

All options may be specified on the command line with a -- prefix, or can be placed in your flake8 config file.

auto settings turn on or off depending on the version of Python that flake8 is running on, and the presence of from __future__ import annotations in the code, which enables the modern annotations in Python 3.7+.

If developing code in Python 3.9+ that is expected to run on 3.7 or 3.8, use modern-annotations-type-alias=always to force older behavior of type aliases and ensure that the code will work.

Error Codes

Examples

x: 'Foo'  <-- MDA001
def foo(x: 'Foo') -> None:  <-- MDA002
def foo(x: Foo) -> 'Bar':  <-- MDA003

from typing import Dict  <-- MDA102
x: Dict[str, str]  <-- MDA202

from typing import Dict
MyDict = Dict[str, int]  <-- no error on Python 3.7/3.8

from typing import Union  <-- MDA400
x: Union[int, float]  <-- MDA401

from typing import Optional  <-- MDA500
x: Optional[int]  <-- MDA501