A static analysis tool that detects complexity patterns in Python code and assigns numeric scores.

The analyzer detects and scores multiple complexity dimensions:

• Cyclomatic Complexity: Branches, loops, boolean operators, comprehensions (+1-3 each)
• Concurrency Complexity: Threading, multiprocessing, async/await (+2-5 each)
• Data Flow Complexity: Global/nonlocal variables, mutable default arguments (+5-7 each)
• Nesting Complexity: Deep nesting penalties (+5 per level beyond depth 3)
• Error Handling: Try/except blocks, bare except clauses (+2-10 each)
• Dynamic Behavior: eval/exec, getattr/setattr (+5-20 each)

Basic analysis:

python cli.py script.py

Detailed breakdown with line numbers:

python cli.py script.py --verbose

JSON output:

python cli.py script.py --json

Interactive HTML report:

python cli.py script.py --html report.html

Set complexity threshold (exits with error if exceeded):

python cli.py script.py --threshold 50

Analyze all Python files in a directory:

python cli.py src/

Show summary with top 10 most complex files:

python cli.py src/ --summary-only

Analyze with verbose breakdown for each file:

python cli.py src/ --verbose

Generate interactive HTML report:

python cli.py src/ --html report.html

Limit traversal depth:

python cli.py . --max-depth 2

Exclude additional patterns (beyond default exclusions):

python cli.py . --exclude tests --exclude experimental

Analyze only specific file patterns:

python cli.py . --file-pattern "test_*.py"

Set threshold for total directory complexity:

python cli.py src/ --threshold 500

The analyzer can generate interactive HTML reports with visual complexity breakdowns:

python cli.py src/ --html report.html

HTML reports feature:

• Interactive visualization: Stacked bar charts showing complexity breakdown by category
• Drill-down capability: Click on any file/function to expand and see line-level details
• Color-coded categories: Each complexity type has a distinct color for easy identification
• Summary statistics: Overview of total files, scores, and averages
• Self-contained: Single HTML file with embedded CSS and JavaScript, no external dependencies
• Mobile-friendly: Responsive design that works on all screen sizes

For more granular analysis, use the --function-level flag to generate a flat list of all functions sorted by complexity:

python cli.py src/ --html report.html --function-level

Function-level reports show:

• All functions from all files in one sortable list
• Qualified names with > for nested functions (e.g., outer>inner)
• Class methods shown as ClassName.method_name
• Module-level code shown as <module-level>
• File path and starting line number for each function
• Individual complexity breakdown per function

This view is ideal for:

• Identifying the most complex functions across your entire codebase
• Prioritizing refactoring efforts
• Understanding where complexity is concentrated

The HTML output provides a much more readable and explorable view of complexity, especially useful for:

• Code reviews and team discussions
• Identifying hotspots in large codebases
• Tracking complexity trends over time
• Presenting analysis results to stakeholders

When analyzing directories, the following patterns are automatically excluded:

• .venv/, venv/ - Virtual environments
• __pycache__/ - Python cache directories
• .git/, .tox/ - Version control and testing
• .pytest_cache/, .mypy_cache/, .ruff_cache/ - Tool caches
• node_modules/, .eggs/, *.egg-info/ - Package artifacts
• build/, dist/ - Build artifacts

Complexity Analysis: sample_code.py
======================================================================

Total Complexity Score: 93

Breakdown by Category:
----------------------------------------------------------------------

CONCURRENCY: 26 points (8 occurrences)
ERROR_HANDLING: 16 points (3 occurrences)
DATA_FLOW: 15 points (3 occurrences)
NESTING: 15 points (2 occurrences)
CYCLOMATIC: 11 points (11 occurrences)
DYNAMIC_BEHAVIOR: 10 points (2 occurrences)

Scores are based on established research and heuristics:

• Cyclomatic complexity: Research-backed (McCabe, 1976). Comprehensions with multiple generators count like nested loops.
• Nesting depth: Empirical studies showing >3-4 levels problematic (baseline: depth 3)
• Concurrency patterns: Heuristic based on known bug patterns
• Data flow: Globals (+5), nonlocals (+7), mutable defaults (+7) due to shared state issues
• Dynamic behavior: High scores for eval/exec due to security and maintainability
• Mutable defaults: Well-documented Python anti-pattern causing unexpected shared state

• Data-driven score calibration from bug correlation analysis
• Per-function granularity in reports
• Custom scoring configuration via config file
• Integration with CI/CD pipelines
• Parallel file processing for large directories
• Configuration file support (.complexity.toml)
• Trend tracking and historical comparison
• Export to other formats (CSV, XML)