lotse-client 0.0.0.dev0__py3-none-any.whl

lotse_client/__init__.py

@@ -0,0 +1,30 @@
+"""Async client for the control API of lotse, the media daemon for RTSP cameras and WebRTC viewers.
+
+`LotseClient` speaks the API over the daemon's Unix socket; the payload types
+are in `lotse_client.models`, generated with the command methods from the
+daemon's JSON Schema.
+"""
+
+from lotse_client.client import LotseClient
+from lotse_client.errors import (
+    ApiVersionError,
+    CannotConnectError,
+    CommandError,
+    ConnectionClosedError,
+    LotseError,
+    ProtocolError,
+)
+from lotse_client.subscription import Subscription
+from lotse_client.version import API_VERSION
+
+__all__ = [
+    "API_VERSION",
+    "ApiVersionError",
+    "CannotConnectError",
+    "CommandError",
+    "ConnectionClosedError",
+    "LotseClient",
+    "LotseError",
+    "ProtocolError",
+    "Subscription",
+]

lotse_client/_base.py

@@ -0,0 +1,19 @@
+"""The base class of every generated model.
+
+Encoding omits fields that are `None`: the daemon rejects a `null` where the
+Rust type has a default but no `Option` (a source's `options`, for one), and
+leaving a field out always means its default. Decoding ignores fields it does
+not know, because a newer daemon may add them without an API version bump.
+"""
+
+from mashumaro.config import BaseConfig
+from mashumaro.mixins.orjson import DataClassORJSONMixin
+
+
+class Model(DataClassORJSONMixin):
+    """A message type of the control API, encoded and decoded by mashumaro."""
+
+    class Config(BaseConfig):
+        """Leave out `None` when encoding."""
+
+        omit_none = True

lotse_client/_commands.py

@@ -0,0 +1,315 @@
+"""Every command of the control API as a typed method.
+
+Generated by `scripts/generate_commands.py` from `schema/api.json` and the
+models datamodel-code-generator made from it. Do not edit: change the Rust
+types in lotse, copy its bundle to `schema/`, then run `mise run schema` (or
+`uv run python scripts/generate_commands.py` in `python/`).
+
+A command named `domain/verb` is the method `verb` of the `domain` namespace
+(`stream/put` is `client.stream.put`); one without a slash is a method of the
+client. Each method builds the generated command class, sends it through the
+transport and decodes the result the bundle names for it. A subscribing
+command, one the bundle lists an event type for, returns a `Subscription` of
+those events instead.
+"""
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, Protocol
+
+from mashumaro.codecs.basic import BasicDecoder
+
+from lotse_client.models import (
+    AudioMode,
+    IceServer,
+    InfoCommand,
+    InfoResult,
+    Metrics,
+    MetricsGetCommand,
+    Orientation,
+    PingCommand,
+    SchemaCommand,
+    Session,
+    SessionAdoptCommand,
+    SessionCloseCommand,
+    SessionEvent,
+    SessionGetCommand,
+    SessionList,
+    SessionListCommand,
+    SourceSpec,
+    Stream,
+    StreamDeleteCommand,
+    StreamEvent,
+    StreamGetCommand,
+    StreamList,
+    StreamListCommand,
+    StreamPutCommand,
+    StreamPutResult,
+    StreamSubscribeCommand,
+    UnsubscribeCommand,
+    WebrtcCandidateCommand,
+    WebrtcOfferCommand,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from lotse_client._base import Model
+    from lotse_client.subscription import Subscription
+
+NEW = 0
+"""The `id` a method gives its command; the transport replaces it with the next id."""
+
+STREAM_EVENTS: BasicDecoder[StreamEvent] = BasicDecoder(StreamEvent)
+"""Decodes the events of `stream/subscribe`."""
+
+SESSION_EVENTS: BasicDecoder[SessionEvent] = BasicDecoder(SessionEvent)
+"""Decodes the events of `webrtc/offer`, `session/adopt`."""
+
+type Request = Callable[[Model], Awaitable[dict[str, Any]]]
+"""The transport's `_request`: sends a command, returns its `result`."""
+
+
+class Subscribe(Protocol):
+    """The transport's `_subscribe`: a subscribing command, its events."""
+
+    async def __call__[E](self, command: Model, events: BasicDecoder[E]) -> Subscription[E]: ...
+
+
+class MetricsCommands:
+    """The `metrics/...` commands, as `client.metrics.<verb>(...)`."""
+
+    def __init__(self, request: Request, subscribe: Subscribe) -> None:
+        """Bind the transport's two primitives."""
+        self._request = request
+        self._subscribe = subscribe
+
+    async def get(self) -> Metrics:
+        """`metrics/get`: process, worker and stream counters."""
+        command = MetricsGetCommand(id=NEW)
+        return Metrics.from_dict(await self._request(command))
+
+
+class StreamCommands:
+    """The `stream/...` commands, as `client.stream.<verb>(...)`."""
+
+    def __init__(self, request: Request, subscribe: Subscribe) -> None:
+        """Bind the transport's two primitives."""
+        self._request = request
+        self._subscribe = subscribe
+
+    async def put(
+        self,
+        *,
+        sources: list[SourceSpec],
+        stream_id: str,
+        audio: AudioMode = "auto",
+        orientation: Orientation = "no_transform",
+        preload: bool = False,
+    ) -> StreamPutResult:
+        """`stream/put`: the idempotent upsert of a stream's desired state.
+
+        Args:
+            sources: The sources, in order; the first that provides a kind wins.
+            stream_id: The stream, `^[A-Za-z0-9._-]{1,128}$`.
+            audio: Audio handling.
+            orientation: How the picture is turned for display. A change reaches the open
+                sessions too, from their next frame and without a new answer. Changing only
+                this never reconnects.
+            preload: Keep the source connected without viewers: connected at put and
+                reconnected after failures while set, so the first viewer gets a frame from
+                the warm GOP cache. Changing only this never reconnects; turning it off with
+                no viewers starts the linger.
+        """
+        command = StreamPutCommand(
+            id=NEW,
+            sources=sources,
+            stream_id=stream_id,
+            audio=audio,
+            orientation=orientation,
+            preload=preload,
+        )
+        return StreamPutResult.from_dict(await self._request(command))
+
+    async def get(self, *, stream_id: str) -> Stream:
+        """`stream/get`: one stream's state, sources, tracks and counters.
+
+        Args:
+            stream_id: The stream.
+        """
+        command = StreamGetCommand(id=NEW, stream_id=stream_id)
+        return Stream.from_dict(await self._request(command))
+
+    async def list(self) -> StreamList:
+        """`stream/list`: every stream, by id."""
+        command = StreamListCommand(id=NEW)
+        return StreamList.from_dict(await self._request(command))
+
+    async def delete(self, *, stream_id: str) -> None:
+        """`stream/delete`: removes a stream and closes its sessions; idempotent.
+
+        Args:
+            stream_id: The stream.
+        """
+        command = StreamDeleteCommand(id=NEW, stream_id=stream_id)
+        await self._request(command)
+
+    async def subscribe(self, *, stream_id: str | None = None) -> Subscription[StreamEvent]:
+        """`stream/subscribe`: a subscription to one stream's state, or every stream's.
+
+        Args:
+            stream_id: One stream, or all when absent.
+        """
+        command = StreamSubscribeCommand(id=NEW, stream_id=stream_id)
+        return await self._subscribe(command, STREAM_EVENTS)
+
+
+class WebrtcCommands:
+    """The `webrtc/...` commands, as `client.webrtc.<verb>(...)`."""
+
+    def __init__(self, request: Request, subscribe: Subscribe) -> None:
+        """Bind the transport's two primitives."""
+        self._request = request
+        self._subscribe = subscribe
+
+    async def offer(
+        self,
+        *,
+        sdp: str,
+        stream_id: str,
+        ice_servers: list[IceServer] | None = None,
+        session_id: str | None = None,
+    ) -> Subscription[SessionEvent]:
+        """`webrtc/offer`: opens a session.
+
+        The subscription's events carry the whole signaling conversation.
+
+        Args:
+            sdp: The browser's SDP offer.
+            stream_id: The stream to view.
+            ice_servers: Overrides the configured ICE servers for this session.
+            session_id: The client's session id, `^[A-Za-z0-9._-]{1,128}$`; a ULID when
+                absent.
+        """
+        command = WebrtcOfferCommand(
+            id=NEW, sdp=sdp, stream_id=stream_id, ice_servers=ice_servers, session_id=session_id
+        )
+        return await self._subscribe(command, SESSION_EVENTS)
+
+    async def candidate(
+        self,
+        *,
+        candidate: str,
+        session_id: str,
+        sdp_mid: str | None = None,
+        sdp_mline_index: int | None = None,
+    ) -> None:
+        """`webrtc/candidate`: a trickled candidate from the browser.
+
+        Taken only from the connection that owns the session.
+
+        Args:
+            candidate: The `candidate:` attribute value; empty is end-of-candidates.
+            session_id: The session.
+            sdp_mid: The media section, when the browser named it (a client may forward only
+                this string; BUNDLE makes it redundant).
+            sdp_mline_index: The media section's index.
+        """
+        command = WebrtcCandidateCommand(
+            id=NEW,
+            candidate=candidate,
+            session_id=session_id,
+            sdp_mid=sdp_mid,
+            sdp_mline_index=sdp_mline_index,
+        )
+        await self._request(command)
+
+
+class SessionCommands:
+    """The `session/...` commands, as `client.session.<verb>(...)`."""
+
+    def __init__(self, request: Request, subscribe: Subscribe) -> None:
+        """Bind the transport's two primitives."""
+        self._request = request
+        self._subscribe = subscribe
+
+    async def get(self, *, session_id: str) -> Session:
+        """`session/get`: one session's state.
+
+        Args:
+            session_id: The session.
+        """
+        command = SessionGetCommand(id=NEW, session_id=session_id)
+        return Session.from_dict(await self._request(command))
+
+    async def list(self) -> SessionList:
+        """`session/list`: every session."""
+        command = SessionListCommand(id=NEW)
+        return SessionList.from_dict(await self._request(command))
+
+    async def close(self, *, session_id: str) -> None:
+        """`session/close`; idempotent.
+
+        Args:
+            session_id: The session.
+        """
+        command = SessionCloseCommand(id=NEW, session_id=session_id)
+        await self._request(command)
+
+    async def adopt(self, *, session_id: str) -> Subscription[SessionEvent]:
+        """`session/adopt`: takes back an orphaned session.
+
+        Args:
+            session_id: The session.
+        """
+        command = SessionAdoptCommand(id=NEW, session_id=session_id)
+        return await self._subscribe(command, SESSION_EVENTS)
+
+
+class Commands(ABC):
+    """Every command as a typed method or a namespace of them.
+
+    The transport implements the two primitives and calls `__init__`.
+    """
+
+    def __init__(self) -> None:
+        """Bind every namespace to this transport."""
+        self.metrics = MetricsCommands(self._request, self._subscribe)
+        """`metrics/get`."""
+        self.stream = StreamCommands(self._request, self._subscribe)
+        """`stream/put`, `stream/get`, `stream/list`, `stream/delete`, `stream/subscribe`."""
+        self.webrtc = WebrtcCommands(self._request, self._subscribe)
+        """`webrtc/offer`, `webrtc/candidate`."""
+        self.session = SessionCommands(self._request, self._subscribe)
+        """`session/get`, `session/list`, `session/close`, `session/adopt`."""
+
+    @abstractmethod
+    async def _request(self, command: Model) -> dict[str, Any]:
+        """Send `command`; return its `result`, or `{}` for `pong`."""
+
+    @abstractmethod
+    async def _subscribe[E](self, command: Model, events: BasicDecoder[E]) -> Subscription[E]:
+        """Send a subscribing `command`; decode its events with `events`."""
+
+    async def ping(self) -> None:
+        """`ping`: answered with `pong`, not a `result`."""
+        command = PingCommand(id=NEW)
+        await self._request(command)
+
+    async def info(self) -> InfoResult:
+        """`info`: version, build, schemes, outputs, codecs, limits and sandbox."""
+        command = InfoCommand(id=NEW)
+        return InfoResult.from_dict(await self._request(command))
+
+    async def schema(self) -> dict[str, Any]:
+        """`schema`: the JSON Schema bundle of every message."""
+        command = SchemaCommand(id=NEW)
+        return await self._request(command)
+
+    async def unsubscribe(self, *, subscription: int) -> None:
+        """`unsubscribe`: ends a subscription of this connection.
+
+        Args:
+            subscription: The subscribing command's id.
+        """
+        command = UnsubscribeCommand(id=NEW, subscription=subscription)
+        await self._request(command)