Metadata-Version: 2.5
Name: onebudgetspec-sdk
Version: 0.1.0
Summary: The onebudgetspec Python SDK: check, validate and list budgets through the onebudgetspec binary, with report models generated from its schema.
Project-URL: Repository, https://github.com/nickderobertis/onebudgetspec
Author: Nick DeRobertis
License-Expression: MIT
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: jsonschema>=4.23
Requires-Dist: onebudgetspec-cli==0.1.0
Requires-Dist: pydantic>=2.12
Requires-Dist: typing-extensions>=4.12
Description-Content-Type: text/markdown

# onebudgetspec-sdk

The Python SDK for [onebudgetspec](https://github.com/nickderobertis/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.

```sh
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:

```python
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`

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.
