クイックスタート
このページでは、単一のソースファイルからメトリクスを計算するために必要な最小限のコードを順に説明します。
1. パッケージをインストールする
pip install big-code-analysis
wheel マトリクスとソースからのビルド手順についてはインストールを参照してください。
2. ファイルを分析する
bca.analyze(path) は、同じファイルに対して bca metrics --format json が出力する JSON と一致する dict を返します — フィールドの順序も、数値の書式も、構造も同じです。
"""Quick-start: analyse one file and print the headline cyclomatic count.
Mirrors the worked example shown on the book's
``python/quick-start.md`` page. The book embeds this file verbatim,
so the snippet is the test fixture — if the API drifts, the
``test_book_examples.py`` test fails and the docs are forced back
into sync.
"""
from __future__ import annotations
from pathlib import Path
import big_code_analysis as bca
from big_code_analysis import FuncSpaceDict
def run(path: Path) -> FuncSpaceDict:
"""Analyse ``path`` and return its metric dict."""
result = bca.analyze(path)
if result is None:
msg = f"{path} was skipped (empty, binary, or generated)"
raise SystemExit(msg)
cyclomatic = result["metrics"]["cyclomatic"]
print(f"{result['name']}: cyclomatic sum = {cyclomatic['sum']:.0f}")
return result
if __name__ == "__main__":
import sys
if len(sys.argv) != 2:
sys.exit("usage: python quick_start.py <path>")
run(Path(sys.argv[1]))
注目すべき点をいくつか挙げます。
analyzeは、CLI のウォーカーがスキップするファイルに対してNoneを返します。具体的には、3 バイト以下のファイル（空として扱われます）、先頭部分が有効な UTF-8 でないファイル（バイナリとして扱われます）、そしてデフォルトのskip_generated=Trueの下でウォーカーのis_generated述語に一致するファイル（先頭に@generated、DO NOT EDIT、GENERATED CODEのいずれかのマーカーがあるもの）です。result["metrics"]の中身にアクセスする前に、必ずこのオプショナルな戻り値を処理してください。- 返されるオブジェクトは、実行時にはただの dict です —
json.dumpsでシリアライズしたり、下流のサービスに送ったり、表形式のコンシューマー向けにflatten_spacesに渡したりしても安全です。型チェッカーからは（Rust のワイヤ形状から生成された）FuncSpaceDictという TypedDict として見えるため、ネストしたメトリクスへのアクセスはキャストなしで mypy/pyright の静的チェックを通ります。 - 言語検出は CLI と完全に同じ挙動です。まずパスの拡張子を見て、次にシバン / emacs モード行にフォールバックします。ソースをメモリ上に持っている場合は
bca.analyze_source(code, language)を使ってください。
3. メモリ上のスニペットを分析する
import big_code_analysis as bca
metrics = bca.analyze_source("fn main() {}\n", "rust")
print(metrics["metrics"]["loc"]["sloc"])
analyze_source は str、bytes、bytearray を受け付けます。返される dict は analyze の出力と同じ構造で、name は None になります（メモリ上のバッファにはパスが関連付けられないためです）。