Blazingly fast cognitive complexity analysis for Python, written in Rust.

Installation • Quick Start • Integrations • Documentation

Cognitive complexity measures how hard code is to understand by humans, not machines.

Unlike traditional metrics, cognitive complexity considers the mental effort required to read and comprehend code. It identifies truly complex code that needs refactoring, making it perfect for code reviews and maintaining clean codebases.

Key benefits:

• Human-focused — Aligns with developer intuition
• Actionable insights — Pinpoints hard-to-understand code
• Better maintenance — Improves long-term code quality

pip install complexipy
# or
uv add complexipy

# Analyze current directory
complexipy .

# Analyze specific file/directory
complexipy path/to/code.py

# Analyze with custom threshold
complexipy . --max-complexity-allowed 10

# Save results to JSON/CSV
complexipy . --output-json --output-csv

# Analyze current directory while excluding specific files
complexipy . --exclude path/to/exclude.py --exclude path/to/other/exclude.py

from complexipy import file_complexity, code_complexity

# Analyze a file
result = file_complexity("app.py")
print(f"File complexity: {result.complexity}")

for func in result.functions:
    print(f"{func.name}: {func.complexity}")

# Analyze code string
snippet = """
def complex_function(data):
    if data:
        for item in data:
            if item.is_valid():
                process(item)
"""

result = code_complexity(snippet)
print(f"Complexity: {result.complexity}")

- uses: rohaquinlop/complexipy-action@v2
  with:
    paths: .
    max_complexity_allowed: 10
    output_json: true

repos:
- repo: https://github.com/rohaquinlop/complexipy-pre-commit
  rev: v3.0.0
  hooks:
    - id: complexipy

complexipy supports configuration via TOML files. Configuration files are loaded in this order of precedence:

1. complexipy.toml (project-specific config)
2. .complexipy.toml (hidden config file)
3. pyproject.toml (under [tool.complexipy] section)

# complexipy.toml or .complexipy.toml
paths = ["src", "tests"]
max-complexity-allowed = 10
quiet = false
ignore-complexity = false
details = "normal"
sort = "asc"
exclude = []

[output]
csv = true
json = true

# pyproject.toml
[tool.complexipy]
paths = ["src", "tests"]
max-complexity-allowed = 10
quiet = false
ignore-complexity = false
details = "normal"
sort = "asc"
exclude = []

[tool.complexipy.output]
csv = true
json = true

Example:

# Exclude only top-level 'tests' directory under the provided root
complexipy . --exclude tests
# This will not exclude './complexipy/utils.py' if you pass '--exclude utils' at repo root,
# because there is no './utils' directory or file at that level.

You can explicitly ignore a known complex function inline, similar to Ruff's C901 ignores:

def legacy_adapter(x, y):  # noqa: complexipy (safe wrapper)
    if x and y:
        return x + y
    return 0

Place # noqa: complexipy on the function definition line (or the line immediately above). An optional reason can be provided in parentheses or plain text, it’s ignored by the parser.

# Core functions
file_complexity(path: str) -> FileComplexity
code_complexity(source: str) -> CodeComplexity

# Return types
FileComplexity:
  ├─ path: str
  ├─ complexity: int  
  └─ functions: List[FunctionComplexity]

FunctionComplexity:
  ├─ name: str
  ├─ complexity: int
  ├─ line_start: int
  └─ line_end: int