Registry / testing / flake8-annotations-complexity

flake8-annotations-complexity

JSON →
library0.1.0pypypiunverified

An extension for flake8 to report on excessively complex type annotations. Complex type annotations often indicate suboptimal annotation usage, poor code decomposition, or an improper choice of data structure, making the code harder to read. The plugin calculates annotation complexity based on the maximum nesting level (e.g., `List[int]` is 2, `Tuple[List[Optional[str]], int]` is 4). The current version is 0.1.0, and it receives infrequent but active maintenance.

pip install flake8-annotations-complexity
INSTALL
IMPORT
SIG · FLAKE8-ANNOTATIONS
F
flake8-annotations-complexity
testingpythonv0.1.0
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

This quickstart demonstrates how to install and use `flake8-annotations-complexity`. It creates a temporary Python file with varying annotation complexities, then runs `flake8` first with the default complexity limit (3) and then with a higher limit (4). The plugin reports errors (TAE002) for annotations exceeding the configured maximum complexity.

import os from typing import List, Dict, Union, Optional # Create a dummy Python file to lint python_code = ''' # test_complexity.py from typing import List, Dict, Union, Optional def func_with_complex_annotation( data: Dict[str, List[Union[int, Optional[str]]]] ) -> Dict[str, List[Union[int, Optional[str]]]]: """A function with a very complex type annotation.""" return data def func_with_medium_annotation( config: Dict[str, List[str]] ) -> None: """A function with a medium-complexity annotation.""" pass def func_with_simple_annotation( name: str, age: int ) -> str: """A function with simple annotations.""" return f"{name} is {age} years old" ''' with open('test_complexity.py', 'w') as f: f.write(python_code) # Run flake8 with the plugin print("\n--- Running flake8 with default max-annotations-complexity (3) ---") os.system("flake8 test_complexity.py") print("\n--- Running flake8 with max-annotations-complexity set to 4 ---") os.system("flake8 --max-annotations-complexity=4 test_complexity.py") # Clean up the dummy file os.remove('test_complexity.py')
flake8 --version
Debug
Known issues
breakingVersion 0.1.0 of `flake8-annotations-complexity` officially drops support for Python 3.7 and 3.8. Projects using these Python versions must upgrade to Python 3.9 or newer to use this version of the plugin or stick to an older plugin version.
fix
Upgrade your project's Python version to 3.9 or later, or pin `flake8-annotations-complexity` to a version prior to 0.1.0.
affects: 0.1.0+
gotchaThe default maximum annotation complexity is 3. This can be surprisingly low for common, slightly nested types like `List[Dict[str, int]]` (complexity 3) or `Dict[str, List[Union[int, str]]]` (complexity 4). Be aware of this default and adjust it using the `--max-annotations-complexity` option in your `flake8` configuration (e.g., `setup.cfg`, `pyproject.toml`) if it's too restrictive for your codebase.
fix
Configure the `max-annotations-complexity` option in your `flake8` config file (e.g., `setup.cfg` or `pyproject.toml`): `[flake8]\nmax-annotations-complexity = 4`
affects: <0.1.0
gotchaThe plugin counts `typing.Annotated` wrappers towards annotation complexity. If you're using `Annotated` (PEP-593) for adding metadata (e.g., with Pydantic fields), types like `Annotated[dict[str, Model], Field(...)]` might be flagged as too complex even if the underlying type's structure is not inherently complex.
fix
Consider increasing `--max-annotations-complexity` to accommodate `Annotated` types, or explicitly ignore specific lines/files if the `Annotated` usage is deemed acceptable.
affects: All
gotchaThe plugin currently only implements a single rule (`TAE002`) for annotation complexity. This means there's no built-in differentiation in complexity checks between various annotation contexts (e.g., function arguments vs. return types vs. variable annotations).
fix
If different complexity thresholds are desired for different contexts, consider using per-file ignores or `noqa` comments to manage specific cases, or look for alternative plugins that offer more granular control.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'flake8-annotations-complexity'
The flake8-annotations-complexity package has not been installed in your Python environment or is not accessible by flake8.
fix
Run `pip install flake8-annotations-complexity` to install the plugin.
TAE002 too complex annotation (X > Y)
The type annotation's nesting level exceeds the maximum allowed complexity (Y), which by default is 3. 'X' indicates the actual complexity detected.
fix
Refactor the complex type annotation using `TypeAlias` (for Python 3.10+) or simpler types, or adjust the maximum allowed complexity with `--max-annotations-complexity=N` in your flake8 command or configuration file.
flake8: error: no such option: --max-annotations-complexity
This error occurs if the `flake8-annotations-complexity` plugin is not correctly installed or recognized by `flake8`, meaning the `--max-annotations-complexity` option is not available.
fix
Ensure `flake8-annotations-complexity` is installed by running `pip install flake8-annotations-complexity`. If it's already installed, verify flake8 can find it by checking `flake8 --version` output for the plugin.
flake8 not picking up config file
Flake8 is not reading the configuration from your `setup.cfg`, `tox.ini`, or `.flake8` file, which might be due to an incorrect file name, location, or missing the `[flake8]` section header.
fix
Ensure your configuration file is named correctly (`.flake8`, `setup.cfg`, or `tox.ini`), is located in the project root or an ancestor directory, and contains the `[flake8]` header before any flake8-specific options like `max-annotations-complexity` or `ignore = TAE002`.
Upgrade
Version history
0.1.0latest on PyPI · released Mar 4, 2025
Audit
Dependencies
flake8requiredThis is a plugin for flake8 and requires flake8 to be installed to function.
pythonrequiredRequires Python 3.9 or newer.
Agent activity
2 hits · last 30 days
node
2
Resources
flake8-annotations-complexity — pip install flake8-annotations-complexity · libregistry