meterbase 0.1.0__py3-none-any.whl

meterbase/_sync/resources/plans.py

@@ -0,0 +1,144 @@
+# Generated by scripts/unasync.py from
+# src/meterbase/_async/resources/plans.py.
+# Do not edit: change the async source, then run `make unasync`.
+
+from __future__ import annotations
+
+from ..._http import segment
+from ..._models import ListResult, list_of
+from ..._not_given import NOT_GIVEN, NotGiven
+from ...types import (
+    ApplyMode,
+    Plan,
+    PlanAllowance,
+    PlanAllowanceKind,
+    PlanCycle,
+    Validity,
+    ValidityParam,
+)
+from .._transport import Requester
+
+
+class PlanAllowances:
+    """
+    A plan's entitlement, versioned. There is no update and no delete: an edit
+    appends the next version, so which amount applied when stays derivable.
+    """
+
+    def __init__(self, api: Requester) -> None:
+        self._api = api
+
+    def set(
+        self,
+        plan_id: str,
+        *,
+        meter_id: str,
+        amount: int | NotGiven = NOT_GIVEN,
+        no_cap: bool | NotGiven = NOT_GIVEN,
+        allow_overage: bool | NotGiven = NOT_GIVEN,
+        kind: PlanAllowanceKind | NotGiven = NOT_GIVEN,
+        valid_for: ValidityParam | Validity | NotGiven = NOT_GIVEN,
+        apply_mode: ApplyMode | NotGiven = NOT_GIVEN,
+    ) -> PlanAllowance:
+        """
+        An allowance says how much, never how often: the period is the plan's
+        cycle. Give exactly one of `amount` or `no_cap`.
+
+        `allow_overage` is a soft cap: past `amount`, admit rather than refuse.
+        Defaults to `False`; refused beside `no_cap` and on `one_time`. `kind`
+        defaults to `recurring`. `valid_for` is `one_time` only. `apply_mode`
+        defaults to `next_cycle`, except `one_time` which is always immediate.
+        """
+        return self._api.request(
+            "POST",
+            f"/v1/plans/{segment(plan_id)}/allowances",
+            PlanAllowance,
+            body={
+                "meter_id": meter_id,
+                "amount": amount,
+                "no_cap": no_cap,
+                "allow_overage": allow_overage,
+                "kind": kind,
+                "valid_for": valid_for,
+                "apply_mode": apply_mode,
+            },
+        )
+
+    def list(
+        self, plan_id: str, *, meter_id: str | NotGiven = NOT_GIVEN
+    ) -> ListResult[PlanAllowance]:
+        """Every version of every meter, newest first — history, not just
+        current."""
+        return self._api.request(
+            "GET",
+            f"/v1/plans/{segment(plan_id)}/allowances",
+            list_of(PlanAllowance),
+            query={"meter_id": meter_id},
+        )
+
+
+class Plans:
+    allowances: PlanAllowances
+
+    def __init__(self, api: Requester) -> None:
+        self._api = api
+        self.allowances = PlanAllowances(api)
+
+    def create(
+        self,
+        *,
+        key: str,
+        name: str,
+        cycle: PlanCycle,
+        description: str | NotGiven = NOT_GIVEN,
+    ) -> Plan:
+        """A new plan grants nothing; attach entitlement with
+        `allowances.set`."""
+        return self._api.request(
+            "POST",
+            "/v1/plans",
+            Plan,
+            body={"key": key, "name": name, "description": description, "cycle": cycle},
+        )
+
+    def list(
+        self, *, include_archived: bool | NotGiven = NOT_GIVEN
+    ) -> ListResult[Plan]:
+        return self._api.request(
+            "GET",
+            "/v1/plans",
+            list_of(Plan),
+            query={"include_archived": include_archived},
+        )
+
+    def retrieve(self, id: str) -> Plan:
+        return self._api.request("GET", f"/v1/plans/{segment(id)}", Plan)
+
+    def update(
+        self,
+        id: str,
+        *,
+        key: str | NotGiven = NOT_GIVEN,
+        name: str | NotGiven = NOT_GIVEN,
+        description: str | NotGiven = NOT_GIVEN,
+    ) -> Plan:
+        """
+        An omitted field is left alone; `""` clears the description. There is
+        no `cycle`: moving a plan's period would re-date every period its
+        customers were already measured against, so a different cadence is a
+        different plan.
+        """
+        return self._api.request(
+            "PATCH",
+            f"/v1/plans/{segment(id)}",
+            Plan,
+            body={"key": key, "name": name, "description": description},
+        )
+
+    def archive(self, id: str) -> Plan:
+        """
+        Stops new assignments without withdrawing capacity from anyone already
+        on the plan, which is why an archived plan still resolves by id.
+        Idempotent.
+        """
+        return self._api.request("DELETE", f"/v1/plans/{segment(id)}", Plan)

meterbase/_time.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta, timezone
+
+# RFC 3339, which is what the engine sends: `2026-09-12T12:00:05.482913Z`, or
+# an offset for the Z. Parsed here rather than by `datetime.fromisoformat`,
+# which before Python 3.11 reads neither the Z nor a fraction that is not
+# three or six digits long.
+_RFC3339 = re.compile(
+    r"(\d{4})-(\d{2})-(\d{2})[Tt ](\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?"
+    r"(?:([Zz])|([+-])(\d{2}):(\d{2}))"
+)
+
+
+def parse_instant(text: object) -> datetime | None:
+    """
+    An RFC 3339 timestamp as an aware `datetime`, or `None` for anything that
+    is not one. A fraction past microseconds is truncated: `datetime` holds no
+    finer.
+    """
+    if not isinstance(text, str):
+        return None
+
+    match = _RFC3339.fullmatch(text.strip())
+    if match is None:
+        return None
+
+    year, month, day, hour, minute, second = (int(part) for part in match.groups()[:6])
+    fraction, zulu, sign, offset_hours, offset_minutes = match.groups()[6:]
+    microsecond = int((fraction or "0")[:6].ljust(6, "0"))
+
+    if zulu:
+        tz = timezone.utc
+    else:
+        offset = timedelta(hours=int(offset_hours), minutes=int(offset_minutes))
+        tz = timezone(-offset if sign == "-" else offset)
+
+    try:
+        return datetime(year, month, day, hour, minute, second, microsecond, tz)
+    except ValueError:
+        # A day or an hour out of range, which matches the pattern and is
+        # still no instant.
+        return None
+
+
+def to_ms(at: datetime) -> float:
+    """Unix milliseconds, fractional below one."""
+    return at.timestamp() * 1000

meterbase/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

meterbase/errors.py

@@ -0,0 +1,309 @@
+"""
+Every failure is a `MeterbaseError`, so a caller can catch one type and still
+tell the specific one apart. `code` is stable; `message` may change.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from ._json import is_object
+from ._time import parse_instant
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APITimeoutError",
+    "AuthenticationError",
+    "ConflictError",
+    "CycleChangeRequiresResetError",
+    "InvalidIdempotencyKeyError",
+    "InvalidRequestError",
+    "MeterbaseError",
+    "NotFoundError",
+    "PeriodSettlingError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ReservationMismatchError",
+    "ServerError",
+    "TooLateError",
+    "WebhookVerificationError",
+    "error_from_response",
+]
+
+
+class MeterbaseError(Exception):
+    """The base of every error this SDK raises."""
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        # Rebuilt from its state rather than from `args`, which is the one
+        # thing the default reads: the subclasses take keyword arguments, so a
+        # worker pool or a task queue could not pickle them back otherwise.
+        return (_rebuild, (type(self), self.args, self.__dict__))
+
+
+def _rebuild(
+    cls: type[MeterbaseError], args: tuple[Any, ...], state: dict[str, Any]
+) -> MeterbaseError:
+    error = cls.__new__(cls)
+    error.args = args
+    error.__dict__.update(state)
+    return error
+
+
+class APIError(MeterbaseError):
+    """The engine answered, with an error."""
+
+    status: int
+    code: str
+    message: str
+    request_id: str | None
+    """From `X-Request-Id`, when the engine sends one."""
+    body: Any
+    """Parsed JSON when the body is JSON, the raw text otherwise, `None` when
+    empty."""
+
+    def __init__(
+        self,
+        *,
+        status: int,
+        code: str,
+        message: str,
+        request_id: str | None = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        self.body = body
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(status={self.status!r}, code={self.code!r}, "
+            f"message={self.message!r})"
+        )
+
+
+class AuthenticationError(APIError):
+    """`401`: an unknown, revoked or malformed key."""
+
+
+class PermissionDeniedError(APIError):
+    """`403`: the key may not use this route."""
+
+
+class NotFoundError(APIError):
+    """`404`. `code` says what was missing."""
+
+
+class ConflictError(APIError):
+    """`409`: a key or external id is taken, among others."""
+
+
+class InvalidRequestError(APIError):
+    """`422`, a field that failed validation; or `400 invalid_query`, a query
+    parameter that did."""
+
+
+class InvalidIdempotencyKeyError(InvalidRequestError):
+    """
+    `422 invalid_idempotency_key`: the key was not a UUID version 7.
+    `uuid.uuid4()` mints a v4, so omit `idempotency_key` and let this SDK mint
+    the right thing.
+    """
+
+
+class TooLateError(InvalidRequestError):
+    """
+    `422 too_late`: the key's timestamp is more than an hour from the engine's
+    clock, so a retry can no longer be told from a new event. **Nothing was
+    recorded** — the check runs before any write.
+
+    The usual cause is this machine's clock. When this SDK minted the key it
+    corrects the offset from `server_time` and retries once, so you only see
+    this for a key you supplied. If that key is a retry of a call made over an
+    hour ago, do not resend it under a new one: it may already be recorded.
+    """
+
+    server_time: datetime | None
+    """The engine's clock when it refused."""
+
+    def __init__(
+        self,
+        *,
+        status: int,
+        code: str,
+        message: str,
+        request_id: str | None = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(
+            status=status,
+            code=code,
+            message=message,
+            request_id=request_id,
+            body=body,
+        )
+        self.server_time = _server_time(body)
+
+
+class ReservationMismatchError(InvalidRequestError):
+    """
+    `422 reservation_mismatch`: the reservation id names a hold made for a
+    different customer or meter than the call sends. A caller bug, refused
+    before anything is written — nothing was recorded and the hold still
+    stands.
+    """
+
+
+class CycleChangeRequiresResetError(InvalidRequestError):
+    """
+    `422 cycle_change_requires_reset`: the two plans measure different cycles,
+    so a `next_cycle` change has no shared boundary to wait for and a
+    `prorate` no shared period to weight. The move is `customers.plan.restart`,
+    which closes the current period and opens a fresh one on the new cycle —
+    or `change_now` with the default `reconciliation="none"` to keep the
+    period that is running. The engine's `message` says as much.
+
+    An `InvalidRequestError` still, so an existing `except` keeps working.
+    """
+
+
+class PeriodSettlingError(ConflictError):
+    """
+    `409 period_settling`: the period ended under a minute ago and may still be
+    taking writes. Read again after `retry_after`; the SDK never retries it.
+    """
+
+    retry_after: float | None
+    """Seconds until the period is final, from `Retry-After`."""
+
+    def __init__(
+        self,
+        *,
+        status: int,
+        code: str,
+        message: str,
+        request_id: str | None = None,
+        retry_after: float | None = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(
+            status=status,
+            code=code,
+            message=message,
+            request_id=request_id,
+            body=body,
+        )
+        self.retry_after = retry_after
+
+
+class RateLimitError(APIError):
+    """`429`. A customer's rate limit is not one: `check` and `reserve` report
+    that as `allowed=False`."""
+
+    retry_after: float | None
+    """Seconds to wait, from `Retry-After`, when the engine sends one."""
+
+    def __init__(
+        self,
+        *,
+        status: int,
+        code: str,
+        message: str,
+        request_id: str | None = None,
+        retry_after: float | None = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(
+            status=status,
+            code=code,
+            message=message,
+            request_id=request_id,
+            body=body,
+        )
+        self.retry_after = retry_after
+
+
+class ServerError(APIError):
+    """`500` and above."""
+
+
+class APIConnectionError(MeterbaseError):
+    """
+    The request never produced an answer: DNS, TLS, a reset. Named so it does
+    not shadow Python's own `ConnectionError`.
+    """
+
+
+class APITimeoutError(APIConnectionError):
+    """An attempt ran past its `timeout`."""
+
+
+class WebhookVerificationError(MeterbaseError):
+    """A webhook that is not one Meterbase signed recently: answer it with a
+    400."""
+
+
+def error_from_response(
+    *,
+    status: int,
+    code: str,
+    message: str,
+    request_id: str | None = None,
+    retry_after: float | None = None,
+    body: Any = None,
+) -> APIError:
+    """The error this SDK raises for a response, which also makes realistic
+    errors for tests."""
+    fields: dict[str, Any] = {
+        "status": status,
+        "code": code,
+        "message": message,
+        "request_id": request_id,
+        "body": body,
+    }
+
+    if status == 400:
+        # A parameter that failed validation, as a 422 is a field that did.
+        if code == "invalid_query":
+            return InvalidRequestError(**fields)
+        return APIError(**fields)
+    if status == 401:
+        return AuthenticationError(**fields)
+    if status == 403:
+        return PermissionDeniedError(**fields)
+    if status == 404:
+        return NotFoundError(**fields)
+    if status == 409:
+        if code == "period_settling":
+            return PeriodSettlingError(**fields, retry_after=retry_after)
+        return ConflictError(**fields)
+    if status == 422:
+        return _UNPROCESSABLE.get(code, InvalidRequestError)(**fields)
+    if status == 429:
+        return RateLimitError(**fields, retry_after=retry_after)
+    if status >= 500:
+        return ServerError(**fields)
+    return APIError(**fields)
+
+
+_UNPROCESSABLE: dict[str, type[InvalidRequestError]] = {
+    "cycle_change_requires_reset": CycleChangeRequiresResetError,
+    "invalid_idempotency_key": InvalidIdempotencyKeyError,
+    "reservation_mismatch": ReservationMismatchError,
+    "too_late": TooLateError,
+}
+
+
+def _server_time(body: Any) -> datetime | None:
+    """The engine carries it beside `code` and `message`, inside `error`."""
+    if not is_object(body):
+        return None
+    error = body.get("error")
+    if not is_object(error):
+        return None
+    return parse_instant(error.get("server_time"))

meterbase/resources.py

@@ -0,0 +1,41 @@
+"""
+The namespaces a client's calls hang off, for annotating code that is handed
+one: `def bill(customers: Customers) -> None`. Reach them through a client —
+`meterbase.customers` — rather than constructing them.
+"""
+
+from ._async.resources import (
+    AsyncCustomerAllowances,
+    AsyncCustomerPeriods,
+    AsyncCustomerPlan,
+    AsyncCustomers,
+    AsyncMeters,
+    AsyncPlanAllowances,
+    AsyncPlans,
+)
+from ._sync.resources import (
+    CustomerAllowances,
+    CustomerPeriods,
+    CustomerPlan,
+    Customers,
+    Meters,
+    PlanAllowances,
+    Plans,
+)
+
+__all__ = [
+    "AsyncCustomerAllowances",
+    "AsyncCustomerPeriods",
+    "AsyncCustomerPlan",
+    "AsyncCustomers",
+    "AsyncMeters",
+    "AsyncPlanAllowances",
+    "AsyncPlans",
+    "CustomerAllowances",
+    "CustomerPeriods",
+    "CustomerPlan",
+    "Customers",
+    "Meters",
+    "PlanAllowances",
+    "Plans",
+]