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

🔧 GitHub Actions

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

🪝 Pre-commit Hook

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

🔌 VS Code Extension

Install from the marketplace for real-time complexity analysis with visual indicators.

Learn More

• Usage Guide - every CLI flag, configuration files, snapshots, complexity diff, and inline ignores
• 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

---

_{Inspired by the Cognitive Complexity research by G. Ann Campbell
complexipy is an independent project and is not affiliated with or endorsed by SonarSource}

Documentation • PyPI • GitHub

_{Built with ❤️ by @rohaquinlop and contributors}