API reference

Everything public is importable from the top-level codecaliper package. All result types are frozen, slotted dataclasses: immutable, clock-free, serialized deterministically. The entry points:

from codecaliper import measure, measure_file, Session

Session is a validated, reusable option set: metrics, feature sets, granularity, cognitive mode, explain and strict, checked once in __init__ (an unknown metric or mode raises CodecaliperError there rather than at the first file), then applied to every call. measure and measure_file take the same keywords and build a throwaway Session per call, so measuring a corpus one file at a time revalidates the same options once per file. Use a Session when you are measuring more than one thing under one configuration.

Grammar loading is not what a Session buys you. Adapters (and the tree-sitter parser each one lazily loads) are cached process-wide by a functools.cache on get_adapter, so the second plain measure() call reuses the same adapter object the first one loaded, with or without a Session. A Session carries no instance-level cache.

Measuring

codecaliper.api.Session

An option set validated once and applied to every call: the corpus-scale entry point (deterministic sequential order; parallelism is a 1.x item). Adapters and their parsers are cached process-wide by get_adapter, not per Session, so a plain measure() reuses them too.

codecaliper.measure(source, *, language, metrics=None, readability=('bw2010',), granularity='file', cognitive_mode='whitepaper', explain=False, strict=False)

codecaliper.measure_file(path, *, language=None, **kwargs)

Results

codecaliper.model.FileReport dataclass

codecaliper.model.FunctionReport dataclass

codecaliper.model.MetricValue dataclass

codecaliper.model.FeatureVectorResult dataclass

A raw feature vector, never a score (ARCHITECTURE.md §7/§13).

codecaliper.model.Diagnostic dataclass

codecaliper.model.Provenance dataclass

codecaliper.model.GrammarInfo dataclass

codecaliper.model.Span dataclass

1-based line numbers, 0-based columns (editor convention).

Spec introspection

The mapping specification ships as package data and is queryable at runtime. The CLI's spec show is a thin wrapper over these:

codecaliper.spec.spec_version() cached

codecaliper.spec.ruling(ruling_id)

codecaliper.spec.iter_rulings(metric=None, language=None)

codecaliper.spec.Ruling dataclass

Errors

codecaliper.errors

Typed error taxonomy. Nothing else escapes the public facade.

CodecaliperError

Bases: Exception

Base class for all codecaliper errors.

GrammarLoadError

Bases: CodecaliperError

A tree-sitter grammar wheel could not be imported or wrapped.

LanguageDetectionError

Bases: CodecaliperError

--lang auto could not map the file extension; never guess (spec CORE-ALL-0005).

UnsupportedLanguageError

Bases: CodecaliperError

The requested language has no registered adapter.

StrictParseError

Bases: CodecaliperError

--strict was set and the parse tree contains ERROR/MISSING nodes (CORE-ALL-0002).

SpecError

Bases: CodecaliperError

The ruling registry is unreadable, or code cited a phantom ruling ID.