flowion 0.2.0__py3-none-any.whl

flowion/client.py

@@ -0,0 +1,330 @@
+"""The Flowion client: builds requests, sends them through a `Transport`, decodes the answers.
+
+`Client` implements `flowion._operation.Caller`, the seam the generated code
+(`flowion.generated.api`) calls. It holds configuration only: no connection, no
+session, no token beyond the string (or provider) it was given, no refresh. A
+`401 invalidToken` is an `ApiError` the caller answers by refreshing.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import AsyncGenerator, AsyncIterator, Awaitable, Callable, Mapping
+from contextlib import asynccontextmanager
+from urllib.parse import quote, urlencode
+
+from flowion._json import DecodePathError, JsonValue
+from flowion._operation import OperationSpec
+from flowion._wire import LOGGER, best_effort_json, excerpt_of, parse_json, path_of, request_id_of
+from flowion.clock import Clock, SystemClock
+from flowion.generated.api import Api
+from flowion.generated.contract import CONTRACT_VERSION
+from flowion.errors import ApiError, DecodeError, FlowionError, RateLimitedError
+from flowion.pagination import RawPage, iterate_pages
+from flowion.rate_limit import RateLimit, parse_rate_limit
+from flowion.retry import RetryPolicy, send_with_retry, wait_before_retry
+from flowion.sse import EventStream
+from flowion.transport import Request, Response, StreamResponse, Transport
+
+__all__ = ["Client", "TokenProvider"]
+
+DEFAULT_BASE_URL = "https://api.flowion.io"
+
+# Awaited once per request, so a component's own refresh runs under its own lock.
+TokenProvider = Callable[[], Awaitable[str]]
+
+_ACCEPT = {
+    "json": "application/json",
+    "empty": "application/json",
+    "text": "text/csv",
+    "stream": "text/event-stream",
+}
+_PATH_PARAMETER = re.compile(r"\{([^}]+)\}")
+# How much of an error body is read from a stream that failed to open.
+_ERROR_BODY_LIMIT = 64 * 1024
+
+
+class Client(Api):
+    """The Flowion API client. Group attributes (`client.charging_stations`, ...) come from the generated tree.
+
+    ``Client(transport, base_url=..., token=..., retry=..., clock=..., mode=..., api_version=...)``
+
+    ``token`` is a string or a `TokenProvider` awaited per request. ``mode``
+    sends ``X-Flowion-Mode`` (for example ``"sandbox"``); ``api_version``
+    sends ``Api-Version`` (default: the contract version this SDK was generated against). ``timeout_seconds`` is the per-request timeout handed
+    to the transport (``None`` for the transport's own default); a live-event
+    stream has none.
+    """
+
+    def __init__(
+        self,
+        transport: Transport,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        token: str | TokenProvider | None = None,
+        retry: RetryPolicy = RetryPolicy(),
+        clock: Clock = SystemClock(),
+        mode: str | None = None,
+        api_version: str | None = None,
+        timeout_seconds: float | None = 30.0,
+    ) -> None:
+        if not base_url.startswith(("https://", "http://")):
+            raise ValueError("base_url must be an absolute http(s) URL")
+        self._transport = transport
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+        self._retry = retry
+        self._clock = clock
+        self._mode = mode
+        self._api_version = CONTRACT_VERSION if api_version is None else api_version
+        self._timeout = timeout_seconds
+        self._last_rate_limit: RateLimit | None = None
+        super().__init__(self)
+
+    def __repr__(self) -> str:
+        # Deliberately without the token.
+        return f"Client(base_url={self._base_url!r})"
+
+    @property
+    def last_rate_limit(self) -> RateLimit | None:
+        """The rate-limit headers of the most recent response (success or failure); `None` before any."""
+        return self._last_rate_limit
+
+    # ----- Caller ---------------------------------------------------------
+
+    async def call(
+        self,
+        spec: OperationSpec,
+        *,
+        path: Mapping[str, str] = {},
+        query: Mapping[str, JsonValue] = {},
+        body: JsonValue = None,
+        headers: Mapping[str, str] = {},
+    ) -> object:
+        if spec.response == "stream":
+            raise ValueError(f"{spec.operation_id} is a stream: use stream()")
+        response = await self._exchange(spec, path, query, body, headers)
+        return _decode(spec, response)
+
+    def paginate(
+        self,
+        spec: OperationSpec,
+        *,
+        path: Mapping[str, str] = {},
+        query: Mapping[str, JsonValue] = {},
+        headers: Mapping[str, str] = {},
+    ) -> AsyncIterator[object]:
+        decode_item = spec.paginated_item
+        if decode_item is None:
+            raise ValueError(f"{spec.operation_id} is not a cursor-paginated operation")
+
+        async def fetch(cursor: str | None) -> RawPage:
+            page_query = dict(query) if cursor is None else {**query, "cursor": cursor}
+            response = await self._exchange(spec, path, page_query, None, headers)
+            try:
+                value = parse_json(response.body)
+            except ValueError:
+                raise DecodeError(
+                    "the response was not JSON",
+                    status=response.status,
+                    request_id=request_id_of(response.headers, None),
+                    excerpt=excerpt_of(response.body),
+                ) from None
+            return RawPage(value, response.status, request_id_of(response.headers, value))
+
+        return iterate_pages(fetch, decode_item)
+
+    def stream(
+        self,
+        spec: OperationSpec,
+        *,
+        path: Mapping[str, str] = {},
+        query: Mapping[str, JsonValue] = {},
+        body: JsonValue = None,
+        headers: Mapping[str, str] = {},
+    ) -> AsyncIterator[object]:
+        return EventStream(lambda: self._open_stream(spec, path, query, body, headers), spec.decode)
+
+    # ----- requests -------------------------------------------------------
+
+    async def _request(
+        self,
+        spec: OperationSpec,
+        path: Mapping[str, str],
+        query: Mapping[str, JsonValue],
+        body: JsonValue,
+        extra: Mapping[str, str],
+    ) -> Request:
+        headers: dict[str, str] = {"Accept": _ACCEPT[spec.response]}
+        headers["Api-Version"] = self._api_version
+        token = await self._token_value()
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        if self._mode is not None:
+            headers["X-Flowion-Mode"] = self._mode
+        data: bytes | None = None
+        if spec.request_body == "json" and body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+        for name, value in extra.items():
+            for existing in [h for h in headers if h.lower() == name.lower()]:
+                del headers[existing]
+            headers[name] = value
+        return Request(
+            method=spec.method.upper(),
+            url=self._url(spec, path, query),
+            headers=headers,
+            body=data,
+            timeout=None if spec.response == "stream" else self._timeout,
+        )
+
+    async def _token_value(self) -> str | None:
+        token = self._token
+        if token is None or isinstance(token, str):
+            return token
+        return await token()
+
+    def _url(self, spec: OperationSpec, path: Mapping[str, str], query: Mapping[str, JsonValue]) -> str:
+        def fill(match: re.Match[str]) -> str:
+            name = match.group(1)
+            if name not in path:
+                raise ValueError(f"missing path parameter {name} for {spec.operation_id}")
+            return quote(path[name], safe="")
+
+        url = self._base_url + _PATH_PARAMETER.sub(fill, spec.path)
+        pairs = _query_pairs(query)
+        return f"{url}?{urlencode(pairs, quote_via=quote)}" if pairs else url
+
+    async def _exchange(
+        self,
+        spec: OperationSpec,
+        path: Mapping[str, str],
+        query: Mapping[str, JsonValue],
+        body: JsonValue,
+        headers: Mapping[str, str],
+    ) -> Response:
+        """Sends one operation with the shared 429 retry; returns a 2xx response or raises."""
+        request = await self._request(spec, path, query, body, headers)
+        try:
+            response = await send_with_retry(self._transport, request, retry=self._retry, clock=self._clock)
+        except RateLimitedError as error:
+            self._last_rate_limit = error.rate_limit
+            raise
+        self._last_rate_limit = parse_rate_limit(response.headers)
+        if not 200 <= response.status < 300:
+            raise failure_for(response.status, response.headers, response.body)
+        return response
+
+    @asynccontextmanager
+    async def _open_stream(
+        self,
+        spec: OperationSpec,
+        path: Mapping[str, str],
+        query: Mapping[str, JsonValue],
+        body: JsonValue,
+        headers: Mapping[str, str],
+    ) -> AsyncGenerator[StreamResponse, None]:
+        """Opens the stream, retrying a 429 like any request; yields a 2xx response."""
+        request = await self._request(spec, path, query, body, headers)
+        route = path_of(request.url)
+        attempt = 1
+        while True:
+            async with self._transport.stream(request) as response:
+                self._last_rate_limit = parse_rate_limit(response.headers)
+                if 200 <= response.status < 300:
+                    LOGGER.debug("%s %s -> %d (stream)", request.method, route, response.status)
+                    yield response
+                    return
+                failure = failure_for(response.status, response.headers, await _drain(response.chunks))
+                LOGGER.debug(
+                    "%s %s -> %d (request id %s, attempt %d)",
+                    request.method,
+                    route,
+                    response.status,
+                    getattr(failure, "request_id", None),
+                    attempt,
+                )
+                wait: float | None = None
+                if isinstance(failure, RateLimitedError):
+                    wait = wait_before_retry(self._retry, attempt, failure.rate_limit.retry_after_seconds)
+                if wait is None:
+                    raise failure
+            assert wait is not None  # only a retryable 429 leaves the stream context without raising or returning
+            await self._clock.sleep(wait)
+            attempt += 1
+
+
+def failure_for(status: int, headers: Mapping[str, str], body: bytes) -> FlowionError:
+    """The error for a non-2xx answer: 429 is rate limited, an error body is an API error, else undecodable."""
+    value = best_effort_json(body)
+    request_id = request_id_of(headers, value)
+    if status == 429:
+        return RateLimitedError(value, rate_limit=parse_rate_limit(headers), request_id=request_id)
+    if isinstance(value, dict):
+        code = value.get("error")
+        if isinstance(code, str):
+            return ApiError(status, code, value, request_id=request_id)
+    return DecodeError(
+        "the response carried no error body", status=status, request_id=request_id, excerpt=excerpt_of(body)
+    )
+
+
+def _decode(spec: OperationSpec, response: Response) -> object:
+    request_id = request_id_of(response.headers, None)
+    status = response.status
+    if spec.response == "empty":
+        return None
+    if spec.response == "text":
+        try:
+            return response.body.decode("utf-8")
+        except UnicodeDecodeError:
+            raise DecodeError("the response was not UTF-8 text", status=status, request_id=request_id) from None
+    if not response.body:
+        if status == 204:
+            return None
+        raise DecodeError("the response body was empty", status=status, request_id=request_id)
+    try:
+        value = parse_json(response.body)
+    except ValueError:
+        raise DecodeError(
+            "the response was not JSON", status=status, request_id=request_id, excerpt=excerpt_of(response.body)
+        ) from None
+    if spec.decode is None:
+        return value
+    try:
+        return spec.decode(value)
+    except DecodePathError as error:
+        raise DecodeError(
+            f"the response did not match the contract at {error}", status=status, request_id=request_id
+        ) from None
+    except ValueError as error:
+        raise DecodeError(f"the response could not be decoded: {error}", status=status, request_id=request_id) from None
+
+
+def _query_pairs(query: Mapping[str, JsonValue]) -> list[tuple[str, str]]:
+    pairs: list[tuple[str, str]] = []
+    for name, value in query.items():
+        for item in value if isinstance(value, list) else [value]:
+            if item is not None:
+                pairs.append((name, _query_text(item)))
+    return pairs
+
+
+def _query_text(value: JsonValue) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (int, float)):
+        return repr(value)
+    return json.dumps(value, separators=(",", ":"))
+
+
+async def _drain(chunks: AsyncIterator[bytes]) -> bytes:
+    data = b""
+    async for chunk in chunks:
+        data += chunk
+        if len(data) >= _ERROR_BODY_LIMIT:
+            break
+    return data

flowion/clock.py

@@ -0,0 +1,30 @@
+"""The clock the SDK reads and waits on, injectable so tests never sleep (R8)."""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import UTC, datetime
+from typing import Protocol
+
+__all__ = ["Clock", "SystemClock"]
+
+
+class Clock(Protocol):
+    def now(self) -> datetime:
+        """The current time, timezone-aware (UTC)."""
+        ...
+
+    async def sleep(self, seconds: float) -> None: ...
+
+
+class SystemClock:
+    """The real clock: `datetime.now(UTC)` and `asyncio.sleep`."""
+
+    def now(self) -> datetime:
+        return datetime.now(UTC)
+
+    async def sleep(self, seconds: float) -> None:
+        await asyncio.sleep(seconds)
+
+    def __repr__(self) -> str:
+        return "SystemClock()"

flowion/errors.py

@@ -0,0 +1,158 @@
+"""The error hierarchy: transport, rate limit, API error, undecodable response, OAuth.
+
+    FlowionError
+      TransportError        (flowion.transport) no response arrived
+      RateLimitedError      a 429 that was not, or could no longer be, retried
+      ApiError              a non-2xx answer carrying the platform's error body
+      DecodeError           a body the SDK cannot decode (status, request id, bounded excerpt)
+      OAuthError            the RFC 6749 failures of the token endpoint, and the redirect checks
+        AccessDenied, StateMismatch, InvalidGrant, InvalidClient, InvalidRequest
+
+No message, `repr` or attribute here ever holds a token, code, verifier or an
+`Authorization` header: callers hand these classes only what the platform sent
+in an error body, and a response body is never copied in unbounded.
+"""
+
+from __future__ import annotations
+
+from flowion._json import JsonValue
+from flowion.rate_limit import RateLimit
+
+__all__ = [
+    "AccessDenied",
+    "ApiError",
+    "DecodeError",
+    "FlowionError",
+    "InvalidClient",
+    "InvalidGrant",
+    "InvalidRequest",
+    "OAuthError",
+    "RateLimitedError",
+    "StateMismatch",
+]
+
+# How much of a body an error carries (spec Edge Cases: a bounded excerpt).
+EXCERPT_LIMIT = 512
+
+
+class FlowionError(Exception):
+    """Base of every error the SDK raises on purpose."""
+
+
+def _message_of(body: JsonValue, fallback: str) -> str:
+    if isinstance(body, dict):
+        message = body.get("message")
+        if isinstance(message, str):
+            return message[:200]
+    return fallback
+
+
+class RateLimitedError(FlowionError):
+    """A 429 that was not (or could no longer be) retried."""
+
+    status: int = 429
+
+    def __init__(
+        self,
+        body: JsonValue,
+        *,
+        rate_limit: RateLimit,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(f"429: {_message_of(body, 'too many requests')}")
+        self.body = body
+        self.rate_limit = rate_limit
+        self.request_id = request_id
+
+    @property
+    def retry_after_seconds(self) -> int | None:
+        """`Retry-After` in seconds; `None` when the header was absent or unparsable."""
+        return self.rate_limit.retry_after_seconds
+
+
+class ApiError(FlowionError):
+    """A non-2xx answer carrying the platform's error body.
+
+    `code` is the stable string the platform sent, verbatim, even one this SDK
+    does not know. `invalidToken` (a 401) is this error: the client does not
+    refresh and does not retry it; the caller does.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        body: JsonValue,
+        *,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(f"{status} {code}: {_message_of(body, f'request failed with status {status}')}")
+        self.status = status
+        self.code = code
+        self.body = body
+        self.request_id = request_id
+
+
+class DecodeError(FlowionError):
+    """A response the SDK cannot decode: HTML from a proxy, truncated JSON, a wrong shape.
+
+    `excerpt` is the start of the body, at most 512 characters; empty where the
+    body might hold a secret (the OAuth token endpoint).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        request_id: str | None = None,
+        excerpt: str = "",
+    ) -> None:
+        bounded = excerpt[:EXCERPT_LIMIT]
+        suffix = f" (body starts: {bounded!r})" if bounded else ""
+        super().__init__(f"{message}{f' [status {status}]' if status is not None else ''}{suffix}")
+        self.status = status
+        self.request_id = request_id
+        self.excerpt = bounded
+
+
+class OAuthError(FlowionError):
+    """A failure of the OAuth grant. `code` is the RFC 6749 error string the platform sent."""
+
+    def __init__(
+        self,
+        code: str,
+        *,
+        description: str | None = None,
+        status: int | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        text = f"oauth error {code}" + (f": {description[:200]}" if description else "")
+        super().__init__(text)
+        self.code = code
+        self.description = description
+        self.status = status
+        self.request_id = request_id
+
+
+class AccessDenied(OAuthError):
+    """The user (or the platform) declined the grant: `error=access_denied` on the redirect."""
+
+
+class StateMismatch(OAuthError):
+    """The redirect's `state` is not the one this flow started with: stop, send nothing."""
+
+    def __init__(self) -> None:
+        super().__init__("state_mismatch", description="the redirect's state does not match the one issued")
+
+
+class InvalidGrant(OAuthError):
+    """The grant is over (replayed, expired or revoked): authorize again."""
+
+
+class InvalidClient(OAuthError):
+    """The platform does not accept this `client_id`."""
+
+
+class InvalidRequest(OAuthError):
+    """The request or the redirect was malformed (for a redirect: no `code`)."""

flowion/generated/__init__.py

@@ -0,0 +1,8 @@
+"""The generated core of the SDK: emitted by ``flowion-codegen py``, never hand-edited.
+
+``types`` holds the models, enums and open unions, ``operations`` the
+``OPERATIONS`` table, ``api`` one class per resource group and the ``Api``
+aggregate, and ``contract`` the contract version and the list of open types.
+Regenerate with ``bazelisk build //sdks/codegen:py_client`` and copy
+``bazel-bin/sdks/codegen/py/*.py`` here.
+"""