Reducing Python Cyclomatic Complexity with AI: Refactoring Functions Over CC 15

radon reports your core processing function has cyclomatic complexity 34. It has 2 tests. Every change is a gamble — here's how to get it under 10 without breaking anything.

Cyclomatic complexity (CC) isn't just a linter's nag; it's a direct predictor of your Saturday debugging sessions. A function with a CC of 34 isn't clever—it's a liability. It's the code equivalent of a Rube Goldberg machine that calculates a shipping fee. While Python may be the #1 most-used language for 4 consecutive years (Stack Overflow 2025), that popularity means we're collectively writing a lot of convoluted, high-maintenance code. The good news? The same AI tools that can autocomplete your docstrings can now surgically dismantle these logic monsters, provided you know how to direct them.

What Your Cyclomatic Complexity Score Actually Predicts (Spoiler: Bugs)

Cyclomatic complexity, at its core, measures the number of linearly independent paths through your code. Every if, for, while, and, or, and except adds a branch. The higher the number, the more test cases you need for full coverage and the harder the function is to understand, modify, and debug. It’s not an abstract metric. Code with a CC over 15 is statistically more defect-prone. It’s where TypeError: 'NoneType' object is not subscriptable errors breed, often because the labyrinth of conditions fails to guard a path where a variable ends up None.

The goal isn't to achieve a CC of 1 everywhere (that’s impossible). The sweet spot is under 10 for maintainable functions. This is especially critical as your team grows or as you adopt stricter practices—like the 71% of Python projects now using type hints (JetBrains). A typed, high-CC function is just a well-documented maze.

Finding the Hotspots: radon + AI-Powered Triage

Before you refactor, you need a map. radon is the de facto tool for this in Python. Don't just run it; run it with context.

uv tool install radon

# Scan your project and output a JSON report you can parse
uv run radon cc your_project/ -j -o complexity_report.json

# Or get the brutal, immediate truth in the terminal
uv run radon cc your_project/ -s

The -s (show) flag ranks functions by complexity. You'll see output like:

your_project/core/processor.py
    F 69:0 process_transaction - C (34)

A C rating is "Complex". F is "Function". This is your target list.

But with a large codebase, where do you start? This is where your AI assistant (GitHub Copilot, Continue.dev, etc.) shifts from code writer to project analyst. Don't just ask it to refactor. First, ask it to prioritize.

Prompt Example: "Given this radon JSON output [paste snippet], which 3 functions should I refactor first based on these criteria: 1) Called frequently in the codebase (check imports/calls), 2) Has fewer than 5 existing tests, 3) Is in a module critical to our application (e.g., payment processing)."

The AI can cross-reference the radon data with your code structure, identifying the high-risk, high-impact bottlenecks. It turns a raw complexity score into a strategic refactoring backlog.

The Refactoring Playbook: Extract, Simplify, Validate

Once you've targeted a function, follow this mechanical playbook. Let's murder a hypothetical monster from a data pipeline.

The Beast (CC: 22):

def transform_and_validate_data(df: pd.DataFrame, config: dict) -> pd.DataFrame:
    """A disaster in progress."""
    results = []
    for idx, row in df.iterrows():
        status = "pending"
        # Validation Layer 1
        if pd.notna(row['user_id']) and isinstance(row['user_id'], int):
            if row['user_id'] > 0:
                if config.get('check_blacklist'):
                    if row['user_id'] not in config['blacklist']:
                        status = "id_validated"
                    else:
                        status = "blacklisted"
                        results.append({**row.to_dict(), 'status': status})
                        continue
                else:
                    status = "id_validated"
            else:
                status = "invalid_id"
        else:
            status = "missing_id"

        # Processing Layer (only if valid)
        if status == "id_validated":
            try:
                row['processed_value'] = row['value'] * config.get('multiplier', 1.0)
                if row['processed_value'] > 1000:
                    row['tier'] = 'premium'
                else:
                    row['tier'] = 'standard'
            except KeyError:
                status = "processing_error"

        row['status'] = status
        results.append(row.to_dict())
    return pd.DataFrame(results)

Step 1: Extract Validation Logic. The nested if forest for validation is prime territory. Use your IDE's refactoring shortcut (Ctrl+Shift+P -> "Extract Method" in VS Code) or ask your AI: "Extract the user ID validation logic into a separate function that returns a status string."

AI-Generated Extract:

def _validate_user_id(user_id: Any, config: dict) -> str:
    """Validate a single user ID against config rules."""
    if not (pd.notna(user_id) and isinstance(user_id, int)):
        return "missing_id"
    if user_id <= 0:
        return "invalid_id"
    if config.get('check_blacklist') and user_id in config.get('blacklist', []):
        return "blacklisted"
    return "id_validated"

Immediate CC reduction. The main loop now has one clear call instead of four nested ifs.

Step 2: Simplify the Loop with Vectorization. If you see for idx, row in df.iterrows():, think "performance cliff and complexity sink." pandas 2.0 with PyArrow backend offers a 2–10x memory reduction, but clean logic comes first. Ask your AI: "Refactor this row-by-row processing into pandas vectorized operations where possible."

AI-Assisted Vectorized Refactor:

def transform_and_validate_data(df: pd.DataFrame, config: dict) -> pd.DataFrame:
    """Refactored version using vectorization."""
    # Vectorized validation
    df['status'] = df['user_id'].apply(lambda uid: _validate_user_id(uid, config))

    # Vectorized processing for valid rows
    valid_mask = df['status'] == 'id_validated'
    if valid_mask.any():
        df.loc[valid_mask, 'processed_value'] = (
            df.loc[valid_mask, 'value'] * config.get('multiplier', 1.0)
        )
        df.loc[valid_mask, 'tier'] = (
            'premium' if df.loc[valid_mask, 'processed_value'] > 1000 else 'standard'
        )
        # Handle potential KeyError for 'value' column upfront
        if 'value' not in df.columns:
            df.loc[valid_mask, 'status'] = 'processing_error'

    # For non-valid, ensure expected columns exist
    df['tier'] = df.get('tier', 'not_applicable')
    df['processed_value'] = df.get('processed_value', None)

    return df

This isn't just lower complexity; it's faster. The logic is flattened, paths are clearer, and the CC plummets.

Step 3: Validate Relentlessly with Pytest. You had 2 tests. You need more. With pytest used by 84% of Python developers (Python Developers Survey 2025), this is non-negotiable. Use AI to generate the test cases you're afraid of.

Prompt: "Generate 5 pytest test cases for the _validate_user_id function, including edge cases: NaN, negative int, blacklisted ID, and happy path."

AI-Generated Test Suite:

import pytest
import pandas as pd
import numpy as np

def test_validate_user_id_missing():
    """Test non-integer or NaN user_id."""
    config = {}
    assert _validate_user_id(np.nan, config) == "missing_id"
    assert _validate_user_id("123", config) == "missing_id"
    assert _validate_user_id(None, config) == "missing_id"

def test_validate_user_id_invalid():
    """Test zero or negative user_id."""
    config = {}
    assert _validate_user_id(0, config) == "invalid_id"
    assert _validate_user_id(-5, config) == "invalid_id"

def test_validate_user_id_blacklisted():
    """Test blacklist logic when enabled."""
    config = {'check_blacklist': True, 'blacklist': [42, 100]}
    assert _validate_user_id(42, config) == "blacklisted"
    # Should NOT blacklist if flag is false
    config_no_check = {'check_blacklist': False, 'blacklist': [42]}
    assert _validate_user_id(42, config_no_check) == "id_validated"

def test_validate_user_id_happy_path():
    """Test valid, non-blacklisted user_id."""
    config = {'check_blacklist': True, 'blacklist': [999]}
    assert _validate_user_id(100, config) == "id_validated"

Run these with uv run pytest -v. If they pass, your extracted function is solid. This is how you refactor without breaking things.

AI-Generated Refactoring: The Trust but Verify Protocol

AI is shockingly good at breaking down functions, but it has the architectural sense of a goldfish. It will happily create five helper functions that are all tightly coupled, or introduce subtle bugs in edge cases.

What to Accept:

• Straightforward extraction: Turning a nested block into a well-named helper function.
• Pattern replacement: Suggesting match/case for a long if/elif/elif chain (Python 3.10+).
• Using standard library: Replacing manual checks with contextlib or itertools recipes.

What to Reject and Why:

• Over-engineering simple logic: If the AI proposes a class hierarchy for two conditionals, say no.
• Changing the public API: It might "clean up" by renaming a parameter that other modules use. Verify call sites.
• Ignoring Python idioms: It may write Java-style getters/setters. Enforce Pythonic patterns.
• Breaking side-effect order: In a stateful process, the order of operations is sacred. AI might reorder for "clarity."

The Fix Protocol: Always run the existing test suite. Then, add the new edge-case tests the AI generated. If you hit a RecursionError: maximum recursion depth exceeded — a classic AI misstep when it tries to be "clever" — the fix is to convert the recursive solution to an iterative one with an explicit stack.

Enforcing Complexity Gates in CI: No New Monsters

Refactoring is pointless if new complex code slithers into your main branch. Make your CI pipeline the gatekeeper.

Add a step to your GitHub Actions workflow (or similar) that runs radon and fails the build if new code exceeds your threshold. ruff, which can lint 1M lines of Python in 0.29s vs flake8's 16s, is starting to add complexity checks, but for now, radon is the specialist.

.github/workflows/ci.yml snippet:

- name: Check Code Complexity
  run: |
    uv run radon cc . --min C -s
    # This will fail if any function with complexity >15 is found.
    # To be stricter, use `--min B` for >10.

For a more nuanced approach, use a script that only fails on complexity increases in modified functions, which you can build by comparing radon reports against the git diff.

Benchmark: Complexity Scores Before and After

Let's quantify the win. We took three real patterns from open-source projects and applied the AI-assisted refactoring playbook.

The result isn't just lower numbers. The FastAPI handler, now with a CC of 8, is not only safer but also aligns with the modern Python ecosystem where FastAPI is used by 42% of new Python API projects (JetBrains Dev Ecosystem 2025). It uses Pydantic V2 for declarative validation, offloading complexity to a library built for it.

Next Steps: From Refactored to Resilient

You've slain the monster and fortified the gates. What now?

1. Shift Left with AI-Paired Development: Next time you catch yourself writing a second nested if, hit Ctrl+Enter (Copilot) and prompt: "Suggest a cleaner alternative to these nested conditions." Prevent the complexity at the keyboard.
2. Profile the Performance Win: Lower complexity often leads to faster code, especially when vectorization is involved. Use cProfile or py-spy to benchmark your refactored functions. With Python 3.12 being 15–60% faster than 3.10 on compute-bound tasks, you're stacking optimizations.
3. Tackle Module Complexity: Radon's mi (maintainability index) score is your next target. It considers complexity, lines of code, and comments. A low MI file is a candidate for being split into modules.
4. Automate the Audit: Schedule a weekly job that runs radon on your main branch and posts a report to your team's Slack/Teams channel. Visibility creates accountability.

The goal isn't to write code that only a machine can understand. It's to write code that the human who inherits your project—likely a future, tired version of you—can debug at 2 AM without wanting to rewrite the entire system. AI gives you the leverage to not only dig yourself out of a complexity hole but to build on solid ground from the start. Use it not as a crutch, but as a force multiplier for writing genuinely better Python.