About complexipy¶

Origins and Inspiration¶

complexipy is inspired by the Cognitive Complexity research paper by G. Ann Campbell from SonarSource. This groundbreaking work introduced a new approach to measuring code complexity that better aligns with human understanding.

Independent Project

While complexipy implements the cognitive complexity methodology described in Campbell's research, it is not affiliated with or endorsed by SonarSource or Sonar products. complexipy is an independent, open-source implementation written in Rust for Python code analysis.

Why Cognitive Complexity?¶

Cyclomatic complexity measures code structural, testing, and branch density (number of paths) by counting decision points. However, this doesn't reflect how humans actually understand code. Cognitive complexity measures how difficult code is for humans to understand and maintain by penalizing nesting, flow breaks, and human-unfriendly logic.

Different Approaches to Measuring Complexity¶

Cyclomatic complexity (McCabe, 1976) counts every decision point:

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

# Cyclomatic complexity: 4 (same as above!)
def example2(a, b, c):
    if a:
        if b:
            if c:
                return 1
    return 4

Both functions have the same cyclomatic complexity, but any developer will tell you example2 is much harder to understand.

The Cognitive Complexity Solution¶

Cognitive complexity accounts for nesting:

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

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

This aligns with human intuition: nested code requires holding more context in your mind.

Project Goals¶

Performance - Blazingly fast analysis using Rust
Accuracy - Faithful implementation of cognitive complexity principles
Accessibility - Easy integration with Python development workflows
Actionability - Clear, actionable insights for improving code quality

The Team¶

complexipy is built with ❤️ by @rohaquinlop and contributors.

License¶

complexipy is released under the MIT License.