PyLoxone-Audio 0.1.0__py3-none-any.whl

pyloxone_audio/clock.py

@@ -0,0 +1,7 @@
+"""UTC observations without a Home Assistant dependency."""
+from datetime import UTC, datetime
+
+
+def utcnow() -> datetime:
+    """Use the same aware UTC observation semantics as the accepted policy."""
+    return datetime.now(UTC)

pyloxone_audio/metadata.py

@@ -0,0 +1,98 @@
+"""Entry-owned optional Audioserver metadata, shared by the entry's players."""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import suppress
+import logging
+from typing import TYPE_CHECKING
+from urllib.parse import urljoin, urlsplit
+
+from .native import AudioServerCommands, AudioServerListener, AudioZoneMetadata, audioserver_uri
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from collections.abc import Coroutine
+    from typing import Any
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class AudioMetadataCoordinator:
+    """Keep the event connection independent of ordinary Miniserver controls."""
+
+    def __init__(self, host: str) -> None:
+        """Prepare a receive-only listener without opening a connection."""
+        self._listeners: dict[int, set[Callable[[], None]]] = {}
+        self._client = AudioServerListener(host, self._on_update)
+        self._http_origin = audioserver_uri(host).replace("ws://", "http://", 1)
+        self._task: asyncio.Task[None] | None = None
+
+    def async_start(self, create_task: Callable[[Coroutine[Any, Any, None]], asyncio.Task[None]] = asyncio.create_task) -> None:
+        """Start observation with an optional host-owned task scheduler."""
+        if self._task is not None and not self._task.done():
+            return
+        self._task = create_task(self._client.async_run())
+
+    async def async_stop(self) -> None:
+        """Cancel and await the connection before dropping entity subscriptions."""
+        if self._task is not None:
+            self._task.cancel()
+            with suppress(asyncio.CancelledError):
+                await self._task
+            self._task = None
+        self._listeners.clear()
+
+    def get(self, player_id: int) -> AudioZoneMetadata | None:
+        """Return an exact player's current metadata, never a name-based guess."""
+        return self._client.get(player_id)
+
+    async def async_ensure_snapshot(
+        self, commands: AudioServerCommands, player_id: int, *, is_current: Callable[[], bool],
+    ) -> None:
+        """Read missing initial state only for an explicit opted-in action."""
+        await self._client.async_ensure_snapshot(
+            player_id, lambda: commands.async_player_status(player_id, is_current=is_current), is_current=is_current,
+        )
+
+    def artwork_url(self, cover_url: str | None) -> str | None:
+        """Resolve optional artwork against this entry's configured Audioserver."""
+        if not cover_url:
+            return None
+        try:
+            resolved = urljoin(self._http_origin, cover_url)
+            parsed = urlsplit(resolved)
+            if (
+                parsed.scheme not in ("http", "https")
+                or not parsed.hostname
+                or parsed.username is not None
+                or parsed.password is not None
+                or parsed.port == 0
+            ):
+                return None
+        except ValueError:
+            return None
+        return resolved
+
+    def async_add_listener(self, player_id: int, listener: Callable[[], None]) -> Callable[[], None]:
+        """Subscribe one player; the entity owns its unsubscribe callback."""
+        self._listeners.setdefault(player_id, set()).add(listener)
+
+        def unsubscribe() -> None:
+            if listeners := self._listeners.get(player_id):
+                listeners.discard(listener)
+            if player_id in self._listeners and not self._listeners[player_id]:
+                del self._listeners[player_id]
+
+        return unsubscribe
+
+    def _on_update(self, updates: tuple[AudioZoneMetadata, ...]) -> None:
+        """Notify affected players; an empty update invalidates every snapshot."""
+        player_ids = {row.player_id for row in updates} if updates else set(self._listeners)
+        for player_id in player_ids:
+            for listener in tuple(self._listeners.get(player_id, ())):
+                try:
+                    listener()
+                except Exception as err:  # noqa: BLE001
+                    _LOGGER.warning("Audioserver metadata subscriber failed (%s)", type(err).__name__)

pyloxone_audio/models.py

@@ -0,0 +1,48 @@
+"""Neutral catalogue DTOs; HA serialization and enums belong to the host."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class MediaKind(StrEnum):
+    """Kinds actually emitted by the existing native catalogues."""
+
+    ALBUM = 'album'
+    ARTIST = 'artist'
+    CHANNEL = 'channel'
+    DIRECTORY = 'directory'
+    EPISODE = 'episode'
+    PLAYLIST = 'playlist'
+    PODCAST = 'podcast'
+    TRACK = 'track'
+
+
+@dataclass(kw_only=True)
+class MediaNode:
+    """Bounded discovered navigation/play item, not an HA UI object.
+
+    Mutable while the catalogue assembles provider-specific capabilities. Opaque
+    IDs remain room-local; a node is not permission to issue arbitrary commands.
+    """
+
+    media_class: MediaKind | str
+    media_content_id: str
+    media_content_type: str
+    title: str
+    can_play: bool
+    can_expand: bool
+    children: list[MediaNode] | None = None
+    children_media_class: MediaKind | str | None = None
+    thumbnail: str | None = None
+    not_shown: int = 0
+    can_search: bool = False
+    search_media_classes: list[MediaKind] | None = None
+
+
+@dataclass(kw_only=True, frozen=True)
+class SearchResult:
+    """Neutral search results; no HA schema, token/session or UI dependency."""
+
+    result: list[MediaNode]
+    version: int = 1