watcherobot 0.1.1__py3-none-any.whl

watcherobot/__init__.py

@@ -0,0 +1,83 @@
+from .errors import (
+    AuthenticationError,
+    CommandError,
+    ConnectionTimeoutError,
+    JobCancelledError,
+    JobFailedError,
+    WatcheRobotError,
+)
+from .audio import AudioPlayback, PCMAudio
+from .job import Job, JobState
+from .inputs import BackTouchEvent, InputDomain, InputEvent, RollerEvent, ScreenTouchEvent
+from .media import AudioFormat, AudioFrame, AudioRecording, ImageFrame, MicrophoneSession
+from .provisioning import (
+    BluetoothConnectionTimeoutError,
+    BluetoothDevice,
+    BluetoothPermissionError,
+    BluetoothProvisioner,
+    BluetoothProvisioningError,
+    BluetoothUnavailableError,
+    DeviceAmbiguityError,
+    DeviceNotFoundError,
+    PayloadTooLargeError,
+    ProtocolMessage,
+    ProvisioningCancelledError,
+    ProvisioningProtocolError,
+    ProvisioningRejectedError,
+    ProvisioningResponseTimeoutError,
+    ProvisioningResult,
+    WifiStatus,
+)
+from .vision import (
+    FaceBox,
+    FaceTrackingFrame,
+    FaceTrackingPreview,
+    FaceTrackingStopPolicy,
+    FaceTrackingTelemetry,
+)
+
+__all__ = [
+    "AudioFormat",
+    "AudioFrame",
+    "AudioPlayback",
+    "AudioRecording",
+    "AuthenticationError",
+    "BackTouchEvent",
+    "BluetoothConnectionTimeoutError",
+    "BluetoothDevice",
+    "BluetoothPermissionError",
+    "BluetoothProvisioner",
+    "BluetoothProvisioningError",
+    "BluetoothUnavailableError",
+    "CommandError",
+    "ConnectionTimeoutError",
+    "DeviceAmbiguityError",
+    "DeviceNotFoundError",
+    "FaceBox",
+    "FaceTrackingFrame",
+    "FaceTrackingPreview",
+    "FaceTrackingStopPolicy",
+    "FaceTrackingTelemetry",
+    "ImageFrame",
+    "InputDomain",
+    "InputEvent",
+    "Job",
+    "JobCancelledError",
+    "JobFailedError",
+    "JobState",
+    "MicrophoneSession",
+    "PCMAudio",
+    "PayloadTooLargeError",
+    "ProtocolMessage",
+    "ProvisioningCancelledError",
+    "ProvisioningProtocolError",
+    "ProvisioningRejectedError",
+    "ProvisioningResponseTimeoutError",
+    "ProvisioningResult",
+    "RollerEvent",
+    "ScreenTouchEvent",
+    "WatcheRobotError",
+    "WifiStatus",
+]
+
+__version__ = "0.1.1"

watcherobot/_internal/__init__.py

@@ -0,0 +1 @@
+"""Private implementation helpers for the WatcheRobot SDK."""

watcherobot/_internal/audio_status.py

@@ -0,0 +1,40 @@
+"""Single source of truth for device audio stream status semantics."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class AudioStatusKind(str, Enum):
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+FAILED_AUDIO_REASONS = frozenset(
+    {
+        "enqueue_timeout",
+        "enqueue_failed",
+        "queue_lock_timeout",
+        "sequence_gap",
+        "stale_stream",
+        "stale_frame",
+        "playback_start_failed",
+        "playback_write_failed",
+    }
+)
+
+CANCELLED_AUDIO_REASONS = frozenset({"aborted", "replaced_by_new_stream"})
+
+
+def classify_audio_status(reason: object) -> AudioStatusKind:
+    """Map one protocol reason to the public playback lifecycle."""
+
+    if reason == "complete":
+        return AudioStatusKind.COMPLETED
+    if reason in FAILED_AUDIO_REASONS:
+        return AudioStatusKind.FAILED
+    if reason in CANCELLED_AUDIO_REASONS:
+        return AudioStatusKind.CANCELLED
+    return AudioStatusKind.RUNNING

watcherobot/application/__init__.py

@@ -0,0 +1,30 @@
+"""Public API for Daemon-managed WatcheRobot Applications."""
+
+from .channels import (
+    ApplicationChannel,
+    ApplicationChannels,
+    Frame,
+    FrameCallback,
+)
+from .context import ApplicationContext, ApplicationEnvironmentError
+from .rtc import (
+    ApplicationRtc,
+    RTC_AUDIO_CAPABILITY,
+    RTC_PROTOCOL,
+    RTC_VIDEO_CAPABILITY,
+    RtcSessionRejectedError,
+)
+
+__all__ = [
+    "ApplicationChannel",
+    "ApplicationChannels",
+    "ApplicationContext",
+    "ApplicationEnvironmentError",
+    "ApplicationRtc",
+    "Frame",
+    "FrameCallback",
+    "RTC_AUDIO_CAPABILITY",
+    "RTC_PROTOCOL",
+    "RTC_VIDEO_CAPABILITY",
+    "RtcSessionRejectedError",
+]

watcherobot/application/channels.py

@@ -0,0 +1,35 @@
+"""Low-level channels for advanced Daemon-managed Applications."""
+
+from __future__ import annotations
+
+from watcherobot.runtime.daemon.application.client import (
+    ApplicationCommunicators,
+    Frame,
+    FrameCallback,
+)
+from watcherobot.runtime.daemon.application.session import ApplicationChannel
+
+
+class ApplicationChannels(ApplicationCommunicators):
+    """Expose source-aware desktop/device frames to an advanced Application.
+
+    Most Applications should use :class:`ApplicationContext`. This lower-level
+    API exists for Applications such as ``watcher_default`` that already own a
+    complete business protocol stack and need the original frames unchanged.
+    """
+
+    @property
+    def desktop_url(self) -> str:
+        return self._desktop_url
+
+    @property
+    def device_url(self) -> str:
+        return self._device_url
+
+
+__all__ = [
+    "ApplicationChannel",
+    "ApplicationChannels",
+    "Frame",
+    "FrameCallback",
+]

watcherobot/application/context.py

@@ -0,0 +1,99 @@
+"""Public context for a Daemon-managed WatcheRobot Application."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import sys
+from types import TracebackType
+
+from watcherobot.application.desktop import ApplicationDesktop
+from watcherobot.application.rtc import ApplicationRtc
+from watcherobot.application.transport import DaemonApplicationTransport
+from watcherobot.robot import WatcheRobot
+
+
+class ApplicationEnvironmentError(RuntimeError):
+    """Raised when code is not running inside an authorized Application."""
+
+
+class ApplicationContext:
+    """Own the SDK objects injected into one managed Application process."""
+
+    def __init__(
+        self,
+        *,
+        app_id: str,
+        transport: DaemonApplicationTransport,
+    ) -> None:
+        self.app_id = app_id
+        self._transport = transport
+        self.robot = WatcheRobot._from_transport(transport)
+        self.desktop = ApplicationDesktop(transport)
+        self.rtc = ApplicationRtc(transport)
+        self.logger = _build_application_logger(app_id)
+        self._entered = False
+
+    @classmethod
+    def from_environment(cls) -> "ApplicationContext":
+        required = {
+            "WATCHER_APP_ID": os.environ.get("WATCHER_APP_ID", "").strip(),
+            "WATCHER_APP_RUN_CREDENTIAL": os.environ.get(
+                "WATCHER_APP_RUN_CREDENTIAL",
+                "",
+            ).strip(),
+            "WATCHER_APP_DESKTOP_WS_URL": os.environ.get(
+                "WATCHER_APP_DESKTOP_WS_URL",
+                "",
+            ).strip(),
+            "WATCHER_APP_DEVICE_WS_URL": os.environ.get(
+                "WATCHER_APP_DEVICE_WS_URL",
+                "",
+            ).strip(),
+        }
+        missing = [name for name, value in required.items() if not value]
+        if missing:
+            raise ApplicationEnvironmentError(
+                "Application environment is incomplete: "
+                + ", ".join(sorted(missing))
+            )
+        return cls(
+            app_id=required["WATCHER_APP_ID"],
+            transport=DaemonApplicationTransport(),
+        )
+
+    async def __aenter__(self) -> "ApplicationContext":
+        if self._entered:
+            raise RuntimeError("ApplicationContext is already entered")
+        await asyncio.to_thread(self._transport.start)
+        self._entered = True
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await asyncio.to_thread(self.close)
+
+    def close(self) -> None:
+        if not self._entered:
+            return
+        self.rtc.close()
+        self.robot.close()
+        self._entered = False
+
+
+def _build_application_logger(app_id: str) -> logging.Logger:
+    logger = logging.getLogger(f"watcherobot.application.{app_id}")
+    logger.setLevel(logging.INFO)
+    logger.propagate = False
+    if not logger.handlers:
+        handler = logging.StreamHandler(sys.stdout)
+        handler.setFormatter(
+            logging.Formatter("%(asctime)s %(levelname)s %(message)s")
+        )
+        logger.addHandler(handler)
+    return logger

watcherobot/application/desktop.py

@@ -0,0 +1,26 @@
+"""Desktop-side Application channel exposed without device ownership."""
+
+from __future__ import annotations
+
+import asyncio
+import queue
+
+from watcherobot.application.transport import DaemonApplicationTransport
+
+
+class ApplicationDesktop:
+    """Send and receive raw desktop frames through the managed Daemon bridge."""
+
+    def __init__(self, transport: DaemonApplicationTransport) -> None:
+        self._transport = transport
+        self._frames: queue.Queue[str | bytes] = queue.Queue()
+        transport.set_desktop_callback(self._frames.put)
+
+    async def send(self, frame: str | bytes) -> None:
+        await asyncio.wrap_future(self._transport.send_desktop(frame))
+
+    async def receive(self, *, timeout: float | None = None) -> str | bytes:
+        try:
+            return await asyncio.to_thread(self._frames.get, True, timeout)
+        except queue.Empty as exc:
+            raise TimeoutError("Timed out waiting for a desktop frame") from exc

watcherobot/application/ignore.py

@@ -0,0 +1,54 @@
+"""Shared Application source ignore rules for validation and publishing."""
+
+from __future__ import annotations
+
+from fnmatch import fnmatchcase
+from pathlib import Path, PurePosixPath
+
+
+APPLICATION_IGNORE_FILE = ".watcherignore"
+
+
+class ApplicationIgnoreError(RuntimeError):
+    """Raised when Application ignore rules cannot be loaded safely."""
+
+
+def load_application_ignore_patterns(source: Path) -> tuple[str, ...]:
+    """Load normalized non-comment patterns from one Application root."""
+
+    ignore_path = Path(source) / APPLICATION_IGNORE_FILE
+    if not ignore_path.is_file():
+        return ()
+    try:
+        lines = ignore_path.read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeError) as exc:
+        raise ApplicationIgnoreError(
+            f"Cannot read {APPLICATION_IGNORE_FILE}: {exc}"
+        ) from exc
+    return tuple(
+        line.strip().replace("\\", "/")
+        for line in lines
+        if line.strip() and not line.lstrip().startswith("#")
+    )
+
+
+def is_application_path_ignored(
+    relative_path: Path,
+    patterns: tuple[str, ...],
+) -> bool:
+    """Return whether a relative Application path matches ignore rules."""
+
+    relative = PurePosixPath(relative_path.as_posix())
+    for pattern in patterns:
+        if pattern.endswith("/"):
+            prefix = pattern.rstrip("/")
+            ancestors = (
+                "/".join(relative.parts[:depth])
+                for depth in range(1, len(relative.parts))
+            )
+            if any(fnmatchcase(ancestor, prefix) for ancestor in ancestors):
+                return True
+            continue
+        if relative.match(pattern):
+            return True
+    return False