flowion 0.2.0__py3-none-any.whl

flowion/__init__.py

@@ -0,0 +1,56 @@
+"""The Flowion API client for Python.
+
+Async-first, standard library only. Bring your own HTTP library through the
+`Transport` protocol, or use the `aiohttp` adapter (`pip install "flowion[aiohttp]"`,
+`flowion.aiohttp_transport.AiohttpTransport`) over a session you already have.
+The public-client OAuth helpers live in `flowion.oauth`.
+"""
+
+from flowion.client import Client, TokenProvider
+from flowion.clock import Clock, SystemClock
+from flowion.errors import (
+    AccessDenied,
+    ApiError,
+    DecodeError,
+    FlowionError,
+    InvalidClient,
+    InvalidGrant,
+    InvalidRequest,
+    OAuthError,
+    RateLimitedError,
+    StateMismatch,
+)
+from flowion.oauth import AuthorizationRequest, AuthorizationResult, OAuthClient, TokenSet
+from flowion.rate_limit import RateLimit
+from flowion.retry import RetryPolicy
+from flowion.sse import EventStream
+from flowion.transport import Request, Response, StreamResponse, Transport, TransportError
+
+__all__ = [
+    "AccessDenied",
+    "ApiError",
+    "AuthorizationRequest",
+    "AuthorizationResult",
+    "Client",
+    "Clock",
+    "DecodeError",
+    "EventStream",
+    "FlowionError",
+    "InvalidClient",
+    "InvalidGrant",
+    "InvalidRequest",
+    "OAuthClient",
+    "OAuthError",
+    "RateLimit",
+    "RateLimitedError",
+    "Request",
+    "Response",
+    "RetryPolicy",
+    "StateMismatch",
+    "StreamResponse",
+    "SystemClock",
+    "TokenProvider",
+    "TokenSet",
+    "Transport",
+    "TransportError",
+]

flowion/_json.py

@@ -0,0 +1,145 @@
+"""The JSON value model and the strict readers generated code decodes with.
+
+This module is one half of the seam between ``flowion.generated`` (emitted,
+never hand-edited) and the runtime; its shape is fixed by
+``specs/167-python-sdk/contracts/generated-runtime-interface.md``.
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from typing import Final
+
+__all__ = [
+    "UNSET",
+    "DecodePathError",
+    "JsonValue",
+    "Unset",
+    "expect_bool",
+    "expect_date",
+    "expect_datetime",
+    "expect_int",
+    "expect_list",
+    "expect_number",
+    "expect_object",
+    "expect_str",
+]
+
+JsonValue = None | bool | int | float | str | list["JsonValue"] | dict[str, "JsonValue"]
+
+
+class Unset:
+    """The marker for "leave this field unchanged" in a patch (``None`` clears it)."""
+
+    __slots__ = ()
+    _instance: Unset | None = None
+
+    def __new__(cls) -> Unset:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "UNSET"
+
+    def __bool__(self) -> bool:
+        return False
+
+    def __copy__(self) -> Unset:
+        return self
+
+    def __deepcopy__(self, memo: object) -> Unset:
+        return self
+
+
+UNSET: Final[Unset] = Unset()
+
+
+class DecodePathError(ValueError):
+    """A value did not have the shape the contract declares.
+
+    ``path`` locates it inside the response body, for example ``data[3].state``
+    (empty for the body itself). The client turns this into the public
+    ``DecodeError``.
+    """
+
+    path: str
+
+    def __init__(self, path: str, message: str) -> None:
+        super().__init__(f"{path or '<body>'}: {message}")
+        self.path = path
+        self.message = message
+
+
+def _describe(value: JsonValue) -> str:
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "a boolean"
+    if isinstance(value, int):
+        return "an integer"
+    if isinstance(value, float):
+        return "a number"
+    if isinstance(value, str):
+        return "a string"
+    if isinstance(value, list):
+        return "an array"
+    return "an object"
+
+
+def expect_object(value: JsonValue, path: str) -> dict[str, JsonValue]:
+    if not isinstance(value, dict):
+        raise DecodePathError(path, f"expected an object, got {_describe(value)}")
+    return value
+
+
+def expect_list(value: JsonValue, path: str) -> list[JsonValue]:
+    if not isinstance(value, list):
+        raise DecodePathError(path, f"expected an array, got {_describe(value)}")
+    return value
+
+
+def expect_str(value: JsonValue, path: str) -> str:
+    if not isinstance(value, str):
+        raise DecodePathError(path, f"expected a string, got {_describe(value)}")
+    return value
+
+
+def expect_int(value: JsonValue, path: str) -> int:
+    """An integer: ``True`` and ``2.0`` are both refused."""
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise DecodePathError(path, f"expected an integer, got {_describe(value)}")
+    return value
+
+
+def expect_number(value: JsonValue, path: str) -> float:
+    """An int or a float, never a bool."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise DecodePathError(path, f"expected a number, got {_describe(value)}")
+    return float(value)
+
+
+def expect_bool(value: JsonValue, path: str) -> bool:
+    if not isinstance(value, bool):
+        raise DecodePathError(path, f"expected a boolean, got {_describe(value)}")
+    return value
+
+
+def expect_datetime(value: JsonValue, path: str) -> datetime:
+    """An RFC 3339 timestamp. The offset is required and the result is aware."""
+    text = expect_str(value, path)
+    try:
+        stamp = datetime.fromisoformat(text)
+    except ValueError:
+        raise DecodePathError(path, f"expected an RFC 3339 timestamp, got {text!r}") from None
+    if stamp.tzinfo is None:
+        raise DecodePathError(path, f"expected a timestamp with an offset, got {text!r}")
+    return stamp
+
+
+def expect_date(value: JsonValue, path: str) -> date:
+    text = expect_str(value, path)
+    try:
+        return date.fromisoformat(text)
+    except ValueError:
+        raise DecodePathError(path, f"expected a date (YYYY-MM-DD), got {text!r}") from None

flowion/_operation.py

@@ -0,0 +1,87 @@
+"""What generated operations describe, and what they call.
+
+This module is the other half of the seam between ``flowion.generated`` and
+the runtime; its shape is fixed by
+``specs/167-python-sdk/contracts/generated-runtime-interface.md``. ``Caller`` is
+implemented by the client (``flowion/client.py``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable, Mapping
+from dataclasses import dataclass
+from typing import Literal, Protocol
+
+from flowion._json import JsonValue
+
+__all__ = ["Caller", "OperationSpec"]
+
+
+@dataclass(frozen=True, slots=True)
+class OperationSpec:
+    """One operation of the contract, as the runtime needs to send it."""
+
+    operation_id: str
+    """snake_case, as in ``openapi.json``."""
+    method: str
+    """``"GET"``, ``"POST"``, ..."""
+    path: str
+    """The path template, for example ``/v1/charging-stations/{chargingStationId}``."""
+    response: Literal["json", "text", "stream", "empty"]
+    """``empty`` is a ``204`` or a response with no body."""
+    success_statuses: tuple[int, ...]
+    """``(200,)``, ``(200, 201)`` or ``(200, 204)``."""
+    decode: Callable[[JsonValue], object] | None
+    """Decodes the response body; ``None`` unless ``response == "json"``."""
+    paginated_item: Callable[[JsonValue], object] | None
+    """Decodes one item when the response is a cursor page, else ``None``."""
+    request_body: Literal["none", "json"]
+
+
+class Caller(Protocol):
+    """The transport-facing half that generated groups call."""
+
+    async def call(
+        self,
+        spec: OperationSpec,
+        *,
+        path: Mapping[str, str] = ...,
+        query: Mapping[str, JsonValue] = ...,
+        body: JsonValue = None,
+        headers: Mapping[str, str] = ...,
+    ) -> object:
+        """Send ``spec`` and return what ``spec.decode`` returned.
+
+        ``str`` for ``text``, ``None`` for ``empty``. Query values that are
+        ``None`` are omitted and lists are repeated parameters; path values are
+        percent-encoded here, not by the caller.
+        """
+        ...
+
+    def paginate(
+        self,
+        spec: OperationSpec,
+        *,
+        path: Mapping[str, str] = ...,
+        query: Mapping[str, JsonValue] = ...,
+        headers: Mapping[str, str] = ...,
+    ) -> AsyncIterator[object]:
+        """Yield each item of every page, decoded by ``spec.paginated_item``."""
+        ...
+
+    def stream(
+        self,
+        spec: OperationSpec,
+        *,
+        path: Mapping[str, str] = ...,
+        query: Mapping[str, JsonValue] = ...,
+        body: JsonValue = None,
+        headers: Mapping[str, str] = ...,
+    ) -> AsyncIterator[object]:
+        """Yield the parsed JSON payload of each ``data:`` frame.
+
+        ``body`` is the JSON request body of a streaming operation that takes
+        one (the assistant's ``send_*_message`` POSTs): the contract's
+        original ``stream`` signature had no body.
+        """
+        ...

flowion/_wire.py

@@ -0,0 +1,55 @@
+"""Small shared helpers for reading what came off the wire. Private to the runtime."""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Mapping
+from urllib.parse import urlsplit
+
+from flowion._json import JsonValue
+from flowion.errors import EXCERPT_LIMIT
+
+__all__ = ["LOGGER", "excerpt_of", "parse_json", "path_of", "request_id_of"]
+
+# The one logger of the SDK. DEBUG only: method, path, status and request id.
+# Never a header, a body, a token or a query string.
+LOGGER = logging.getLogger("flowion")
+
+
+def parse_json(body: bytes) -> JsonValue:
+    """The body as JSON; `ValueError` (which `UnicodeDecodeError` is) when it is not."""
+    try:
+        value: JsonValue = json.loads(body.decode("utf-8"))
+    except RecursionError:
+        raise ValueError("JSON nested too deeply") from None
+    return value
+
+
+def best_effort_json(body: bytes) -> JsonValue:
+    """The body as JSON, or `None` when it is empty or not JSON (for error bodies)."""
+    if not body:
+        return None
+    try:
+        return parse_json(body)
+    except ValueError:
+        return None
+
+
+def excerpt_of(body: bytes) -> str:
+    """The start of a body as text, bounded to 512 characters; undecodable bytes become U+FFFD."""
+    return body[: EXCERPT_LIMIT * 4].decode("utf-8", errors="replace")[:EXCERPT_LIMIT]
+
+
+def path_of(url: str) -> str:
+    """The path of a URL, for logging: never the query string."""
+    return urlsplit(url).path
+
+
+def request_id_of(headers: Mapping[str, str], body: JsonValue) -> str | None:
+    """The request's id, from the error body or the `x-request-id` header."""
+    if isinstance(body, dict):
+        in_body = body.get("requestId")
+        if isinstance(in_body, str):
+            return in_body
+    return headers.get("x-request-id")

flowion/aiohttp_transport.py

@@ -0,0 +1,96 @@
+"""A `Transport` over an existing `aiohttp.ClientSession` (the optional `aiohttp` extra).
+
+    from flowion.aiohttp_transport import AiohttpTransport
+    client = Client(transport=AiohttpTransport(session))   # session: owned by the caller
+
+The session belongs to the caller and may be shared with other components (Home
+Assistant's is). This adapter therefore only ever calls `session.request(...)`
+with the headers and timeout of that one request: it never touches
+`session.headers`, never writes the cookie jar, never closes anything. It cannot
+stop aiohttp sending a cookie the session already holds, and does not try; the
+gateway is bearer-only and cookie-free, which is what makes sharing safe.
+
+Needs aiohttp 3.9.0 or newer: `pip install "flowion[aiohttp]"`.
+"""
+
+from __future__ import annotations
+
+try:
+    import aiohttp
+except ImportError as error:  # pragma: no cover - exercised by blocking the import in a test
+    raise ImportError(
+        'flowion.aiohttp_transport needs the aiohttp package: pip install "flowion[aiohttp]"'
+    ) from error
+
+import asyncio
+from collections.abc import AsyncGenerator, AsyncIterator, Mapping
+from contextlib import asynccontextmanager
+from typing import Any
+
+from flowion.transport import Request, Response, StreamResponse, TransportError
+
+__all__ = ["AiohttpTransport"]
+
+
+def _lowercase(headers: Mapping[str, str] | Any) -> dict[str, str]:
+    """Lowercase names; a repeated header is joined with ", " as HTTP allows."""
+    merged: dict[str, str] = {}
+    for name, value in headers.items():
+        key = str(name).lower()
+        merged[key] = f"{merged[key]}, {value}" if key in merged else str(value)
+    return merged
+
+
+class AiohttpTransport:
+    """Sends the SDK's requests through the caller's `aiohttp.ClientSession`."""
+
+    def __init__(self, session: aiohttp.ClientSession) -> None:
+        self._session = session
+
+    def __repr__(self) -> str:
+        return "AiohttpTransport()"
+
+    def _options(self, request: Request, *, streaming: bool) -> dict[str, Any]:
+        options: dict[str, Any] = {
+            "headers": dict(request.headers),
+            "data": request.body,
+            "allow_redirects": False,
+        }
+        if request.timeout is not None:
+            options["timeout"] = aiohttp.ClientTimeout(total=request.timeout)
+        elif streaming:
+            # A live stream has no total deadline; the session's own default would cut it.
+            options["timeout"] = aiohttp.ClientTimeout(total=None)
+        return options
+
+    async def send(self, request: Request) -> Response:
+        try:
+            async with self._session.request(
+                request.method, request.url, **self._options(request, streaming=False)
+            ) as response:
+                body = await response.read()
+                return Response(status=response.status, headers=_lowercase(response.headers), body=body)
+        except (aiohttp.ClientError, asyncio.TimeoutError) as error:
+            raise TransportError(f"{type(error).__name__}: {error}") from error
+
+    @asynccontextmanager
+    async def stream(self, request: Request) -> AsyncGenerator[StreamResponse, None]:
+        try:
+            response = await self._session.request(request.method, request.url, **self._options(request, streaming=True))
+        except (aiohttp.ClientError, asyncio.TimeoutError) as error:
+            raise TransportError(f"{type(error).__name__}: {error}") from error
+        try:
+            yield StreamResponse(status=response.status, headers=_lowercase(response.headers), chunks=_chunks(response))
+        finally:
+            if response.content.at_eof():
+                response.release()
+            else:
+                response.close()
+
+
+async def _chunks(response: aiohttp.ClientResponse) -> AsyncIterator[bytes]:
+    try:
+        async for chunk in response.content.iter_any():
+            yield chunk
+    except (aiohttp.ClientError, asyncio.TimeoutError) as error:
+        raise TransportError(f"{type(error).__name__}: {error}") from error