meterbase 0.1.0__py3-none-any.whl

meterbase/_async/resources/plans.py

@@ -0,0 +1,140 @@
+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 AsyncRequester
+
+
+class AsyncPlanAllowances:
+    """
+    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: AsyncRequester) -> None:
+        self._api = api
+
+    async 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 await 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,
+            },
+        )
+
+    async 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 await self._api.request(
+            "GET",
+            f"/v1/plans/{segment(plan_id)}/allowances",
+            list_of(PlanAllowance),
+            query={"meter_id": meter_id},
+        )
+
+
+class AsyncPlans:
+    allowances: AsyncPlanAllowances
+
+    def __init__(self, api: AsyncRequester) -> None:
+        self._api = api
+        self.allowances = AsyncPlanAllowances(api)
+
+    async 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 await self._api.request(
+            "POST",
+            "/v1/plans",
+            Plan,
+            body={"key": key, "name": name, "description": description, "cycle": cycle},
+        )
+
+    async def list(
+        self, *, include_archived: bool | NotGiven = NOT_GIVEN
+    ) -> ListResult[Plan]:
+        return await self._api.request(
+            "GET",
+            "/v1/plans",
+            list_of(Plan),
+            query={"include_archived": include_archived},
+        )
+
+    async def retrieve(self, id: str) -> Plan:
+        return await self._api.request("GET", f"/v1/plans/{segment(id)}", Plan)
+
+    async 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 await self._api.request(
+            "PATCH",
+            f"/v1/plans/{segment(id)}",
+            Plan,
+            body={"key": key, "name": name, "description": description},
+        )
+
+    async 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 await self._api.request("DELETE", f"/v1/plans/{segment(id)}", Plan)

meterbase/_http.py

@@ -0,0 +1,205 @@
+"""
+What the two transports share: building a request, reading the answer, and
+deciding whether to try again. None of it does I/O, so the sync and async
+clients cannot disagree about any of it.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import random
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, cast
+from urllib.parse import quote, urlencode
+
+import httpx
+
+from ._json import is_object
+from ._models import Model
+from ._not_given import NotGiven
+from ._version import __version__
+from .errors import APIError, MeterbaseError, error_from_response
+
+DEFAULT_BASE_URL = "https://api.meterbase.tech"
+DEFAULT_TIMEOUT = 10.0
+DEFAULT_MAX_RETRIES = 2
+MAX_BACKOFF = 8.0
+
+USER_AGENT = f"meterbase-python/{__version__}"
+
+Query = Mapping[str, object]
+Body = Mapping[str, object]
+
+
+@dataclass(frozen=True)
+class RequestOptions:
+    timeout: float
+    """Seconds, per attempt rather than per call."""
+    max_retries: int
+
+    def __post_init__(self) -> None:
+        # A negative count would run the loop no times at all, and a call that
+        # makes no attempt has nothing to answer with.
+        if self.max_retries < 0:
+            raise MeterbaseError("max_retries should be 0 or more.")
+        if not self.timeout > 0:
+            raise MeterbaseError("timeout should be a number of seconds above 0.")
+
+
+def normalize_base_url(base_url: str | None) -> str:
+    url = (DEFAULT_BASE_URL if base_url is None else base_url).rstrip("/")
+    try:
+        parsed = httpx.URL(url)
+    except httpx.InvalidURL:
+        parsed = None
+
+    if parsed is None or parsed.scheme not in ("http", "https") or not parsed.host:
+        raise MeterbaseError(
+            f"base_url should be an http or https URL, such as {DEFAULT_BASE_URL}; "
+            f"got {base_url!r}."
+        )
+    return url
+
+
+def origin_of(base_url: str) -> str:
+    url = httpx.URL(base_url)
+    return f"{url.scheme}://{url.netloc.decode('ascii')}"
+
+
+def segment(value: str) -> str:
+    """One path segment, percent-encoded, a slash included."""
+    return quote(value, safe="")
+
+
+def build_url(base_url: str, path: str, query: Query | None) -> str:
+    pairs = [
+        (key, _query_value(value))
+        for key, value in (query or {}).items()
+        if value is not None and not isinstance(value, NotGiven)
+    ]
+    return base_url + path + (f"?{urlencode(pairs)}" if pairs else "")
+
+
+def _query_value(value: object) -> str:
+    # As the engine spells them, rather than Python's `True`.
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def request_headers(api_key: str, *, has_body: bool) -> dict[str, str]:
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Accept": "application/json",
+        "User-Agent": USER_AGENT,
+    }
+    if has_body:
+        headers["Content-Type"] = "application/json"
+    return headers
+
+
+def encode_body(body: Body) -> bytes:
+    """
+    JSON, leaving out every field that is `NOT_GIVEN`. The engine refuses a
+    field it does not know, so a default this SDK sent on the caller's behalf
+    could break a call against an engine that predates it.
+    """
+    fields = {
+        key: value for key, value in body.items() if not isinstance(value, NotGiven)
+    }
+    return json.dumps(
+        fields,
+        default=_json_default,
+        ensure_ascii=False,
+        allow_nan=False,
+        separators=(",", ":"),
+    ).encode("utf-8")
+
+
+def _json_default(value: object) -> object:
+    # A model sent back as a parameter is the JSON it was read from.
+    if isinstance(value, Model):
+        return value.to_dict()
+    if isinstance(value, Mapping):
+        return dict(cast("Mapping[object, object]", value))
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        return list(cast("Sequence[object]", value))
+    raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")
+
+
+def parse_body(response: httpx.Response) -> Any:
+    if response.status_code == 204 or not response.content:
+        return None
+    try:
+        return json.loads(response.content)
+    except ValueError as error:
+        raise MeterbaseError("The engine returned a body that is not JSON.") from error
+
+
+def error_from(response: httpx.Response) -> APIError:
+    text = response.text
+    parsed = _safe_json(text)
+    envelope = _error_envelope(parsed)
+    status = response.status_code
+
+    return error_from_response(
+        status=status,
+        code=envelope[0] if envelope else f"http_{status}",
+        message=envelope[1] if envelope else f"The engine responded {status}.",
+        request_id=response.headers.get("x-request-id"),
+        retry_after=parse_retry_after(response.headers.get("retry-after")),
+        body=None if text == "" else (text if parsed is _NOT_JSON else parsed),
+    )
+
+
+_NOT_JSON = object()
+
+
+def _safe_json(text: str) -> Any:
+    try:
+        return json.loads(text)
+    except ValueError:
+        return _NOT_JSON
+
+
+def _error_envelope(parsed: Any) -> tuple[str, str] | None:
+    """`{"error": {"code", "message"}}`, both there, or nothing."""
+    error = parsed.get("error") if is_object(parsed) else None
+    if not is_object(error):
+        return None
+    code, message = error.get("code"), error.get("message")
+    if (
+        not isinstance(code, str)
+        or not isinstance(message, str)
+        or not code
+        or not message
+    ):
+        return None
+    return code, message
+
+
+def parse_retry_after(header: str | None) -> float | None:
+    """Seconds. The date form of `Retry-After` reads as nothing."""
+    if not header:
+        return None
+    try:
+        seconds = float(header)
+    except ValueError:
+        return None
+    return seconds if math.isfinite(seconds) else None
+
+
+def should_retry(status: int) -> bool:
+    return status == 408 or status == 429 or status >= 500
+
+
+def backoff(attempt: int, last_error: BaseException | None) -> float:
+    """Exponential backoff with full jitter, unless the engine named a delay."""
+    retry_after = getattr(last_error, "retry_after", None)
+    if isinstance(retry_after, (int, float)):
+        return max(0.0, min(float(retry_after), MAX_BACKOFF))
+
+    ceiling = min(0.5 * 2.0 ** (attempt - 1), MAX_BACKOFF)
+    return random.random() * ceiling

meterbase/_json.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, TypeGuard
+
+
+def is_object(value: object) -> TypeGuard[dict[str, Any]]:
+    """A JSON object, as `json.loads` reads one."""
+    return isinstance(value, dict)
+
+
+def is_mapping(value: object) -> TypeGuard[Mapping[str, Any]]:
+    return isinstance(value, Mapping)
+
+
+def is_array(value: object) -> TypeGuard[list[Any]]:
+    """A JSON array, as `json.loads` reads one."""
+    return isinstance(value, list)

meterbase/_keys.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import secrets
+import uuid
+
+IDEMPOTENCY_WINDOW_MS = 60 * 60 * 1000
+"""How far the engine lets a key's timestamp sit from its own clock."""
+
+RESERVE_WINDOW_MS = 30 * 60 * 1000
+"""
+The same guard for a reservation id, and narrower on purpose: the id is minted
+at the call, and the engine has to leave room to commit the hold it names long
+after.
+"""
+
+
+def mint(at_ms: float) -> str:
+    """
+    A UUIDv7: 48 bits of Unix milliseconds, then the version and variant, then
+    74 random bits. `uuid.uuid4()` mints a v4, which carries no time, and
+    `uuid.uuid7()` reads this machine's clock, so this builds one from random
+    bytes.
+
+    `at_ms` is the engine's clock as the client knows it, not this machine's: a
+    device an hour out would otherwise mint keys the engine refuses.
+    """
+    raw = bytearray(secrets.token_bytes(16))
+
+    ms = max(0, int(at_ms))
+    raw[0:6] = (ms & 0xFFFF_FFFF_FFFF).to_bytes(6, "big")
+    raw[6] = (raw[6] & 0x0F) | 0x70  # version 7
+    raw[8] = (raw[8] & 0x3F) | 0x80  # variant 10
+
+    return str(uuid.UUID(bytes=bytes(raw)))
+
+
+def minted_at_ms(key: str) -> int:
+    """The millisecond a v7 carries in its first 48 bits."""
+    return int(key.replace("-", "")[:12], 16)

meterbase/_models.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import copy
+import keyword
+import types
+from collections.abc import Callable, Mapping
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    ClassVar,
+    Generic,
+    TypeVar,
+    Union,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from ._json import is_array, is_mapping, is_object
+from .errors import MeterbaseError
+
+_M = TypeVar("_M", bound="Model")
+_Convert = Callable[[Any], Any]
+
+
+class Model:
+    """
+    One JSON object the engine sent, as it sent it, read-only.
+
+    There is no translation layer between the two: `to_dict()` returns the
+    object exactly as it arrived, and `model["field"]` reads one field of it,
+    which is how to reach a field this release of the SDK does not know yet.
+    The attributes are the same values, typed. A field that is itself an object
+    reads as a model, and a list of them as a list of models.
+
+    A field named for a Python keyword takes a trailing underscore: `from_`
+    reads `from`.
+    """
+
+    _raw: dict[str, Any]
+
+    def __init__(self, raw: Mapping[str, Any]) -> None:
+        if not is_mapping(raw):
+            raise TypeError(
+                f"{type(self).__name__} reads a JSON object, not {type(raw).__name__}"
+            )
+
+        state = self.__dict__
+        state["_raw"] = data = dict(raw)
+        for attr, (key, convert) in _fields(type(self)).items():
+            if key in data:
+                state[attr] = convert(data[key])
+
+    def to_dict(self) -> dict[str, Any]:
+        """The object exactly as the engine sent it, as plain JSON types."""
+        return copy.deepcopy(self._raw)
+
+    def __getitem__(self, key: str) -> Any:
+        return self._raw[key]
+
+    def __contains__(self, key: object) -> bool:
+        return key in self._raw
+
+    def __eq__(self, other: object) -> bool:
+        # Equal to the same JSON, whether that arrives as a model or a dict.
+        if isinstance(other, Model):
+            return self._raw == other._raw
+        if is_mapping(other):
+            return self._raw == dict(other)
+        return NotImplemented
+
+    def __repr__(self) -> str:
+        attrs = {key: attr for attr, (key, _) in _fields(type(self)).items()}
+        shown = ", ".join(
+            f"{attrs[key]}={self.__dict__.get(attrs[key], value)!r}"
+            if key in attrs
+            else f"{key}={value!r}"
+            for key, value in self._raw.items()
+        )
+        return f"{type(self).__name__}({shown})"
+
+    if not TYPE_CHECKING:  # pragma: no branch
+        # Hidden from type checkers, which would otherwise take a class that
+        # defines these to accept any attribute at all.
+
+        def __setattr__(self, name, value):
+            raise AttributeError(f"{type(self).__name__} is read-only")
+
+        def __delattr__(self, name):
+            raise AttributeError(f"{type(self).__name__} is read-only")
+
+
+_T = TypeVar("_T")
+
+
+class ListResult(Model, Generic[_T]):
+    """Enveloped so pagination can arrive without breaking callers."""
+
+    data: list[_T]
+
+    def __init__(
+        self,
+        raw: Mapping[str, Any],
+        item: Callable[[Mapping[str, Any]], _T] | None = None,
+    ) -> None:
+        super().__init__(raw)
+        items = self._raw.get("data")
+        if item is not None and is_array(items):
+            self.__dict__["data"] = [
+                item(each) if is_mapping(each) else each for each in items
+            ]
+
+
+def list_of(item: type[_M]) -> Callable[[Mapping[str, Any]], ListResult[_M]]:
+    """Reads a listing whose rows are `item`."""
+    return lambda raw: ListResult(raw, item)
+
+
+def construct(cast_to: Callable[[dict[str, Any]], _T], data: Any) -> _T:
+    """Reads a response body as the object a call answers with."""
+    if not is_object(data):
+        raise MeterbaseError(
+            "The engine answered without the JSON object this call reads, "
+            f"sending {type(data).__name__} instead."
+        )
+    return cast_to(data)
+
+
+_FIELDS: dict[type[Model], dict[str, tuple[str, _Convert]]] = {}
+
+
+def _fields(cls: type[Model]) -> dict[str, tuple[str, _Convert]]:
+    """Each attribute a model declares, the wire key behind it, and how to read
+    that key's value."""
+    cached = _FIELDS.get(cls)
+    if cached is not None:
+        return cached
+
+    fields: dict[str, tuple[str, _Convert]] = {}
+    for attr, hint in get_type_hints(cls).items():
+        if attr.startswith("_") or get_origin(hint) is ClassVar:
+            continue
+        stem = attr[:-1]
+        key = stem if attr.endswith("_") and keyword.iskeyword(stem) else attr
+        fields[attr] = (key, _converter(hint))
+
+    _FIELDS[cls] = fields
+    return fields
+
+
+def _identity(value: Any) -> Any:
+    return value
+
+
+def _converter(hint: Any) -> _Convert:
+    origin = get_origin(hint)
+
+    if origin is Union or origin is types.UnionType:
+        shapes = [arg for arg in get_args(hint) if arg is not type(None)]
+        # A union of several shapes is left as sent: nothing here can tell
+        # which one a value is.
+        return _converter(shapes[0]) if len(shapes) == 1 else _identity
+
+    if origin is list:
+        args = get_args(hint)
+        read_item = _converter(args[0]) if args else _identity
+        if read_item is _identity:
+            return _identity
+        return lambda value: (
+            [read_item(each) for each in value] if is_array(value) else value
+        )
+
+    if origin is None and isinstance(hint, type) and issubclass(hint, Model):
+        model = hint
+        return lambda value: model(value) if is_mapping(value) else value
+
+    return _identity

meterbase/_not_given.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import Final
+
+
+class NotGiven:
+    """
+    A parameter the caller left out, which is not the same as `None`.
+
+    The engine reads an omitted field and a `null` differently where it reads
+    `null` at all: `thresholds=None` goes back to inheriting, and leaving
+    `thresholds` out keeps the stored list. So an omitted parameter is not
+    sent, and `None` is sent as `null`. Every optional parameter defaults to
+    `NOT_GIVEN`, and only the ones where `null` means something accept `None`.
+    """
+
+    _instance: NotGiven | None = None
+
+    def __new__(cls) -> NotGiven:
+        # One value, so `is NOT_GIVEN` holds for a copy and a pickle too.
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "NOT_GIVEN"
+
+    def __reduce__(self) -> str:
+        return "NOT_GIVEN"
+
+
+NOT_GIVEN: Final = NotGiven()

meterbase/_sync/__init__.py

@@ -0,0 +1,4 @@
+# Generated by scripts/unasync.py from
+# src/meterbase/_async/__init__.py.
+# Do not edit: change the async source, then run `make unasync`.
+

meterbase/_sync/_io.py

@@ -0,0 +1,21 @@
+"""
+What the sync client does that the async one does differently, kept out of the
+code `scripts/unasync.py` generates. `_async/_io.py` is its twin, and like this
+file is written by hand.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import TypeVar
+
+_A = TypeVar("_A")
+_B = TypeVar("_B")
+
+sleep = time.sleep
+
+
+def both(first: _A, second: _B) -> tuple[_A, _B]:
+    """Two calls' answers. The async client makes them at once; here they have
+    already been made, one after the other."""
+    return first, second