API Reference

Quick map

Area	What you get	Docs
Decorators & suites	bench, Bench, parameter grids, grouping	Decorators & Suites
BenchContext & runner	Manual timing, calibration knobs, execution helpers	BenchContext & Runner
Runs & storage	Run data model, .pybenchx/ helpers, compare utilities	Runs, Storage & Compare
Reporters & exports	Table rendering, JSON/CSV/Markdown/Chart reporters, extending output	Reporters & Exports

Module overview

• pybench.bench_model: dataclasses (Case, Bench, bench) powering the decorator workflow.
• pybench.timing: BenchContext plus the monotonic clock wrapper.
• pybench.runner: calibration/measurement engine used by the CLI and available for advanced integrations.
• pybench.run_model: serializable run outputs (Run, VariantResult, StatSummary).
• pybench.run_store: helpers for listing, loading, and pruning .pybenchx/ history.
• pybench.reporters: output backends (ANSI table, Markdown, CSV, JSON, Chart.js).
• pybench.utils / pybench.params: supporting utilities (formatting, percentile math, parameter expansion).

Each module exports its public surface via __all__. If an object is not listed there, we consider it internal and subject to change.

Import styles

from pybench import bench, Bench, BenchContext
from pybench.runner import execute_case
from pybench.run_store import save_run, load_baseline

The package root intentionally re-exports only the decorator workflow. Reach into submodules when you need lower-level control (custom runners, storage automation, reporters).

Versioning policy

pybenchx follows semver. Public APIs documented in this section remain stable within a major version. Expect additive changes (new parameters, dataclass fields) in minor releases; breaking changes only land in majors.

Looking for implementation notes or extension guides? See Internals for architecture details and Contributing for development workflows.