Python バインディング

big-code-analysis ships first-party Python bindings, built with PyO3 and maturin, that expose the same metric pipeline as the Rust library and the bca CLI: same JSON shape, same numeric formatting, same language coverage. This chapter is for a Python developer deciding whether to use the bindings and then finding the page for each workflow.

import big_code_analysis as bca

result = bca.analyze("src/main.rs")
if result is not None:
    print(result["metrics"]["cyclomatic"]["sum"])

The bindings cover the analysis workflows: file and in-memory analysis (big_code_analysis::analyze), the FuncSpace result as a typed dict, metric selection, AST traversal, SARIF output, and the VCS metrics. The metrics are computed by the same Rust code, so the numbers are identical. Python also exposes the language-detection helpers. Some lower-level Rust facilities, including the C preprocessor pass and the output writers, have no Python counterpart. Pick whichever language fits your pipeline.

Python を選ぶべき場面

• You work in a data-pipeline stack (pandas, Jupyter, Airflow, dbt, Polars) and want metric records as dict or DataFrame rows without shelling out to the CLI.
• You integrate with a Python-native security tool that consumes SARIF; see SARIF output.
• You build a code-quality dashboard on a Python web framework (FastAPI, Django).

If you only need a one-shot quality report from the command line, the bca CLI is the simpler tool; see Commands → Metrics.

If you embed the analysis in a long-running Rust program, the Rust library has lower overhead.

本章の内容

• Installation: pip install, the wheel matrix, building from source.
• Quick start: analyse one file, print one metric.
• Batch processing: analyze_batch, AnalysisFailure, parallelism with ThreadPoolExecutor.
• Flat-record iteration: flatten_spaces feeding SQLite or pandas.
• Metric selection: the metrics= kwarg, bca.METRIC_NAMES and the CLI aliases, dependency-pull semantics.
• AST traversal: Ast, Node, walk(), and find() over the held parse.
• SARIF output: to_sarif and the GitHub Code Scanning upload.
• Change-history (VCS) metrics: vcs.rank, vcs.trend, vcs.commit, and vcs.score_diff over a git working tree.
• Error handling: the full exception taxonomy and the never-raise batch contract.
• Async patterns: asyncio.to_thread as the canonical recipe.

The headline example on each page is embedded verbatim from an importable file under big-code-analysis-py/examples/ and run end-to-end by big-code-analysis-py/tests/test_book_examples.py, so a renamed kwarg or a removed function on the primary path fails CI before it can rot the docs. The shorter snippets around each embedded example (logging recipes, regex parsing of the errno suffix, the asyncio anti-pattern, the pandas one-liner) are inline and deliberately not test-pinned. Treat the embedded blocks as the canonical reference when the two disagree.