onebudgetspec-sdk 0.1.0__py3-none-any.whl

onebudgetspec_sdk/__init__.py

@@ -0,0 +1,45 @@
+"""The onebudgetspec Python SDK: check, validate and list budgets through the binary.
+
+Each call runs the ``onebudgetspec`` binary once and returns its JSON report as a model
+generated from ``onebudgetspec schema``.
+"""
+
+from ._client import (
+    BINARY_ENV,
+    CLI_DISTRIBUTION,
+    OnebudgetspecError,
+    StrPath,
+    check,
+    list_budgets,
+    resolve_binary,
+    schema,
+    validate,
+)
+from ._generated import SCHEMA_BUNDLE_VERSION
+from ._generated.check_report import CheckReport, CheckResult, Direction, Host, Verdict
+from ._generated.list_report import ListedBudget, ListReport, Measure
+
+__all__ = [
+    "BINARY_ENV",
+    "CLI_DISTRIBUTION",
+    "SCHEMA_BUNDLE_VERSION",
+    "CheckReport",
+    "CheckResult",
+    "Direction",
+    "Host",
+    "ListReport",
+    "ListedBudget",
+    "Measure",
+    "OnebudgetspecError",
+    "StrPath",
+    "Verdict",
+    "__version__",
+    "check",
+    "list_budgets",
+    "resolve_binary",
+    "schema",
+    "validate",
+]
+
+#: The version of this package, which releases in lock step with the ``onebudgetspec`` binary.
+__version__ = "0.1.0"

onebudgetspec_sdk/_client.py

@@ -0,0 +1,394 @@
+"""Run the ``onebudgetspec`` binary once per call and read the JSON report it prints.
+
+Nothing here measures, loads or selects a budget: the binary does all of it, and this
+module turns a call into its argv and its stdout into the generated report type, after
+validating it against the schema that type was generated from.
+"""
+
+import importlib.metadata
+import json
+import math
+import os
+import re
+import shutil
+import subprocess
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import TypeVar
+
+from jsonschema import Draft202012Validator, FormatChecker
+from pydantic import BaseModel, JsonValue, ValidationError
+
+from ._generated import BUNDLE_ROOTS
+from ._generated.check_report import CheckReport
+from ._generated.list_report import ListReport
+from ._generated.schemas import REPORT_SCHEMAS
+
+#: The environment variable naming the binary when no explicit one is passed.
+BINARY_ENV = "ONEBUDGETSPEC_BIN"
+#: The distribution whose wheel carries the binary.
+CLI_DISTRIBUTION = "onebudgetspec-cli"
+_EXECUTABLE = "onebudgetspec"
+#: The statuses whose stdout is a report: within, over and error. A verdict is in the
+#: report, so none of them is an exception.
+_REPORTED = frozenset({0, 1, 3})
+
+#: A filesystem path, as a string or a path object.
+StrPath = str | os.PathLike[str]
+_Report = TypeVar("_Report", bound=BaseModel)
+
+
+class OnebudgetspecError(RuntimeError):
+    """The binary refused the call, could not run, or printed no report.
+
+    ``str(error)`` is the binary's own message when it gave one. ``exit_code`` is its exit
+    status, ``2`` for an invalid invocation or budgets file, and ``None`` when no binary ran.
+    """
+
+    def __init__(self, message: str, *, exit_code: int | None) -> None:
+        """Keep the message and the exit status, ``None`` when nothing ran."""
+        super().__init__(message)
+        self.exit_code = exit_code
+
+
+def _bundled() -> Path | None:
+    """The binary the ``onebudgetspec-cli`` wheel installed, when it is installed."""
+    try:
+        distribution = importlib.metadata.distribution(CLI_DISTRIBUTION)
+    except importlib.metadata.PackageNotFoundError:
+        return None
+    for file in distribution.files or ():
+        if file.name == _EXECUTABLE and file.parent.name == "bin":
+            path = Path(os.path.normpath(Path(str(distribution.locate_file(file)))))
+            if path.is_file():
+                return path
+    return None
+
+
+def resolve_binary(binary: StrPath | None = None) -> Path:
+    """The binary a call runs.
+
+    In order: ``binary`` when given, then ``ONEBUDGETSPEC_BIN`` when set and non-empty, then
+    the binary the ``onebudgetspec-cli`` wheel installed, then ``onebudgetspec`` on ``PATH``.
+
+    Raises:
+        OnebudgetspecError: none of them names a binary.
+    """
+    if binary is not None:
+        return Path(binary)
+    from_environment = os.environ.get(BINARY_ENV)
+    if from_environment:
+        return Path(from_environment)
+    bundled = _bundled()
+    if bundled is not None:
+        return bundled
+    on_path = shutil.which(_EXECUTABLE)
+    if on_path is not None:
+        return Path(on_path)
+    raise OnebudgetspecError(
+        f"onebudgetspec: no binary found; install {CLI_DISTRIBUTION}, put {_EXECUTABLE} "
+        f"on PATH, set {BINARY_ENV}, or pass binary=",
+        exit_code=None,
+    )
+
+
+def _values(name: str, values: Sequence[str] | None) -> list[str]:
+    """``values`` as a list, refusing a lone string, which would split into characters."""
+    if values is None:
+        return []
+    if isinstance(values, str) or not all(isinstance(value, str) for value in values):
+        raise TypeError(f"{name} must be a sequence of strings, not {values!r}")
+    return list(values)
+
+
+def _paths(paths: Sequence[StrPath] | None) -> list[str]:
+    if paths is None:
+        return []
+    if isinstance(paths, (str, os.PathLike)):
+        raise TypeError(f"paths must be a sequence of paths, not {paths!r}")
+    return [os.fspath(path) for path in paths]
+
+
+def _files(paths: Sequence[StrPath] | None, recursive: bool) -> list[str]:
+    """The flags and operands naming the budgets files, after ``--`` so none reads as a flag."""
+    if not isinstance(recursive, bool):
+        raise TypeError(f"recursive must be True or False, not {recursive!r}")
+    return [*(["--recursive"] if recursive else []), "--", *_paths(paths)]
+
+
+def _selection(
+    ids: Sequence[str] | None,
+    labels: Sequence[str] | None,
+    exclude_labels: Sequence[str] | None,
+) -> list[str]:
+    """The selection flags, each value joined to its flag so none can read as a flag."""
+    return [
+        f"{flag}={value}"
+        for flag, name, values in (
+            ("--id", "ids", ids),
+            ("--label", "labels", labels),
+            ("--exclude-label", "exclude_labels", exclude_labels),
+        )
+        for value in _values(name, values)
+    ]
+
+
+def _run(binary: StrPath | None, args: list[str], cwd: StrPath | None) -> bytes:
+    """Run the binary with ``args`` and return its stdout, or raise with its message."""
+    program = resolve_binary(binary)
+    try:
+        completed = subprocess.run(
+            [os.fspath(program), *args],
+            cwd=cwd,
+            stdin=subprocess.DEVNULL,
+            capture_output=True,
+            check=False,
+        )
+    except OSError as error:
+        raise OnebudgetspecError(
+            f"onebudgetspec: cannot run {program}: {error}", exit_code=None
+        ) from error
+    if completed.returncode in _REPORTED:
+        return completed.stdout
+    status = completed.returncode
+    message = completed.stderr.decode(errors="replace").strip()
+    if not message:
+        ended = f"was terminated by signal {-status}" if status < 0 else f"exited {status}"
+        message = f"onebudgetspec: {program} {ended} with no message"
+    raise OnebudgetspecError(message, exit_code=status)
+
+
+#: An RFC 3339 timestamp, as the reports' ``date-time`` fields carry.
+_RFC3339 = re.compile(
+    r"(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|[+-](\d{2}):(\d{2}))",
+    re.IGNORECASE,
+)
+_DAYS_IN_MONTH = (31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31)
+#: Every format the report schemas name, checked: the timestamps, and the numeric widths
+#: the binary's Rust types carry. A format applies only to its own JSON type; the schema's
+#: ``type`` refuses any other.
+_FORMATS = FormatChecker(formats=())
+
+
+@_FORMATS.checks("date-time")
+def _is_date_time(value: object) -> bool:
+    """An RFC 3339 instant: a day its month has, and every field in range.
+
+    A second of 60 is refused: a leap second cannot be told from a nonexistent one here.
+    """
+    if not isinstance(value, str):
+        return True
+    match = _RFC3339.fullmatch(value)
+    if match is None:
+        return False
+    year, month, day, hour, minute, second = (int(part) for part in match.groups()[:6])
+    offset_hours, offset_minutes = (int(part or 0) for part in match.groups()[6:])
+    if not 1 <= month <= 12:
+        return False
+    leap = year % 4 == 0 and (year % 100 != 0 or year % 400 == 0)
+    days = _DAYS_IN_MONTH[month - 1] + (1 if month == 2 and leap else 0)
+    return (
+        1 <= day <= days
+        and hour <= 23
+        and minute <= 59
+        and second <= 59
+        and offset_hours <= 23
+        and offset_minutes <= 59
+    )
+
+
+def _is_unsigned(bits: int) -> Callable[[object], bool]:
+    """A check that an integer fits in ``bits`` unsigned bits."""
+
+    def check(value: object) -> bool:
+        if isinstance(value, bool) or not isinstance(value, int):
+            return True
+        return 0 <= value < 2**bits
+
+    return check
+
+
+_FORMATS.checks("uint32")(_is_unsigned(32))
+_FORMATS.checks("uint64")(_is_unsigned(64))
+
+
+@_FORMATS.checks("double")
+def _is_double(value: object) -> bool:
+    """A finite number; JSON holds no infinity, but a literal too large reads as one."""
+    return not isinstance(value, float) or math.isfinite(value)
+
+
+def _formats_named(schema: object) -> set[str]:
+    """Every ``format`` a JSON Schema names, at any depth."""
+    match schema:
+        case {"format": str(name), **rest}:
+            return {name}.union(*(_formats_named(value) for value in rest.values()))
+        case dict():
+            return set().union(*(_formats_named(value) for value in schema.values()))
+        case list():
+            return set().union(*(_formats_named(item) for item in schema))
+        case _:
+            return set()
+
+
+def _require_validators(schemas: object) -> None:
+    """Refuse report schemas naming a format no validator here checks.
+
+    ``FormatChecker`` passes a format it has no check for, so a report schema naming one would
+    let its values through unchecked; this makes that a failure at import instead.
+
+    Raises:
+        OnebudgetspecError: a format the schemas name has no validator in this module.
+    """
+    unchecked = sorted(_formats_named(schemas) - set(_FORMATS.checkers))
+    if unchecked:
+        raise OnebudgetspecError(
+            f"onebudgetspec: the report schemas name the format(s) {unchecked}, which this SDK "
+            "has no validator for, so it cannot check the binary's reports; install the "
+            "onebudgetspec-sdk release that matches the binary, or, developing this SDK, add a "
+            "validator for each to onebudgetspec_sdk/_client.py",
+            exit_code=None,
+        )
+
+
+_require_validators(REPORT_SCHEMAS)
+_VALIDATORS = {
+    root: Draft202012Validator(schema, format_checker=_FORMATS)
+    for root, schema in REPORT_SCHEMAS.items()
+}
+
+
+def _report(model: type[_Report], root: str, stdout: bytes) -> _Report:
+    """``stdout`` as ``model``, once it is valid against the schema root ``root``."""
+    try:
+        document = json.loads(stdout)
+    except ValueError as error:
+        raise OnebudgetspecError(
+            f"onebudgetspec: the binary printed no JSON: {error}", exit_code=None
+        ) from error
+    problems = [
+        f"{'/'.join(str(part) for part in error.absolute_path) or '(report)'}: {error.message}"
+        for error in _VALIDATORS[root].iter_errors(document)
+    ]
+    if problems:
+        raise OnebudgetspecError(
+            f"onebudgetspec: the binary printed no valid {root}: {'; '.join(sorted(problems))}",
+            exit_code=None,
+        )
+    try:
+        # Strict: a report field of the wrong JSON type is refused, never coerced.
+        return model.model_validate_json(stdout, strict=True)
+    except ValidationError as error:
+        raise OnebudgetspecError(
+            f"onebudgetspec: the binary printed no valid {root}: {error}", exit_code=None
+        ) from error
+
+
+def check(
+    paths: Sequence[StrPath] | None = None,
+    ids: Sequence[str] | None = None,
+    labels: Sequence[str] | None = None,
+    exclude_labels: Sequence[str] | None = None,
+    recursive: bool = False,
+    cwd: StrPath | None = None,
+    *,
+    binary: StrPath | None = None,
+) -> CheckReport:
+    """Measure every selected budget once: ``onebudgetspec check``.
+
+    Args:
+        paths: budgets files, or directories with ``recursive``; ``./budgets.yaml`` when
+            omitted. Relative paths are read from ``cwd``.
+        ids: keep only these budgets; an id no file registers is refused.
+        labels: keep budgets carrying at least one of these labels.
+        exclude_labels: drop budgets carrying any of these labels.
+        recursive: search directories for files named ``budgets.yaml``.
+        cwd: the directory to run from; the current one when omitted.
+        binary: the binary to run; see :func:`resolve_binary`.
+
+    Returns:
+        The report, whatever its verdicts: within, over and error are all in it.
+
+    Raises:
+        OnebudgetspecError: the invocation or a budgets file is invalid (exit status 2),
+            with the binary's message, or the binary could not run.
+    """
+    args = ["check", "--json", *_selection(ids, labels, exclude_labels), *_files(paths, recursive)]
+    return _report(CheckReport, "check-report", _run(binary, args, cwd))
+
+
+def validate(
+    paths: Sequence[StrPath] | None = None,
+    recursive: bool = False,
+    cwd: StrPath | None = None,
+    *,
+    binary: StrPath | None = None,
+) -> ListReport:
+    """Check the files' shape and id uniqueness, running no command: ``onebudgetspec validate``.
+
+    Args:
+        paths: as for :func:`check`.
+        recursive: as for :func:`check`.
+        cwd: as for :func:`check`.
+        binary: as for :func:`check`.
+
+    Returns:
+        Every budget the valid files register, as ``list`` reports them.
+
+    Raises:
+        OnebudgetspecError: a file is invalid (exit status 2), with the binary's message.
+    """
+    args = ["validate", "--json", *_files(paths, recursive)]
+    return _report(ListReport, "list-report", _run(binary, args, cwd))
+
+
+def list_budgets(
+    paths: Sequence[StrPath] | None = None,
+    ids: Sequence[str] | None = None,
+    labels: Sequence[str] | None = None,
+    exclude_labels: Sequence[str] | None = None,
+    recursive: bool = False,
+    cwd: StrPath | None = None,
+    *,
+    binary: StrPath | None = None,
+) -> ListReport:
+    """Report the selected budgets, running no command: ``onebudgetspec list``.
+
+    Takes the arguments of :func:`check`.
+
+    Raises:
+        OnebudgetspecError: the invocation or a budgets file is invalid (exit status 2).
+    """
+    args = ["list", "--json", *_selection(ids, labels, exclude_labels), *_files(paths, recursive)]
+    return _report(ListReport, "list-report", _run(binary, args, cwd))
+
+
+def schema(*, binary: StrPath | None = None) -> dict[str, JsonValue]:
+    """The JSON Schema bundle the binary prints: ``onebudgetspec schema``.
+
+    Raises:
+        OnebudgetspecError: the binary could not run, or printed no schema bundle.
+    """
+    stdout = _run(binary, ["schema"], None)
+    try:
+        bundle = json.loads(stdout)
+    except ValueError as error:
+        raise OnebudgetspecError(
+            f"onebudgetspec: the schema is not JSON: {error}", exit_code=None
+        ) from error
+    if not isinstance(bundle, dict):
+        raise OnebudgetspecError("onebudgetspec: the schema is not a JSON object", exit_code=None)
+    version, roots = bundle.get("version"), bundle.get("roots")
+    if (
+        isinstance(version, bool)
+        or not isinstance(version, int)
+        or not isinstance(roots, dict)
+        or not all(isinstance(roots.get(root), dict) for root in BUNDLE_ROOTS)
+    ):
+        raise OnebudgetspecError(
+            "onebudgetspec: the binary's output is not a schema bundle: it needs an integer "
+            f"`version` and the `roots` {list(BUNDLE_ROOTS)}, each an object; point "
+            f"{BINARY_ENV} at an onebudgetspec binary, or reinstall {CLI_DISTRIBUTION}",
+            exit_code=None,
+        )
+    return bundle

onebudgetspec_sdk/_generated/__init__.py

@@ -0,0 +1,7 @@
+"""Models generated from `onebudgetspec schema`; see sdks/python/generate.py."""
+
+#: The version of the schema bundle these models were generated from.
+SCHEMA_BUNDLE_VERSION = 1
+
+#: Every root the schema bundle carries, which the client requires of one.
+BUNDLE_ROOTS = ("budgets-file", "check-report", "list-report")

onebudgetspec_sdk/_generated/check_report.py

@@ -0,0 +1,137 @@
+# Generated by sdks/python/generate.py from the 'check-report' root of `onebudgetspec schema`.
+# Do not edit: re-run the generator. Each docstring is the schema's description verbatim.
+# ruff: noqa: D200, D205, D212, D400, D415, E501
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field
+from typing_extensions import TypeAliasType
+
+Direction = TypeAliasType("Direction", Literal["max", "min"])
+"""
+Which side of the threshold is within.
+"""
+
+
+class Host(BaseModel):
+    """
+    The host conditions recorded beside a result.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    conditions: dict[str, str]
+    """
+    Each condition the file declares, and for a `reported` result each condition its
+    command returned, by name.
+    """
+    cpus: int = Field(..., ge=0)
+    """
+    The CPUs available to this process.
+    """
+    load1: float | None
+    """
+    The 1-minute load average; null where unreadable.
+    """
+    mem_available_mib: int | None = Field(..., ge=0)
+    """
+    Available memory in MiB; null where unreadable.
+    """
+
+
+Verdict = TypeAliasType("Verdict", Literal["within", "over", "error"])
+"""
+A result's verdict.
+"""
+
+
+class CheckResult(BaseModel):
+    """
+    One budget's measurement.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    actual: float | None
+    """
+    The measured value; null on an error.
+    """
+    detail: str | None
+    """
+    The `detail` a `reported` command wrote; null when it wrote none.
+    """
+    direction: Direction
+    """
+    The budget's direction.
+    """
+    ended_at: AwareDatetime
+    """
+    When the measurement ended (RFC 3339), never before `started_at`.
+    """
+    error: str | None
+    """
+    Why the measurement failed; null unless `verdict` is `error`.
+    """
+    file: str
+    """
+    The budgets file's path, as discovered or given.
+    """
+    headroom: float | None
+    """
+    `threshold - actual` under `max`, `actual - threshold` under `min`; negative when
+    over, null on an error.
+    """
+    headroom_percent: float | None
+    """
+    `headroom / threshold * 100`; null on an error or when the threshold is 0.
+    """
+    host: Host
+    """
+    The host conditions recorded beside this result.
+    """
+    id: str
+    """
+    The budget's id.
+    """
+    labels: list[str]
+    """
+    The budget's labels, empty when it has none.
+    """
+    started_at: AwareDatetime
+    """
+    When the measurement started (RFC 3339).
+    """
+    threshold: float
+    """
+    The budget's threshold.
+    """
+    unit: str
+    """
+    The budget's unit.
+    """
+    verdict: Verdict
+    """
+    `within`, `over` or `error`.
+    """
+
+
+class CheckReport(BaseModel):
+    """
+    What `check` answers with: one result per selected budget, in measurement order.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    results: list[CheckResult]
+    """
+    One result per selected budget.
+    """
+    schema_version: Literal[1]
+    """
+    Always `1`.
+    """

onebudgetspec_sdk/_generated/list_report.py

@@ -0,0 +1,89 @@
+# Generated by sdks/python/generate.py from the 'list-report' root of `onebudgetspec schema`.
+# Do not edit: re-run the generator. Each docstring is the schema's description verbatim.
+# ruff: noqa: D200, D205, D212, D400, D415, E501
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+from typing_extensions import TypeAliasType
+
+Direction = TypeAliasType("Direction", Literal["max", "min"])
+"""
+Which side of the threshold is within.
+"""
+
+
+Measure = TypeAliasType("Measure", Literal["elapsed", "reported"])
+"""
+How a budget's value is measured.
+"""
+
+
+class ListedBudget(BaseModel):
+    """
+    One budget as `list` reports it: every field the file gives, plus the file.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    command: list[str]
+    """
+    The argv that measures it.
+    """
+    description: str | None
+    """
+    The budget's description; null when it has none.
+    """
+    direction: Direction
+    """
+    The budget's direction.
+    """
+    file: str
+    """
+    The budgets file's path, as discovered or given.
+    """
+    id: str
+    """
+    The budget's id.
+    """
+    labels: list[str]
+    """
+    The budget's labels, empty when it has none.
+    """
+    measure: Measure
+    """
+    How the value is measured.
+    """
+    threshold: float
+    """
+    The budget's threshold.
+    """
+    timeout_seconds: int | None = Field(..., ge=0)
+    """
+    The budget's timeout; null when it has none.
+    """
+    unit: str
+    """
+    The budget's unit.
+    """
+
+
+class ListReport(BaseModel):
+    """
+    What `list` answers with: the selected budgets, in file order.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    budgets: list[ListedBudget]
+    """
+    The selected budgets.
+    """
+    schema_version: Literal[1]
+    """
+    Always `1`.
+    """

onebudgetspec_sdk/_generated/schemas.py

@@ -0,0 +1,283 @@
+# ruff: noqa: E501  # The schema's descriptions are kept verbatim.
+"""The report roots of `onebudgetspec schema`, generated by sdks/python/generate.py.
+
+The client validates every report against them. Do not edit.
+"""
+
+#: Each report root, by name, as the binary emits it.
+REPORT_SCHEMAS: dict[str, dict[str, object]] = {
+    "check-report": {
+        "$defs": {
+            "CheckResult": {
+                "additionalProperties": False,
+                "description": "One budget's measurement.",
+                "properties": {
+                    "actual": {
+                        "description": "The measured value; null on an error.",
+                        "format": "double",
+                        "type": ["number", "null"],
+                    },
+                    "detail": {
+                        "description": "The `detail` a `reported` command wrote; null when it wrote none.",
+                        "type": ["string", "null"],
+                    },
+                    "direction": {
+                        "$ref": "#/$defs/Direction",
+                        "description": "The budget's direction.",
+                    },
+                    "ended_at": {
+                        "description": "When the measurement ended (RFC 3339), never before `started_at`.",
+                        "format": "date-time",
+                        "type": "string",
+                    },
+                    "error": {
+                        "description": "Why the measurement failed; null unless `verdict` is `error`.",
+                        "type": ["string", "null"],
+                    },
+                    "file": {
+                        "description": "The budgets file's path, as discovered or given.",
+                        "type": "string",
+                    },
+                    "headroom": {
+                        "description": "`threshold - actual` under `max`, `actual - threshold` under `min`; negative when\nover, null on an error.",
+                        "format": "double",
+                        "type": ["number", "null"],
+                    },
+                    "headroom_percent": {
+                        "description": "`headroom / threshold * 100`; null on an error or when the threshold is 0.",
+                        "format": "double",
+                        "type": ["number", "null"],
+                    },
+                    "host": {
+                        "$ref": "#/$defs/Host",
+                        "description": "The host conditions recorded beside this result.",
+                    },
+                    "id": {"description": "The budget's id.", "type": "string"},
+                    "labels": {
+                        "description": "The budget's labels, empty when it has none.",
+                        "items": {"type": "string"},
+                        "type": "array",
+                    },
+                    "started_at": {
+                        "description": "When the measurement started (RFC 3339).",
+                        "format": "date-time",
+                        "type": "string",
+                    },
+                    "threshold": {
+                        "description": "The budget's threshold.",
+                        "format": "double",
+                        "type": "number",
+                    },
+                    "unit": {"description": "The budget's unit.", "type": "string"},
+                    "verdict": {
+                        "$ref": "#/$defs/Verdict",
+                        "description": "`within`, `over` or `error`.",
+                    },
+                },
+                "required": [
+                    "actual",
+                    "detail",
+                    "direction",
+                    "ended_at",
+                    "error",
+                    "file",
+                    "headroom",
+                    "headroom_percent",
+                    "host",
+                    "id",
+                    "labels",
+                    "started_at",
+                    "threshold",
+                    "unit",
+                    "verdict",
+                ],
+                "type": "object",
+            },
+            "Direction": {
+                "description": "Which side of the threshold is within.",
+                "oneOf": [
+                    {
+                        "const": "max",
+                        "description": "Within when `actual <= threshold`.",
+                        "type": "string",
+                    },
+                    {
+                        "const": "min",
+                        "description": "Within when `actual >= threshold`.",
+                        "type": "string",
+                    },
+                ],
+            },
+            "Host": {
+                "additionalProperties": False,
+                "description": "The host conditions recorded beside a result.",
+                "properties": {
+                    "conditions": {
+                        "additionalProperties": {"type": "string"},
+                        "description": "Each condition the file declares, and for a `reported` result each condition its\ncommand returned, by name.",
+                        "type": "object",
+                    },
+                    "cpus": {
+                        "description": "The CPUs available to this process.",
+                        "format": "uint32",
+                        "minimum": 0,
+                        "type": "integer",
+                    },
+                    "load1": {
+                        "description": "The 1-minute load average; null where unreadable.",
+                        "format": "double",
+                        "type": ["number", "null"],
+                    },
+                    "mem_available_mib": {
+                        "description": "Available memory in MiB; null where unreadable.",
+                        "format": "uint64",
+                        "minimum": 0,
+                        "type": ["integer", "null"],
+                    },
+                },
+                "required": ["conditions", "cpus", "load1", "mem_available_mib"],
+                "type": "object",
+            },
+            "Verdict": {
+                "description": "A result's verdict.",
+                "oneOf": [
+                    {
+                        "const": "within",
+                        "description": "The actual value is on the budget's side of the threshold.",
+                        "type": "string",
+                    },
+                    {
+                        "const": "over",
+                        "description": "The actual value is past the threshold.",
+                        "type": "string",
+                    },
+                    {
+                        "const": "error",
+                        "description": "No value was measured; `error` says why.",
+                        "type": "string",
+                    },
+                ],
+            },
+        },
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "additionalProperties": False,
+        "description": "What `check` answers with: one result per selected budget, in measurement order.",
+        "properties": {
+            "results": {
+                "description": "One result per selected budget.",
+                "items": {"$ref": "#/$defs/CheckResult"},
+                "type": "array",
+            },
+            "schema_version": {"const": 1, "description": "Always `1`.", "type": "integer"},
+        },
+        "required": ["schema_version", "results"],
+        "title": "check-report",
+        "type": "object",
+    },
+    "list-report": {
+        "$defs": {
+            "Direction": {
+                "description": "Which side of the threshold is within.",
+                "oneOf": [
+                    {
+                        "const": "max",
+                        "description": "Within when `actual <= threshold`.",
+                        "type": "string",
+                    },
+                    {
+                        "const": "min",
+                        "description": "Within when `actual >= threshold`.",
+                        "type": "string",
+                    },
+                ],
+            },
+            "ListedBudget": {
+                "additionalProperties": False,
+                "description": "One budget as `list` reports it: every field the file gives, plus the file.",
+                "properties": {
+                    "command": {
+                        "description": "The argv that measures it.",
+                        "items": {"type": "string"},
+                        "type": "array",
+                    },
+                    "description": {
+                        "description": "The budget's description; null when it has none.",
+                        "type": ["string", "null"],
+                    },
+                    "direction": {
+                        "$ref": "#/$defs/Direction",
+                        "description": "The budget's direction.",
+                    },
+                    "file": {
+                        "description": "The budgets file's path, as discovered or given.",
+                        "type": "string",
+                    },
+                    "id": {"description": "The budget's id.", "type": "string"},
+                    "labels": {
+                        "description": "The budget's labels, empty when it has none.",
+                        "items": {"type": "string"},
+                        "type": "array",
+                    },
+                    "measure": {
+                        "$ref": "#/$defs/Measure",
+                        "description": "How the value is measured.",
+                    },
+                    "threshold": {
+                        "description": "The budget's threshold.",
+                        "format": "double",
+                        "type": "number",
+                    },
+                    "timeout_seconds": {
+                        "description": "The budget's timeout; null when it has none.",
+                        "format": "uint64",
+                        "minimum": 0,
+                        "type": ["integer", "null"],
+                    },
+                    "unit": {"description": "The budget's unit.", "type": "string"},
+                },
+                "required": [
+                    "command",
+                    "description",
+                    "direction",
+                    "file",
+                    "id",
+                    "labels",
+                    "measure",
+                    "threshold",
+                    "timeout_seconds",
+                    "unit",
+                ],
+                "type": "object",
+            },
+            "Measure": {
+                "description": "How a budget's value is measured.",
+                "oneOf": [
+                    {
+                        "const": "elapsed",
+                        "description": "The command's wall clock, in seconds; a non-zero exit is an error.",
+                        "type": "string",
+                    },
+                    {
+                        "const": "reported",
+                        "description": "The value the command writes to the file `ONEBUDGETSPEC_RESULT` names.",
+                        "type": "string",
+                    },
+                ],
+            },
+        },
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "additionalProperties": False,
+        "description": "What `list` answers with: the selected budgets, in file order.",
+        "properties": {
+            "budgets": {
+                "description": "The selected budgets.",
+                "items": {"$ref": "#/$defs/ListedBudget"},
+                "type": "array",
+            },
+            "schema_version": {"const": 1, "description": "Always `1`.", "type": "integer"},
+        },
+        "required": ["schema_version", "budgets"],
+        "title": "list-report",
+        "type": "object",
+    },
+}

onebudgetspec_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,59 @@
+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.

onebudgetspec_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+onebudgetspec_sdk/__init__.py,sha256=bLF60eZfj8el1XgwZhkAUlNowltqH_QiGfrzBIohKMY,1084
+onebudgetspec_sdk/_client.py,sha256=jPSFTA0QenflMrNqhrIQloBvr-3ONRG8xzEi43yIppM,14748
+onebudgetspec_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+onebudgetspec_sdk/_generated/__init__.py,sha256=AhDOYr_x7dAphRo16masPrNZKVVhE3wgW1vD5IheAT0,317
+onebudgetspec_sdk/_generated/check_report.py,sha256=Etfev6a5pC9dKNWm43zoGSFrH7JImFIxMkhuMxfrYX4,3068
+onebudgetspec_sdk/_generated/list_report.py,sha256=i50nhyWcpdyM_UdhHZRsIX63ArTwRfHqDiFIy1essJQ,1874
+onebudgetspec_sdk/_generated/schemas.py,sha256=PGM6vBjCJmYmz-pxno4bo8X5fG7e6P0fPzqvaa4h_9U,12043
+onebudgetspec_sdk-0.1.0.dist-info/METADATA,sha256=Na-QLNL7Y8Kp4wpl4zNunb7RFDy2TSsWtphAZdcxpHM,2662
+onebudgetspec_sdk-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+onebudgetspec_sdk-0.1.0.dist-info/RECORD,,

onebudgetspec_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any