keres-sdk 0.1.0__py3-none-any.whl

keres_sdk/__init__.py

@@ -0,0 +1,38 @@
+"""keres-sdk — Playwright-compatible automation client for Keres Browser.
+
+Connects to the local Keres Automation Gateway; Keres owns profiles, sessions,
+and the browser runtime. See ``sync_api`` / ``async_api`` for entry points.
+"""
+
+from ._errors import (
+    ConnectionError,
+    KeresError,
+    PermissionDeniedError,
+    ProfileError,
+    ServerBusyError,
+    TargetClosedError,
+    TimeoutError,
+    UnsupportedCapabilityError,
+    from_gateway_error,
+)
+from .sync_api import keres
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "keres",
+    "KeresError",
+    "ConnectionError",
+    "TimeoutError",
+    "UnsupportedCapabilityError",
+    "PermissionDeniedError",
+    "TargetClosedError",
+    "ProfileError",
+    "ServerBusyError",
+    "from_gateway_error",
+    "__version__",
+]
+from ._expect import expect, KeresExpectationError
+
+__all__ = [name for name in dir() if not name.startswith("_")]
+

keres_sdk/_errors.py

@@ -0,0 +1,115 @@
+"""Typed errors for the keres-playwright client.
+
+Error names follow Playwright conventions (TimeoutError, ...) so existing
+`try/except` code keeps working, while every error carries the original
+structured Keres code under ``code`` for precise handling.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ._protocol import ErrorShape
+
+_CAPABILITY_CODES = frozenset(
+    {
+        "CAPABILITY_UNSUPPORTED",
+        "ENGINE_FEATURE_UNSUPPORTED",
+        "ENGINE_PROTOCOL_UNSUPPORTED",
+        "ENGINE_VARIANT_UNAVAILABLE",
+    }
+)
+
+_PROFILE_CODES = frozenset(
+    {
+        "PROFILE_NOT_FOUND",
+        "PROFILE_ACTIVE",
+        "PROFILE_LOCKED",
+        "PROFILE_DATA_MISSING",
+        "PROFILE_DATA_CORRUPTED",
+        "INVALID_PROFILE",
+    }
+)
+
+_TARGET_CLOSED_CODES = frozenset(
+    {
+        "SESSION_CLOSED",
+        "SESSION_NOT_READY",
+        "SESSION_INTERRUPTED",
+        "PAGE_CLOSED",
+        "PAGE_NOT_FOUND",
+    }
+)
+
+
+class KeresError(Exception):
+    """Base class for every error raised by this client."""
+
+    def __init__(self, shape: ErrorShape) -> None:
+        super().__init__(shape.message)
+        self.name = "KeresError"
+        self.code = shape.code
+        self.category = shape.category
+        self.recoverable = shape.recoverable
+
+
+class ConnectionError(KeresError):
+    def __init__(self, message: str) -> None:
+        super().__init__(
+            ErrorShape(code="GATEWAY_CONNECTION_FAILED", message=message, category="GATEWAY")
+        )
+        self.name = "ConnectionError"
+
+
+class TimeoutError(KeresError):
+    def __init__(self, shape: ErrorShape) -> None:
+        super().__init__(shape)
+        self.name = "TimeoutError"
+
+
+class UnsupportedCapabilityError(KeresError):
+    def __init__(self, shape: ErrorShape) -> None:
+        super().__init__(shape)
+        self.name = "UnsupportedCapabilityError"
+
+
+class PermissionDeniedError(KeresError):
+    def __init__(self, shape: ErrorShape) -> None:
+        super().__init__(shape)
+        self.name = "PermissionDeniedError"
+
+
+class TargetClosedError(KeresError):
+    def __init__(self, shape: ErrorShape) -> None:
+        super().__init__(shape)
+        self.name = "TargetClosedError"
+
+
+class ProfileError(KeresError):
+    def __init__(self, shape: ErrorShape) -> None:
+        super().__init__(shape)
+        self.name = "ProfileError"
+
+
+class ServerBusyError(KeresError):
+    def __init__(self, shape: ErrorShape) -> None:
+        super().__init__(shape)
+        self.name = "ServerBusyError"
+
+
+def from_gateway_error(error: ErrorShape) -> KeresError:
+    """Maps a structured gateway error onto the typed surface above."""
+    code = error.code
+    if code.endswith("_TIMEOUT"):
+        return TimeoutError(error)
+    if code in _CAPABILITY_CODES:
+        return UnsupportedCapabilityError(error)
+    if code in ("GATEWAY_PERMISSION_DENIED", "SESSION_PERMISSION_DENIED"):
+        return PermissionDeniedError(error)
+    if code == "GATEWAY_SERVER_BUSY":
+        return ServerBusyError(error)
+    if code in _PROFILE_CODES:
+        return ProfileError(error)
+    if code in _TARGET_CLOSED_CODES:
+        return TargetClosedError(error)
+    return KeresError(error)

keres_sdk/_expect.py

@@ -0,0 +1,236 @@
+"""Web-first auto-retrying assertions (Playwright ``expect`` shape).
+
+Polling is client-side over governed read operations — no new wire semantics.
+Works from both API flavors: probes transparently await async locator/page
+methods when driven through :mod:`keres_playwright.async_api`, and run
+synchronously through the sync facade.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import fnmatch
+import inspect
+import time
+from typing import Any, Callable, Optional
+
+DEFAULT_TIMEOUT_MS = 5_000
+DEFAULT_INTERVAL_MS = 100
+
+
+class KeresExpectationError(AssertionError):
+    """Raised when an assertion does not pass within its deadline."""
+
+    def __init__(self, assertion: str, expected: str, received: str) -> None:
+        super().__init__(
+            f"expect({assertion}) failed\n\nExpected: {expected}\nReceived: {received}"
+        )
+        self.assertion = assertion
+        self.expected = expected
+        self.received = received
+
+
+async def _poll_until(
+    assertion: str,
+    expected_description: str,
+    deadline_ms: float,
+    interval_ms: float,
+    probe: Callable[[], Any],
+) -> None:
+    """``probe`` returns an ``(ok, received)`` tuple or an awaitable of one."""
+    started_ms = time.monotonic() * 1000
+    received = "unknown"
+    while time.monotonic() * 1000 - started_ms < deadline_ms:
+        result = probe()
+        if inspect.isawaitable(result):
+            result = await result
+        ok, received = result
+        if ok:
+            return
+        await asyncio.sleep(interval_ms / 1000)
+    raise KeresExpectationError(assertion, expected_description, received)
+
+
+def _bool_probe(value: Any) -> Any:
+    """Adapts a sync-or-async boolean into an ``(ok, received)`` tuple."""
+    if inspect.isawaitable(value):
+
+        async def runner() -> tuple:
+            got = bool(await value)
+            return got, str(got)
+
+        return runner()
+    got = bool(value)
+    return got, str(got)
+
+
+def _text_probe(value: Any, predicate: Callable[[str], bool]) -> Any:
+    """Adapts a sync-or-async text into a predicate-checked tuple."""
+    if inspect.isawaitable(value):
+
+        async def runner() -> tuple:
+            text = (await value) or ""
+            return predicate(text), text
+
+        return runner()
+    text = value or ""
+    return predicate(text), text
+
+
+def _opts(options: Optional[dict]) -> dict:
+    return options or {}
+
+
+def expect(target: Any) -> Any:
+    """Playwright-style entry point. Returns an assertion object."""
+    if target.__class__.__name__ in ("Page", "SyncPage"):
+        return PageAssertions(target)
+    return LocatorAssertions(target)
+
+
+class LocatorAssertions:
+    def __init__(self, locator: Any) -> None:
+        self._locator = locator
+
+    def to_be_visible(self, options: Optional[dict] = None) -> Any:
+        o = _opts(options)
+        return _poll_until(
+            "locator.to_be_visible",
+            "visible",
+            o.get("timeoutMs", DEFAULT_TIMEOUT_MS),
+            o.get("intervalMs", DEFAULT_INTERVAL_MS),
+            lambda: _bool_probe(self._locator.is_visible()),
+        )
+
+    def to_be_hidden(self, options: Optional[dict] = None) -> Any:
+        o = _opts(options)
+
+        def probe() -> Any:
+            value = self._locator.is_visible()
+            if inspect.isawaitable(value):
+
+                async def runner() -> tuple:
+                    visible = bool(await value)
+                    return not visible, "hidden" if not visible else "visible"
+
+                return runner()
+            return not value, "hidden" if not value else "visible"
+
+        return _poll_until(
+            "locator.to_be_hidden",
+            "hidden",
+            o.get("timeoutMs", DEFAULT_TIMEOUT_MS),
+            o.get("intervalMs", DEFAULT_INTERVAL_MS),
+            probe,
+        )
+
+    def to_be_enabled(self, options: Optional[dict] = None) -> Any:
+        o = _opts(options)
+        return _poll_until(
+            "locator.to_be_enabled",
+            "enabled",
+            o.get("timeoutMs", DEFAULT_TIMEOUT_MS),
+            o.get("intervalMs", DEFAULT_INTERVAL_MS),
+            lambda: _bool_probe(self._locator.is_enabled()),
+        )
+
+    def to_be_checked(self, expected: bool = True, options: Optional[dict] = None) -> Any:
+        o = _opts(options)
+        return _poll_until(
+            "locator.to_be_checked",
+            str(expected),
+            o.get("timeoutMs", DEFAULT_TIMEOUT_MS),
+            o.get("intervalMs", DEFAULT_INTERVAL_MS),
+            lambda: _bool_probe(self._locator.is_checked() == expected),
+        )
+
+    def to_be_editable(self, options: Optional[dict] = None) -> Any:
+        o = _opts(options)
+        return _poll_until(
+            "locator.to_be_editable",
+            "editable",
+            o.get("timeoutMs", DEFAULT_TIMEOUT_MS),
+            o.get("intervalMs", DEFAULT_INTERVAL_MS),
+            lambda: _bool_probe(self._locator.is_editable()),
+        )
+
+    def to_have_text(self, text: str, options: Optional[dict] = None) -> Any:
+        o = _opts(options)
+        exact = o.get("exact", True)
+        return _poll_until(
+            "locator.to_have_text",
+            text,
+            o.get("timeoutMs", DEFAULT_TIMEOUT_MS),
+            o.get("intervalMs", DEFAULT_INTERVAL_MS),
+            lambda: _text_probe(
+                self._locator.text_content(options=o),
+                (lambda actual: actual == text) if exact else (lambda actual: text in actual),
+            ),
+        )
+
+    def to_contain_text(self, text: str, options: Optional[dict] = None) -> Any:
+        merged = dict(_opts(options))
+        merged["exact"] = False
+        return self.to_have_text(text, merged)
+
+    def to_have_value(self, value: str, options: Optional[dict] = None) -> Any:
+        o = _opts(options)
+        return _poll_until(
+            "locator.to_have_value",
+            value,
+            o.get("timeoutMs", DEFAULT_TIMEOUT_MS),
+            o.get("intervalMs", DEFAULT_INTERVAL_MS),
+            lambda: _text_probe(
+                self._locator.get_property("value", options=o),
+                lambda actual: str(actual) == value,
+            ),
+        )
+
+    def to_have_attribute(self, name: str, value: str, options: Optional[dict] = None) -> Any:
+        o = _opts(options)
+        return _poll_until(
+            "locator.to_have_attribute",
+            f'{name}="{value}"',
+            o.get("timeoutMs", DEFAULT_TIMEOUT_MS),
+            o.get("intervalMs", DEFAULT_INTERVAL_MS),
+            lambda: _text_probe(
+                self._locator.get_attribute(name, options=o),
+                lambda actual: str(actual) == value,
+            ),
+        )
+
+
+class PageAssertions:
+    def __init__(self, page: Any) -> None:
+        self._page = page
+
+    def to_have_title(self, title: str, options: Optional[dict] = None) -> Any:
+        o = _opts(options)
+        exact = o.get("exact", True)
+        return _poll_until(
+            "page.to_have_title",
+            title,
+            o.get("timeoutMs", DEFAULT_TIMEOUT_MS),
+            o.get("intervalMs", DEFAULT_INTERVAL_MS),
+            lambda: _text_probe(
+                self._page.title(options=o),
+                (lambda actual: actual == title) if exact else (lambda actual: title in actual),
+            ),
+        )
+
+    def to_have_url(self, pattern: str, options: Optional[dict] = None) -> Any:
+        o = _opts(options)
+        use_glob = o.get("glob", "*" in pattern)
+
+        def matcher(candidate: str) -> bool:
+            if use_glob:
+                return fnmatch.fnmatchcase(candidate, pattern)
+            return candidate == pattern
+
+        return _poll_until(
+            "page.to_have_url",
+            pattern,
+            o.get("timeoutMs", DEFAULT_TIMEOUT_MS),
+            o.get("intervalMs", DEFAULT_INTERVAL_MS),
+            lambda: (matcher(self._page.url()), self._page.url()),
+        )