flake8-annotations vs mypy for Python type checking?

flake8-annotations focuses on detecting missing type annotations in function signatures, while mypy performs full type validation for correctness. Use flake8-annotations for enforcement and mypy for deep type safety, as the README notes they complement each other.

How to suppress warnings for None-returning functions in flake8-annotations?

Use the --suppress-none-returning flag, which suppresses ANN200-level errors for functions that return None or have no return statement. This is configurable via Flake8 options, as detailed in the README's configuration section.

Does flake8-annotations check variable annotations?

No, it does not check PEP 526 variable annotations. The README explicitly states that it only focuses on function annotations, leaving variable annotations to other tools or manual review.

Can I use flake8-annotations with pre-commit?

Yes, the README includes a pre-commit.ci status badge and implies integration, as it's a standard Flake8 plugin. You can add it to your .pre-commit-config.yaml file to run during commits for automated linting.

What decorators does flake8-annotations support for generic functions?

It supports decorators like functools.singledispatch and functools.singledispatchmethod by default, configurable via --dispatch-decorators. However, deeper imports (e.g., a.b.singledispatch) are not supported, as noted in the README.

How to enable opinionated warnings in flake8-annotations?

Use Flake8's extend-select option to enable warnings like ANN401 (disallowing typing.Any) without overriding other configurations. The README warns against using ignore to avoid enabling all implicitly disabled warnings.

Open-Awesome

flake8-annotations

MITPythonv3.3.0

A Flake8 plugin that checks for missing PEP 3107-style type annotations in Python functions and methods.

Visit Website GitHub

165 stars9 forks0 contributors

What is flake8-annotations?

flake8-annotations is a Flake8 plugin that statically analyzes Python code to detect missing type annotations in function and method signatures. It enforces the use of PEP 3107-style annotations, helping teams adopt consistent typing practices without performing full type checking. The tool focuses on annotation presence, leaving deeper type validation to dedicated type checkers like mypy.

Target Audience

Python developers and teams who want to enforce type annotation consistency in their codebases, particularly those using Flake8 for linting and aiming to improve code documentation and maintainability.

Value Proposition

Developers choose flake8-annotations for its focused, configurable approach to annotation enforcement, seamless integration with Flake8, and ability to catch missing annotations early in the development cycle without the overhead of a full type checker.

Overview

Flake8 Type Annotation Checking

Use Cases

Best For

Enforcing type annotation policies in Python projects
Catching missing annotations in function signatures during CI/CD
Improving code documentation through consistent type hints
Complementing mypy by focusing on annotation presence rather than type correctness
Linting codebases transitioning to typed Python
Configuring annotation rules for decorators like singledispatch and overload

Not Ideal For

Projects relying heavily on type comments or stub files for type hints
Codebases with decorators using deep imports (e.g., a.b.singledispatch)
Teams needing variable annotation checking or full type validation beyond presence

Pros & Cons

Pros

Focused Annotation Enforcement

Specifically targets missing PEP 3107-style function annotations, helping teams adopt consistent typing practices without the overhead of full type checking, as stated in the README's philosophy.

Configurable Decorator Support

Offers flags like --dispatch-decorators and --overload-decorators to suppress warnings for generic functions, with clear examples for singledispatch and overload decorators in the README.

Method-Specific Checks

Includes warnings for missing annotations on self and cls parameters in methods, referencing PEP 484 and PEP 563 for guidance on annotating instance and class methods.

Seamless Flake8 Integration

Installs as a Flake8 plugin and runs automatically, with verification shown in the README's installation example using flake8 --version.

Cons

Limited Scope for Type Validation

Only checks annotation presence, not type correctness; the README explicitly states it won't replace mypy, leaving deeper type checking to dedicated tools.

No Variable Annotation Checks

Does not support PEP 526 variable annotations, which is a gap for modern Python codebases using variable type hints, as mentioned in the README's limitations.

Complex Configuration for Advanced Use

Flags like --dispatch-decorators have limitations, such as no support for deeper imports (e.g., a.b.singledispatch), and dynamic typing support is restricted to specific patterns, adding setup complexity.

Frequently Asked Questions

Related Projects

wemake-python-styleguide

The strictest and most opinionated python linter ever!

Stars2,940

Forks439

Last commit14 hours ago

flake8-typing-only-imports

Flake8 plugin for managing type-checking imports & forward references.

Stars128

Forks15

Last commit10 days ago

flake8-type-checking