flake8-annotations-complexity

What it is and what it does

flake8-annotations-complexity is a flake8 extension that measures and enforces limits on type annotation complexity. It defines complexity as the maximum nesting level of type brackets—for example, `List[int]` has complexity 2, while `Tuple[List[Optional[str]], int]` has complexity 4. The plugin checks annotations on function arguments (positional, keyword-only, *args, **kwargs), return types (including async functions), and annotated variable assignments.

The plugin provides two checks: TAE002 flags annotations exceeding a nesting-depth threshold (default 3), and TAE003 flags annotations with too many elements (default 7). Both thresholds are configurable via flake8 command-line options. It runs on Python 3.10 through 3.14 and integrates directly into your existing flake8 workflow, making it easy to catch overly complex type hints during development or CI.

Use it for:

• Enforce a team style guide that discourages deeply nested generics like `Dict[str, List[Tuple[int, Optional[str]]]]` in code review.
• Catch annotation mistakes early—complex annotations often signal bad decomposition or wrong data structure choices.
• Improve code readability by flagging annotations that are hard to parse at a glance.
• Prevent Java-like verbosity in Python type hints during refactoring or new feature development.
• Integrate into CI/CD pipelines to maintain consistent annotation standards across a project.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A flake8 plugin that flags type annotations exceeding configurable complexity thresholds, measuring nesting depth and element count to encourage simpler, more readable type hints.

Yes. The plugin is actively maintained, has no known vulnerabilities, carries a permissive MIT license, and adds minimal install friction (only flake8 as a dependency). It solves a real code-quality problem—catching overly complex type annotations—and integrates seamlessly into existing flake8 workflows. Install it if your team values readable, maintainable type hints.

Install

flake8-annotations-complexity on PyPI

pip install flake8-annotations-complexity

uv add flake8-annotations-complexity

poetry add flake8-annotations-complexity

Installing flake8-annotations-complexity

Before you install

Low friction: pure Python wheel with only flake8 as a runtime dependency. Actively maintained as of 2026-08-14 with no known vulnerabilities.

License in practice

MIT license permits free use, modification, and distribution with minimal restrictions—suitable for both open and closed projects.

Quickstart

pip install flake8-annotations-complexity

# In your flake8 config or command line:
flake8 --max-annotations-complexity=3 --max-annotations-len=7 mycode.py

# Reports TAE002 (nesting too deep) and TAE003 (too many elements)

Requires Python 3.10 or later; flake8 must be installed and configured.

Verify before relying

• Whether the plugin integrates seamlessly with existing flake8 configurations and CI/CD pipelines.
• Performance impact on large codebases with many type annotations.

Package facts

Evidence: flake8_annotations_complexity-0.2.0-py3-none-any.whl

Keywords: annotations, flake8

Tags

More Python Modules packages