API Reference¶
This reference is intentionally narrow: it follows the package's public exports and works best alongside the guide pages.
If you are trying to use Pymetrica from the command line, start with CLI Reference. If you are trying to understand the analysis model, read Architecture and Metrics first.
Using Pymetrica From Python¶
The CLI and the Python API share the same parser, calculators, and report registry. A typical programmatic workflow is:
```python from pymetrica.codebase_parser import parse_codebase from pymetrica.metric_calculators import ( AlocCalculator, BaseStatsCalculator, CCCalculator, HalsteadVolumeCalculator, InstabilityCalculator, MaintainabilityCostCalculator, PrimitiveObsessionCalculator, ) from pymetrica.metric_calculators.base_stats import create_diagram from pymetrica.report_generators import REPORTS_MAPPING from pymetrica.utils.settings import update_config_from_pyproject
project_path = "path/to/project" update_config_from_pyproject(project_path) codebase = parse_codebase(project_path)
metrics = [ BaseStatsCalculator().calculate_metric(codebase), AlocCalculator().calculate_metric(codebase), CCCalculator().calculate_metric(codebase), HalsteadVolumeCalculator().calculate_metric(codebase), PrimitiveObsessionCalculator().calculate_metric(codebase), MaintainabilityCostCalculator().calculate_metric(codebase), InstabilityCalculator().calculate_metric(codebase), ]
report_generator = REPORTS_MAPPING"BASIC_TERMINAL" print(report_generator.long_report().content)
create_diagram(codebase, filename="architecture.mmd") ```
CLI commands load configuration automatically. Library callers should invoke
update_config_from_pyproject() before parse_codebase() when they want the
target project's thresholds and exclusions. Without that call, parsing uses the
current in-process Config values.
Extension Points¶
The most useful public extension points are:
MetricCalculatorsubclasses for adding new metricsReportGeneratorsubclasses for adding new report backendsREPORTS_MAPPINGfor registering report backends under-rtnames
Bundled report backends are BASIC_TERMINAL for terminal output, BASIC_HOOK
for pre-commit style output that only shows failed metrics and returns
threshold-based exit statuses, and JSON for informational machine-readable
output. Instantiate a backend with a metric sequence and then call its
short_report() or long_report() method.
Models¶
The models package contains the core data structures and abstract base types
used throughout the project. CodebaseStats is the parser-statistics subset
shared by Codebase and Base Stats results. The package also exports the
validated aliases StrPath, StrRatio, and NonNegativeInt.
models
¶
Codebase Parser¶
The codebase_parser package exposes parse_codebase, the main parser
entrypoint. Diagram generation belongs to
pymetrica.metric_calculators.base_stats.
codebase_parser
¶
Metric Calculators¶
The metric_calculators package re-exports the calculator classes and CLI
callables for the supported metrics. It also re-exports selected result types;
more detailed result and layer models live in each metric's submodule.
BaseStatsCalculator produces the informational metric included at the start of
run-all.
metric_calculators
¶
Report Generators¶
The report layer is small today. REPORTS_MAPPING is the registry used by the
CLI. It includes the normal terminal backend, the hook-oriented backend used by
the published pre-commit hooks, and the optional JSON backend.
BasicTerminalReport, BasicHookReport, and JsonReport are exported directly
from this package.
report_generators
¶
Utilities¶
The utils package exposes configuration loading, logging, and profiler
helpers.