cognitive-complexity

What it is and what it does

Cognitive-complexity is a Python library that computes a numeric score representing how cognitively difficult a function is to understand. It works by parsing Python source code into an abstract syntax tree and applying heuristics that award complexity points for control-flow breaks, nesting depth, recursion, and logical operations. The library itself has no runtime dependencies and is typically used either as a standalone API or integrated into flake8 via the flake8-cognitive-complexity extension.

The package is based on research into cognitive complexity as a measure of code understandability—distinct from traditional cyclomatic complexity. The implementation is acknowledged to be an approximation rather than a precise realization of the original algorithm. The project has been abandoned and receives no active maintenance, though it remains functional for Python 3.6+ codebases.

Use it for:

• Integrate into a CI/CD pipeline to flag functions exceeding a complexity threshold and enforce code review for high-complexity changes.
• Use as a flake8 plugin to get real-time warnings during development when functions become too difficult to understand.
• Analyze legacy codebases to identify which functions are candidates for refactoring based on cognitive load.
• Build custom linting rules that combine cognitive complexity with other metrics to guide architectural decisions.

Worth the install?

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

Calculates cognitive complexity scores for Python functions by analyzing their abstract syntax tree, measuring how difficult code is to understand based on control flow, nesting, recursion, and logical operations.

Yes, if you need cognitive complexity analysis and are comfortable with an unmaintained library. The package is stable, has no dependencies, and works reliably on Python 3.6+. However, consider it a read-only tool: expect no bug fixes, security patches, or feature updates. If active maintenance is critical for your workflow, investigate whether a maintained alternative exists before committing to this version.

Install

cognitive-complexity on PyPI

pip install cognitive-complexity

uv add cognitive-complexity

poetry add cognitive-complexity

Installing cognitive-complexity

Before you install

High install friction: no runtime dependencies but marked as abandoned since the last commit on 2022-08-09 with no maintenance or security updates.

License in practice

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

Quickstart

import ast
from cognitive_complexity.api import get_cognitive_complexity

funcdef = ast.parse("def f(a):\n    return a * f(a - 1)").body[0]
print(get_cognitive_complexity(funcdef))  # Output: 1

Requires Python 3.6 or later; input must be an AST node (typically from ast.parse), not raw source code.

Verify before relying

• How closely the implementation matches G. Ann Campbell's original algorithm and whether deviations affect reliability for production linting.
• Whether the package is maintained under a different repository or if a maintained fork exists as a drop-in replacement.
• Current stability and compatibility with Python versions beyond 3.8 given the abandoned maintenance status.

Package facts

Evidence: cognitive_complexity-1.3.0.tar.gz

Keywords: flake8

Tags

More Python Modules packages