complexipy

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

Installation • Quick Start • Features • Integrations • Learn More • Complexipy Teams

Scoring cognitive complexity of the Django codebase (2,929 files). Benchmarks

Installation

uv tooluv addpip

uv tool install complexipy

uv add complexipy

pip install complexipy

Git for the diff options

The --diff, --diff-only, and --staged options require Git 2.30 or newer on your PATH. Check your version with git --version. Git is not required for analysis without these options.

What is Cognitive Complexity?

Cognitive complexity measures how hard a function's control flow is to follow. Use it to keep code easy to review and change, whether a person or an AI agent wrote it.

These two functions have the same cyclomatic complexity, 4. Their cognitive complexity is different:

Flat: score 3Nested: score 6

def example1(a, b, c):
    if a:        # +1
        return 1
    if b:        # +1
        return 2
    if c:        # +1
        return 3
    return 4

def example2(a, b, c):
    if a:        # +1
        if b:    # +2 (1 + nesting_level)
            if c:  # +3 (1 + nesting_level)
                return 1
    return 4

Nested code makes the reader hold more context, so each nesting level adds to the score. complexipy implements the Cognitive Complexity metric by G. Ann Campbell for Python. How scores are calculated

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")
print(f"File complexity: {result.complexity}")

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

Features

• Cognitive complexity scores

  ---

  Scores that follow G. Ann Campbell's paper: nesting, flow breaks, and boolean sequences.

  How scores work

• Gate only what a change makes worse

  ---

  --diff and --staged compare each function with a git reference.

  Complexity diff

• Snapshot baselines

  ---

  Record the current state of an existing codebase, then fail only on new or worse functions.

  Snapshots

• Refactor suggestions and --fix

  ---

  Rules such as guard clauses and extract helper, and automatic fixes where they are safe.

  Refactoring rules

• Output formats

  ---

  JSON, CSV, SARIF for GitHub code scanning, and GitLab Code Quality.

  Output formats

• Language server

  ---

  Inlay hints, hover, and warnings in VS Code, Neovim, and Zed.

  Editor integration

• GitHub Action and pre-commit hook

  ---

  Run the same gate in CI and before each commit.

  CI/CD integration

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.

Integrations

GitHub ActionsPre-commit HookEditors

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

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

Every editor uses complexipy lsp, a language server with inlay hints, hover, and warnings that update as you type. Install complexipy first (uv tool install complexipy).

For VS Code, install the extension from the Visual Studio Marketplace or OpenVSX. For Neovim and Zed, see Editor Integration.

Learn More

• Usage Guide - installation, the basic CLI workflow, and troubleshooting
• Adopting in an Existing Codebase - baseline, gate new code, then lower the threshold
• Configuration - configuration files and the cache
• Diff and Snapshots - complexity diff and snapshot baselines
• Ignores and Rule Selection - inline ignores and rule selection
• CLI Options - every CLI flag
• 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

---

_{Inspired by the Cognitive Complexity research by G. Ann Campbell}

_{complexipy is an independent project and is not affiliated with or endorsed by SonarSource}

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