{"id":6632,"library":"flake8-annotations-complexity","title":"flake8-annotations-complexity","description":"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.","status":"active","version":"0.1.0","language":"en","source_language":"en","source_url":"https://github.com/best-doctor/flake8-annotations-complexity","tags":["flake8","linter","static-analysis","type-annotations","complexity","code-quality"],"install":[{"cmd":"pip install flake8-annotations-complexity","lang":"bash","label":"Install package"}],"dependencies":[{"reason":"This is a plugin for flake8 and requires flake8 to be installed to function.","package":"flake8","optional":false},{"reason":"Requires Python 3.9 or newer.","package":"python","optional":false}],"imports":[],"quickstart":{"code":"import os\nfrom typing import List, Dict, Union, Optional\n\n# Create a dummy Python file to lint\npython_code = '''\n# test_complexity.py\nfrom typing import List, Dict, Union, Optional\n\ndef func_with_complex_annotation(\n    data: Dict[str, List[Union[int, Optional[str]]]]\n) -> Dict[str, List[Union[int, Optional[str]]]]:\n    \"\"\"A function with a very complex type annotation.\"\"\"\n    return data\n\ndef func_with_medium_annotation(\n    config: Dict[str, List[str]]\n) -> None:\n    \"\"\"A function with a medium-complexity annotation.\"\"\"\n    pass\n\ndef func_with_simple_annotation(\n    name: str, age: int\n) -> str:\n    \"\"\"A function with simple annotations.\"\"\"\n    return f\"{name} is {age} years old\"\n'''\n\nwith open('test_complexity.py', 'w') as f:\n    f.write(python_code)\n\n# Run flake8 with the plugin\nprint(\"\\n--- Running flake8 with default max-annotations-complexity (3) ---\")\nos.system(\"flake8 test_complexity.py\")\n\nprint(\"\\n--- Running flake8 with max-annotations-complexity set to 4 ---\")\nos.system(\"flake8 --max-annotations-complexity=4 test_complexity.py\")\n\n# Clean up the dummy file\nos.remove('test_complexity.py')","lang":"python","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":"0.1.0+"},{"fix":"Configure the `max-annotations-complexity` option in your `flake8` config file (e.g., `setup.cfg` or `pyproject.toml`): `[flake8]\\nmax-annotations-complexity = 4`","message":"The 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.","severity":"gotcha","affected_versions":"<0.1.0"},{"fix":"Consider increasing `--max-annotations-complexity` to accommodate `Annotated` types, or explicitly ignore specific lines/files if the `Annotated` usage is deemed acceptable.","message":"The 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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"The 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).","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}