Flake8 Annotations

3.2.0 · active · verified Sun Apr 12

Flake8 Annotations is a plugin for Flake8 that enforces the presence and style of PEP 3107-style function annotations in Python code. It helps maintain consistent typing practices by flagging missing or incorrect type annotations. The current version is 3.2.0, and the project is actively maintained with regular updates addressing Python and Flake8 compatibility.

Warnings

breaking Version 3.0.0 introduced significant breaking changes, requiring Python >=3.8.1 and Flake8 >=5.0. Projects using older Python or Flake8 versions must upgrade their environment or pin flake8-annotations to a version <3.0.0.
Fix: Ensure your project's `requires-python` is >=3.8.1 and `flake8` dependency is >=5.0. Version 3.2.0 further raised the Python requirement to >=3.10.
breaking As of v3.0.0, support for PEP 484-style type comments (e.g., `# type: (str) -> None`) was removed. Instead, the new `ANN402` warning code (disabled by default) flags the *presence* of these now-unsupported type comments.
Fix: Migrate all type comments to PEP 526-style variable annotations (e.g., `def func(arg: str) -> None:`). Enable `ANN402` to detect lingering type comments: `flake8 --extend-select ANN402`.
gotcha `ANN4xx` error codes (e.g., `ANN401` for `typing.Any`, `ANN402` for type comments) are considered 'opinionated warnings' and are disabled by default.
Fix: To enable these warnings, use `flake8 --extend-select ANN401,ANN402` (or similar) in your command line or `extend-select = ANN401,ANN402` in your `pyproject.toml`, `setup.cfg`, or `.flake8` configuration file.
gotcha The `ANN401` warning for `typing.Any` can be overly strict, especially for `*args: Any` and `**kwargs: Any`.
Fix: Use the `--allow-star-arg-any` flag (added in v2.9.0) to suppress `ANN401` specifically for `*args` and `**kwargs` annotations if this is an acceptable pattern in your codebase.
gotcha By default, `flake8-annotations` does not respect `# type: ignore` comments.
Fix: Enable the `--respect-type-ignore` flag (available since v3.1.0) to suppress linting errors for functions or modules annotated with `# type: ignore`. Module-level `# mypy: ignore-errors` or `# type: ignore` on the first line is also supported.

Install

pip install flake8 flake8-annotations Install Flake8 and the annotations plugin

Imports

flake8_annotations
```
(Run flake8 command)
```
flake8-annotations is a Flake8 plugin and is automatically detected and run by Flake8 when installed. There are no direct Python imports for its functionality.

Quickstart

Install flake8 and flake8-annotations. Create a Python file (e.g., `example.py`) with functions, some with and some without type annotations. Run `flake8 example.py` from your terminal to see the reported issues regarding missing annotations.

import os

def my_function(arg1, arg2):
    # This function is missing type annotations
    return arg1 + arg2

def another_function(value: int) -> str:
    return str(value)

# To run flake8, save this as example.py and execute:
# flake8 example.py
# You should see errors like ANN001, ANN201 for my_function.

view raw JSON →