onebudgetspec-sdk

The Python SDK for onebudgetspec, imported as onebudgetspec_sdk. It releases at the same version as the onebudgetspec command line and requires onebudgetspec-cli at that version, whose wheel installs the binary.

pip install onebudgetspec-sdk

Each call runs the onebudgetspec binary once, validates the JSON report it prints against onebudgetspec schema, and returns it as a pydantic model generated from that schema:

from onebudgetspec_sdk import check, list_budgets, schema, validate

report = check(
    paths=None, ids=None, labels=["api"], exclude_labels=["slow"], recursive=False, cwd="."
)
for result in report.results:
    print(result.id, result.verdict, result.actual, result.threshold, result.headroom)
    print(result.host.conditions)  # declared conditions, and any the command returned

listed = list_budgets(labels=["api"])  # ListReport; runs no command
validated = validate(recursive=True, paths=["."])  # ListReport of every budget; runs no command
bundle = schema()  # the JSON Schema bundle, as a dict

• check(paths=None, ids=None, labels=None, exclude_labels=None, recursive=False, cwd=None) -> CheckReport
• validate(paths=None, recursive=False, cwd=None) -> ListReport
• list_budgets(paths=None, ids=None, labels=None, exclude_labels=None, recursive=False, cwd=None) -> ListReport
• schema() -> dict
• report(value: float, detail: str | None = None) -> bool, which runs no binary: a reported budget's command calls it to write its result to the file ONEBUDGETSPEC_RESULT names, replacing it, and gets True. With that variable unset or empty it writes nothing and returns False, so a test that measures behaves the same outside a check. A non-finite value raises ValueError and a failed write OSError, and neither writes anything. It never reads a budgets file or judges the value; onebudgetspec check does. Every budget's command also gets its id in ONEBUDGETSPEC_BUDGET_ID.

Exit statuses 0 (within), 1 (over) and 3 (a measurement errored) all return the report, since the verdicts are in it. Status 2, an invalid invocation or budgets file, raises OnebudgetspecError with the CLI's own message and exit_code == 2.

The binary is, in order: the binary= keyword every call takes, then ONEBUDGETSPEC_BIN, then the onebudgetspec the onebudgetspec-cli wheel installed, then onebudgetspec on PATH. resolve_binary() says which.

The models are generated by generate.py from the binary's own schema. In the repository, just generate regenerates them and just lint fails while they and the schema part.