API reference

BenchCore exposes a deliberately small root API for the most common operation:

from benchcore import Bench, benchmark

More specialized symbols are imported from the package that owns their responsibility.

benchcore.core.models

Symbol Purpose
BenchmarkConfig Immutable execution and calibration configuration
RoundResult One measured round in nanoseconds
BenchmarkResult[R] Typed callable value, rounds, and statistics
BenchmarkStatistics Unit-explicit descriptive statistics
BenchmarkEnvironment Python and platform identity
BenchmarkReport Portable report without arbitrary return values
RegressionThreshold Relative and absolute comparison tolerance
BenchmarkComparison Typed baseline/current comparison
ComparisonStatus Improvement, stable, or regression
IncompatibleReportsError Incompatible report identity/environment
SCHEMA_VERSION Current portable report schema

benchcore.core.protocols

Symbol Contract
Timer Callable returning integer nanoseconds
Reporter Renders a BenchmarkReport
ComparisonReporter Renders a BenchmarkComparison
ReportStorage Saves and loads reports by canonical name

benchcore.engine

  • Bench
  • BenchmarkRunner
  • benchmark()
  • benchmarked()
  • calculate_statistics()

All callable-taking APIs preserve parameters and return types.

benchcore.reporting

  • capture_environment()
  • create_report()
  • format_duration_ns()
  • serialize_report() and deserialize_report()
  • TerminalReporter and JsonReporter

benchcore.comparison

  • compare_reports()
  • ComparisonTerminalReporter
  • ComparisonJsonReporter
  • Comparison models and Protocol re-exported for cohesive use

benchcore.storage

  • JsonFileStorage
  • ReportStorage

benchcore.integrations

  • benchcore.integrations.pytest.BenchCoreFixture
  • benchcore.integrations.unittest.BenchCoreTestCase