schedule-bit 0.1.0__py3-none-any.whl

schedule_bit/__init__.py

@@ -0,0 +1,57 @@
+"""The schedule-bit API from Python.
+
+    from schedule_bit import Client, Slots
+
+    with Client() as api:                      # key from SCHEDULE_BIT_API_KEY
+        api.create_world(name="room-1", preset="temporal-hour")
+        api.declare_occupier("room-1", name="omar")
+        receipt = api.claim("room-1", who="omar", date="2026-10-15", slots=Slots.range(9, 11))
+
+See https://api.schedule-bit.io/v1/docs for every operation; each one is a method
+here, in ``snake_case`` (``explainClaim`` is ``explain_claim``).
+"""
+
+from ._client import DEFAULT_BASE_URL, AsyncClient, Client
+from ._generated import models
+from ._options import RequestOptions
+from ._redact import redact
+from ._version import __version__
+from .errors import (
+    ApiError,
+    Cancelled,
+    LocalTimeError,
+    NetworkError,
+    RateLimited,
+    Refusal,
+    ScheduleBitError,
+    TimeoutError,
+)
+from .local_time import local_day, local_hour, local_slot
+from .masks import Slots
+from .rate_limit import RateLimit, TokenBucket
+from .retry import RetryPolicy
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "ApiError",
+    "AsyncClient",
+    "Cancelled",
+    "Client",
+    "LocalTimeError",
+    "NetworkError",
+    "RateLimit",
+    "RateLimited",
+    "Refusal",
+    "RequestOptions",
+    "RetryPolicy",
+    "ScheduleBitError",
+    "Slots",
+    "TimeoutError",
+    "TokenBucket",
+    "__version__",
+    "local_day",
+    "local_hour",
+    "local_slot",
+    "models",
+    "redact",
+]

schedule_bit/_client.py

@@ -0,0 +1,444 @@
+"""`Client` and `AsyncClient`: the generated operations over one careful transport."""
+
+from __future__ import annotations
+
+import asyncio
+import datetime
+import json
+import os
+import random
+import time
+import uuid
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator, Mapping
+from typing import Any, TypeVar
+from urllib.parse import quote
+
+import httpx
+from pydantic import BaseModel
+
+from ._generated import models
+from ._generated.operations import OPS, AsyncOperations, Operation, SyncOperations
+from ._options import RequestOptions
+from ._redact import redact
+from ._version import __version__
+from .errors import ApiError, Cancelled, NetworkError, Refusal, TimeoutError, error_for
+from .rate_limit import RateLimit, TokenBucket
+from .retry import RetryPolicy, should_retry, wait_for
+
+DEFAULT_BASE_URL = "https://api.schedule-bit.io"
+DEFAULT_TIMEOUT = 30.0
+USER_AGENT = f"schedule-bit-python/{__version__}"
+
+T = TypeVar("T")
+
+
+def _query_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (datetime.date, datetime.datetime)):
+        return value.isoformat()
+    if isinstance(value, (list, tuple)):
+        return ",".join(_query_value(v) for v in value)  # form, explode: false
+    return str(value)
+
+
+class _ServerSentEvents:
+    """``text/event-stream`` lines in, one `AssistEvent` per blank-line-ended event out."""
+
+    def __init__(self) -> None:
+        self._data: list[str] = []
+
+    def feed(self, line: str) -> list[models.AssistEvent]:
+        if line == "":
+            return self.end()
+        if line.startswith("data:"):
+            self._data.append(line[5:].lstrip(" "))
+        return []
+
+    def end(self) -> list[models.AssistEvent]:
+        if not self._data:
+            return []
+        event = models.AssistEvent.model_validate(json.loads("\n".join(self._data)))
+        self._data = []
+        return [event]
+
+
+class _Base:
+    """Configuration and request building shared by both clients."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        retry: RetryPolicy | None = None,
+        max_retries: int | None = None,
+        rate_limit_per_minute: float | None = None,
+        on_rate_limit: Callable[[RateLimit], None] | None = None,
+        headers: Mapping[str, str] | None = None,
+        clock: Callable[[], float] = time.time,
+        rng: random.Random | None = None,
+    ) -> None:
+        key = api_key if api_key is not None else os.environ.get("SCHEDULE_BIT_API_KEY")
+        self._api_key = key or None
+        self.base_url = (base_url or os.environ.get("SCHEDULE_BIT_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        policy = retry or RetryPolicy()
+        if max_retries is not None:
+            policy = RetryPolicy(max_retries=max_retries, base=policy.base, cap=policy.cap)
+        self.retry = policy
+        self.bucket = TokenBucket(rate_limit_per_minute) if rate_limit_per_minute else None
+        self.on_rate_limit = on_rate_limit
+        self.rate_limit: RateLimit | None = None
+        self._extra_headers = dict(headers or {})
+        self._clock = clock
+        self._rng = rng or random.Random()
+
+    def __repr__(self) -> str:
+        key = "set" if self._api_key else "none"
+        return f"{type(self).__name__}(base_url={self.base_url!r}, api_key=<{key}>)"
+
+    # -- building -----------------------------------------------------------------
+
+    def _url(self, op: Operation, path: Mapping[str, str]) -> str:
+        filled = op.path
+        for name, value in path.items():
+            filled = filled.replace("{" + name + "}", quote(str(value), safe=""))
+        return self.base_url + filled
+
+    def _headers(self, op: Operation, opts: RequestOptions, has_body: bool, key: str | None) -> dict[str, str]:
+        headers = {"Accept": "application/json, application/problem+json", "User-Agent": USER_AGENT}
+        if self._api_key:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+        if has_body:
+            headers["Content-Type"] = "application/json"
+        if key:
+            headers["Idempotency-Key"] = key
+        headers.update(self._extra_headers)
+        headers.update(opts.headers)
+        return headers
+
+    def _request(
+        self, op: Operation, path: Mapping[str, str], query: Mapping[str, Any], body: Any, opts: RequestOptions
+    ) -> httpx.Request:
+        # One key per call, reused across its retries.
+        key = opts.idempotency_key or (str(uuid.uuid4()) if op.keyed else None)
+        params = {k: _query_value(v) for k, v in query.items() if v is not None}
+        content = json.dumps(body).encode() if body is not None else None
+        timeout = opts.timeout if opts.timeout is not None else self.timeout
+        return httpx.Request(
+            op.method,
+            self._url(op, path),
+            params=params,
+            content=content,
+            headers=self._headers(op, opts, body is not None, key),
+            extensions={"timeout": httpx.Timeout(timeout).as_dict()},
+        )
+
+    def _observe(self, response: httpx.Response) -> None:
+        limit = RateLimit.from_headers(response.headers)
+        if limit is not None:
+            self.rate_limit = limit
+            if self.on_rate_limit:
+                self.on_rate_limit(limit)
+
+    def _retries(self, opts: RequestOptions) -> int:
+        return self.retry.max_retries if opts.max_retries is None else opts.max_retries
+
+    # -- answers ------------------------------------------------------------------
+
+    @staticmethod
+    def _decode(response: httpx.Response) -> Any:
+        if not response.content:
+            return None
+        ctype = response.headers.get("content-type", "")
+        if "json" in ctype:
+            try:
+                return response.json()
+            except ValueError:
+                return response.text
+        return response.text
+
+    def _error(self, response: httpx.Response, request: httpx.Request) -> ApiError:
+        return error_for(
+            response.status_code,
+            self._decode(response),
+            method=request.method,
+            url=str(request.url),
+            rate_limit=RateLimit.from_headers(response.headers),
+        )
+
+    @staticmethod
+    def _parse(op: Operation, response: httpx.Response, parse: type[BaseModel] | None) -> Any:
+        if op.answer == "empty" or not response.content:
+            return None
+        if op.answer == "text":
+            return response.text
+        data = response.json()
+        return parse.model_validate(data) if parse is not None else data
+
+    @staticmethod
+    def _network(exc: Exception, request: httpx.Request, attempts: int) -> NetworkError:
+        kind = TimeoutError if isinstance(exc, httpx.TimeoutException) else NetworkError
+        what = type(exc).__name__
+        return kind(
+            f"{request.method} {redact(str(request.url))}: no answer after {attempts} attempt(s) ({what}: {exc})"
+        )
+
+    @staticmethod
+    def _sse_events(lines: Iterator[str]) -> Iterator[models.AssistEvent]:
+        parser = _ServerSentEvents()
+        for line in lines:
+            yield from parser.feed(line)
+        yield from parser.end()
+
+
+class Client(_Base, SyncOperations):
+    """The schedule-bit API, synchronously.
+
+    >>> from schedule_bit import Client
+    >>> api = Client("sbk_…")            # or set SCHEDULE_BIT_API_KEY
+    >>> api.claim("room-1", who="omar", date="2026-10-15", slots=[9, 10])
+
+    Every call retries 429/503 (and, when it is safe, network failures and other
+    5xx) with jittered back-off, honours ``Retry-After``, sends an
+    ``Idempotency-Key`` on keyed writes, and raises a typed error otherwise.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        http: httpx.Client | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(api_key, **kwargs)
+        self._http = http or httpx.Client()
+        self._sleep = sleep
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _wait(self, seconds: float, opts: RequestOptions) -> None:
+        if opts.cancel is not None:
+            if opts.cancel.wait(seconds):
+                raise Cancelled("cancelled while waiting to retry")
+        else:
+            self._sleep(seconds)
+
+    def _send(
+        self, op: Operation, request: httpx.Request, opts: RequestOptions, *, stream: bool = False
+    ) -> httpx.Response:
+        retries = self._retries(opts)
+        attempt = 0
+        while True:
+            if opts.cancel is not None and opts.cancel.is_set():
+                raise Cancelled(f"{op.id} cancelled")
+            if self.bucket:
+                self.bucket.acquire()
+            try:
+                response = self._http.send(request, stream=stream)
+            except httpx.TransportError as exc:
+                if attempt >= retries or not should_retry(op, None):
+                    raise self._network(exc, request, attempt + 1) from exc
+                self._wait(wait_for(self.retry, attempt, None, self._clock(), self._rng), opts)
+                attempt += 1
+                continue
+            self._observe(response)
+            if response.status_code < 400:
+                return response
+            if attempt >= retries or not should_retry(op, response.status_code):
+                if stream:
+                    response.read()
+                raise self._error(response, request)
+            delay = wait_for(self.retry, attempt, response.headers, self._clock(), self._rng)
+            response.close()
+            self._wait(delay, opts)
+            attempt += 1
+
+    def _call(
+        self,
+        op: Operation,
+        path: dict[str, str],
+        query: dict[str, Any],
+        body: Any,
+        options: RequestOptions | None,
+        parse: Any,
+    ) -> Any:
+        opts = options or RequestOptions()
+        request = self._request(op, path, query, body, opts)
+        return self._parse(op, self._send(op, request, opts), parse)
+
+    def _stream(
+        self, op: Operation, path: dict[str, str], query: dict[str, Any], body: Any, options: RequestOptions | None
+    ) -> Iterator[models.AssistEvent]:
+        opts = options or RequestOptions()
+        request = self._request(op, path, query, body, opts)
+        request.headers["Accept"] = "text/event-stream"
+
+        def events() -> Iterator[models.AssistEvent]:
+            response = self._send(op, request, opts, stream=True)
+            try:
+                yield from self._sse_events(response.iter_lines())
+            finally:
+                response.close()
+
+        return events()
+
+    # -- the expected outcomes, as values -----------------------------------------
+
+    def try_claim(
+        self, w: str, body: Any = None, /, *, options: RequestOptions | None = None, **fields: Any
+    ) -> models.Receipt | Refusal:
+        """`claim`, but a refusal is returned rather than raised."""
+        try:
+            return self.claim(w, body, options=options, **fields)
+        except Refusal as refusal:
+            return refusal
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        body: Any = None,
+        options: RequestOptions | None = None,
+        idempotent: bool = False,
+    ) -> Any:
+        """Any path, with the same retries and errors: for an operation newer than this SDK."""
+        op = Operation(f"{method} {path}", method.upper(), path, "json", idempotent)
+        return self._call(op, {}, dict(query or {}), body, options, None)
+
+    def watch(self, w: str, **kwargs: Any) -> Any:
+        """A live, resuming iterator of this World's frames; needs ``schedule-bit[watch]``."""
+        from .watch import Watch
+
+        return Watch(self, w, **kwargs)
+
+
+class AsyncClient(_Base, AsyncOperations):
+    """The schedule-bit API, with asyncio. Same behaviour as `Client`; cancel a call by cancelling its task."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        http: httpx.AsyncClient | None = None,
+        sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(api_key, **kwargs)
+        self._http = http or httpx.AsyncClient()
+        self._sleep = sleep
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def _send(
+        self, op: Operation, request: httpx.Request, opts: RequestOptions, *, stream: bool = False
+    ) -> httpx.Response:
+        retries = self._retries(opts)
+        attempt = 0
+        while True:
+            if self.bucket:
+                await self.bucket.acquire_async()
+            try:
+                response = await self._http.send(request, stream=stream)
+            except httpx.TransportError as exc:
+                if attempt >= retries or not should_retry(op, None):
+                    raise self._network(exc, request, attempt + 1) from exc
+                await self._sleep(wait_for(self.retry, attempt, None, self._clock(), self._rng))
+                attempt += 1
+                continue
+            self._observe(response)
+            if response.status_code < 400:
+                return response
+            if attempt >= retries or not should_retry(op, response.status_code):
+                if stream:
+                    await response.aread()
+                raise self._error(response, request)
+            delay = wait_for(self.retry, attempt, response.headers, self._clock(), self._rng)
+            await response.aclose()
+            await self._sleep(delay)
+            attempt += 1
+
+    async def _call(
+        self,
+        op: Operation,
+        path: dict[str, str],
+        query: dict[str, Any],
+        body: Any,
+        options: RequestOptions | None,
+        parse: Any,
+    ) -> Any:
+        opts = options or RequestOptions()
+        request = self._request(op, path, query, body, opts)
+        return self._parse(op, await self._send(op, request, opts), parse)
+
+    def _stream(
+        self, op: Operation, path: dict[str, str], query: dict[str, Any], body: Any, options: RequestOptions | None
+    ) -> AsyncIterator[models.AssistEvent]:
+        opts = options or RequestOptions()
+        request = self._request(op, path, query, body, opts)
+        request.headers["Accept"] = "text/event-stream"
+
+        async def events() -> AsyncIterator[models.AssistEvent]:
+            response = await self._send(op, request, opts, stream=True)
+            parser = _ServerSentEvents()
+            try:
+                async for line in response.aiter_lines():
+                    for event in parser.feed(line):
+                        yield event
+                for event in parser.end():
+                    yield event
+            finally:
+                await response.aclose()
+
+        return events()
+
+    async def try_claim(
+        self, w: str, body: Any = None, /, *, options: RequestOptions | None = None, **fields: Any
+    ) -> models.Receipt | Refusal:
+        """`claim`, but a refusal is returned rather than raised."""
+        try:
+            return await self.claim(w, body, options=options, **fields)
+        except Refusal as refusal:
+            return refusal
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        body: Any = None,
+        options: RequestOptions | None = None,
+        idempotent: bool = False,
+    ) -> Any:
+        """Any path, with the same retries and errors: for an operation newer than this SDK."""
+        op = Operation(f"{method} {path}", method.upper(), path, "json", idempotent)
+        return await self._call(op, {}, dict(query or {}), body, options, None)
+
+    def watch(self, w: str, **kwargs: Any) -> Any:
+        """A live, resuming async iterator of this World's frames; needs ``schedule-bit[watch]``."""
+        from .watch import AsyncWatch
+
+        return AsyncWatch(self, w, **kwargs)
+
+
+__all__ = ["DEFAULT_BASE_URL", "OPS", "AsyncClient", "Client"]

schedule_bit/_generated/__init__.py

@@ -0,0 +1,2 @@
+# Generated by sdks/python/scripts/generate.py from sdks/spec/openapi.json. Do not edit.
+"""Code generated from the contract: models and one method per operation."""