mccabe

mccabe is Ned Batchelder’s script for measuring the McCabe (cyclomatic) complexity of Python code. It walks a module’s abstract syntax tree, builds a control-flow path graph for each function, and reports functions whose complexity exceeds a configurable threshold.

It can run as a standalone command via python -m mccabe, or act as a plugin for Flake8, where the --max-complexity switch enables a C901 warning for over-complex functions. Because high cyclomatic complexity correlates with hard-to-test, hard-to-maintain code, mccabe is a common part of Python linting setups.

What You Get

• A standalone python -m mccabe command that reports the complexity of each function in a module
• A Flake8 plugin exposing the --max-complexity option and the C901 warning code
• Configurable minimum/maximum complexity thresholds
• An optional Graphviz dot output of the computed control-flow path graph
• A small, dependency-light implementation that integrates into existing linting pipelines

Common Use Cases

• Failing CI when a function’s cyclomatic complexity exceeds an agreed threshold via Flake8
• Auditing a codebase to find the most complex, refactor-worthy functions
• Enforcing a team complexity budget as part of pre-commit or lint checks
• Visualizing a function’s control-flow path graph for analysis

Under The Hood

Architecture The whole tool lives in a single 349-line mccabe.py. A PathGraphingAstVisitor walks the Python AST, and for each function builds a PathGraph whose nodes and edges model control-flow branches (if, for, while, try/except); the cyclomatic number is derived from the graph’s edge and node counts. A McCabeChecker class provides the Flake8 entry point (C901), while get_code_complexity and main drive the standalone python -m mccabe command. Tech Stack Pure Python using only the standard-library ast and optparse modules with no third-party runtime dependencies, packaged via setup.py/setup.cfg and tested across interpreters with tox. Code Quality The repo ships a focused test_mccabe.py covering the visitor and complexity calculations, uses tox for multi-version CI, and is maintained under the PyCQA umbrella; the code is compact and readable though intentionally narrow in scope. API Design Usage is minimal and well documented: enable it in Flake8 with a single --max-complexity flag, or run the module directly with --min to list complexities, making adoption trivial for anyone already linting Python.