complexipy

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

Installation • Quick Start • Integrations • Learn More • Documentation • Changelog • Complexipy Teams

What is Cognitive Complexity?

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

Unlike traditional metrics like cyclomatic complexity, cognitive complexity accounts for nesting depth and control flow patterns that affect human comprehension. Inspired by G. Ann Campbell's research at SonarSource, complexipy provides a fast, accurate implementation for Python.

Key benefits:

• Human-focused - Penalizes nesting, flow breaks, and human-unfriendly logic
• Actionable insights - Identifies genuinely hard-to-maintain code
• Different from cyclomatic - Measures readability while cyclomatic measures structural, testing, and branch density

Common Questions

How is complexity calculated? Learn about the scoring algorithm, what each control structure contributes, and how nesting affects the final score.

How does this compare to Ruff's PLR0912? Understand the key differences between cyclomatic complexity (Ruff) and cognitive complexity (complexipy), and why you might want to use both.

Is this a SonarSource/Sonar product? No. complexipy is an independent project inspired by G. Ann Campbell's research, but it's not affiliated with or endorsed by SonarSource.

Installation

pip install complexipy
# or
uv add complexipy

Quick Start

Command Line

# Analyze the current directory
complexipy .

# Set a custom threshold
complexipy . --max-complexity-allowed 10

# Show failing functions with refactor suggestions
complexipy . --failed --suggest-refactors

# Save results to JSON
complexipy . --output-format json

# Block regressions against a git reference
complexipy . --diff main

# Exclude paths with glob patterns
complexipy . --exclude "tests/**"

Python API

from complexipy import file_complexity

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

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

Integrations

- uses: rohaquinlop/complexipy-action@v2
  with:
      paths: .
      max_complexity_allowed: 10
      output_format: json

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

Learn More

• Usage Guide - every CLI flag, configuration files, snapshots, complexity diff, and inline ignores
• Editor Integration - the language server, inlay hints, and the VS Code, Neovim, and Zed setup
• API Reference - the complete Python API
• Understanding Scores - how the scoring algorithm works
• Comparison with Ruff - cognitive vs cyclomatic complexity
• Refactoring Rules - the rules behind --suggest-refactors
• Changelog - what changed in each release