browser-daemon-client 0.1.0__py3-none-any.whl

browser_daemon_client/__init__.py

@@ -0,0 +1,398 @@
+"""Async client for browser-daemon's HTTP API, with nothing but aiohttp.
+
+Made for Home Assistant integrations and other code that cannot carry
+Playwright: :meth:`BrowserDaemon.run` runs a Playwright script or a list of
+steps on the node (see docs/run.md), and the other methods cover sessions,
+tabs and a page's login.
+
+    async with aiohttp.ClientSession() as http:
+        bd = BrowserDaemon(http, "https://browser.example.org", secret)
+        res = await bd.run(
+            profile="work",
+            url="https://example.org/login",
+            steps=[
+                step.fill("#user", arg="user"),
+                step.fill("#password", arg="password"),
+                step.click("role=button[name='Sign in']"),
+                step.text(".balance", as_="balance"),
+            ],
+            args={"user": user, "password": password},
+        )
+        print(res.result["balance"])
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import quote
+
+import aiohttp
+
+__all__ = [
+    "BrowserDaemon",
+    "BrowserDaemonError",
+    "RunError",
+    "RunResult",
+    "RunTimeout",
+    "read_secret",
+    "step",
+]
+
+SECRET_HEADER = "X-Browser-Cluster-Secret"
+DEFAULT_SECRET_FILE = "/run/secrets/browser-daemon/cluster-secret"
+
+
+class BrowserDaemonError(Exception):
+    """The daemon refused a request or could not be reached."""
+
+    def __init__(self, message: str, status: int | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+
+
+@dataclass
+class RunResult:
+    """The answer of a run (see docs/run.md, "The answer")."""
+
+    ok: bool
+    result: Any = None
+    error: str | None = None
+    timed_out: bool = False
+    steps: list[dict[str, Any]] = field(default_factory=list)
+    logs: list[dict[str, Any]] = field(default_factory=list)
+    url: str | None = None
+    page: str | None = None
+    #: The tab when the run failed: a base64 PNG.
+    screenshot: str | None = None
+    ms: int | None = None
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> RunResult:
+        return cls(
+            ok=bool(data.get("ok")),
+            result=data.get("result"),
+            error=data.get("error"),
+            timed_out=bool(data.get("timed_out")),
+            steps=data.get("steps") or [],
+            logs=data.get("logs") or [],
+            url=data.get("url"),
+            page=data.get("page"),
+            screenshot=data.get("screenshot"),
+            ms=data.get("ms"),
+        )
+
+
+class RunError(BrowserDaemonError):
+    """The script or a step failed; :attr:`run` holds the whole answer."""
+
+    def __init__(self, run: RunResult, status: int | None = None) -> None:
+        super().__init__(run.error or "The run failed", status)
+        self.run = run
+
+
+class RunTimeout(RunError):
+    """The run hit its timeout."""
+
+
+def read_secret(path: str = DEFAULT_SECRET_FILE) -> str | None:
+    """The cluster secret from a file, or None when it cannot be read."""
+    try:
+        with open(path, encoding="utf-8") as f:
+            return f.read().strip() or None
+    except OSError:
+        return None
+
+
+class BrowserDaemon:
+    """A node of the mesh. Requests for other nodes go through it (`node=`)."""
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        url: str,
+        secret: str | None = None,
+        *,
+        client: str | None = None,
+        timeout: float = 30,
+    ) -> None:
+        self.session = session
+        self.url = url.rstrip("/")
+        self.secret = secret
+        #: Shown on the dashboard for sessions and runs ("Home Assistant · HR WORKS").
+        self.client = client
+        self.timeout = timeout
+        self.local_node: str | None = None
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        node: str | None = None,
+        timeout: float | None = None,
+        accept: tuple[int, ...] = (),
+        **kwargs: Any,
+    ) -> tuple[int, Any]:
+        if node and node != self.local_node:
+            path = f"/api/peers/{quote(node, safe='')}/{path.removeprefix('/api/').lstrip('/')}"
+        headers = {SECRET_HEADER: self.secret} if self.secret else {}
+        try:
+            async with self.session.request(
+                method,
+                self.url + path,
+                headers=headers,
+                timeout=aiohttp.ClientTimeout(total=timeout or self.timeout),
+                **kwargs,
+            ) as res:
+                data = await res.json(content_type=None) if res.status != 204 else None
+                if res.status < 300 or res.status in accept:
+                    return res.status, data
+                message = data.get("error") if isinstance(data, dict) else None
+                raise BrowserDaemonError(
+                    message or f"browser-daemon returned HTTP {res.status}", res.status
+                )
+        except (aiohttp.ClientError, TimeoutError) as err:
+            raise BrowserDaemonError(f"browser-daemon is unreachable: {err!r}") from err
+        except ValueError as err:
+            raise BrowserDaemonError("browser-daemon sent an unreadable answer") from err
+
+    async def _json(self, method: str, path: str, **kwargs: Any) -> Any:
+        return (await self._request(method, path, **kwargs))[1]
+
+    # The mesh
+
+    async def overview(self) -> dict[str, Any]:
+        """Nodes, sessions, profiles and tabs of the whole mesh."""
+        data = await self._json("GET", "/api/mesh/overview")
+        self.local_node = (data.get("local_node") or {}).get("name")
+        return data
+
+    async def find_profile(self, name: str) -> dict[str, Any] | None:
+        """A profile of the mesh by name, with its `node_name` and `session_id`."""
+        overview = await self.overview()
+        return next((p for p in overview.get("profiles", []) if p.get("name") == name), None)
+
+    # Runs
+
+    async def run(
+        self,
+        *,
+        script: str | None = None,
+        steps: list[dict[str, Any]] | None = None,
+        args: dict[str, Any] | None = None,
+        profile: str | None = None,
+        session_id: str | None = None,
+        tab: str | None = None,
+        url: str | None = None,
+        keep_open: bool = False,
+        persistent: bool = False,
+        timeout: float = 60,
+        action_timeout: float | None = None,
+        screenshot_on_error: bool = True,
+        idle_timeout_minutes: int | None = None,
+        node: str | None = None,
+        check: bool = True,
+    ) -> RunResult:
+        """Run a script or steps in a browser of the mesh (see docs/run.md).
+
+        Raises :class:`RunError` (:class:`RunTimeout`) when the run fails,
+        unless `check` is false, and :class:`BrowserDaemonError` when it could
+        not start.
+        """
+        body: dict[str, Any] = {
+            "script": script,
+            "steps": steps,
+            "args": args,
+            "profile": profile,
+            "session_id": session_id,
+            "tab": tab,
+            "url": url,
+            "keep_open": keep_open,
+            "persistent": persistent,
+            "timeout_seconds": max(1, round(timeout)),
+            "action_timeout_seconds": round(action_timeout) if action_timeout else None,
+            "screenshot_on_error": screenshot_on_error,
+            "idle_timeout_minutes": idle_timeout_minutes,
+            "client": self.client,
+        }
+        status, data = await self._request(
+            "POST",
+            "/api/run",
+            node=node,
+            json={k: v for k, v in body.items() if v is not None},
+            timeout=timeout + 45,
+            accept=(422, 504),
+        )
+        res = RunResult.from_json(data or {})
+        if check and not res.ok:
+            raise (RunTimeout if res.timed_out else RunError)(res, status)
+        return res
+
+    # Sessions and tabs
+
+    async def sessions(self, node: str | None = None) -> list[dict[str, Any]]:
+        return await self._json("GET", "/api/sessions", node=node)
+
+    async def session(self, session_id: str, node: str | None = None) -> dict[str, Any]:
+        """The session and its `targets` (tabs)."""
+        return await self._json("GET", f"/api/sessions/{quote(session_id, safe='')}", node=node)
+
+    async def create_session(
+        self, *, profile: str | None = None, node: str | None = None, **options: Any
+    ) -> dict[str, Any]:
+        """Start a session (or attach to the profile's); options as `POST /api/sessions`."""
+        body = {"persistent": True, "profile": profile, **options}
+        if self.client and "name" not in body:
+            body["name"] = self.client
+        return await self._json(
+            "POST",
+            "/api/sessions",
+            node=node,
+            json={k: v for k, v in body.items() if v is not None},
+        )
+
+    async def delete_session(self, session_id: str, node: str | None = None) -> None:
+        await self._request("DELETE", f"/api/sessions/{quote(session_id, safe='')}", node=node)
+
+    async def set_idle_timeout(
+        self, session_id: str, minutes: int, node: str | None = None
+    ) -> None:
+        await self._request(
+            "POST",
+            f"/api/sessions/{quote(session_id, safe='')}/idle-timeout",
+            node=node,
+            params={"minutes": minutes},
+        )
+
+    async def tabs(self, node: str | None = None) -> list[dict[str, Any]]:
+        """The pages of all sessions of the node (`/json/list`)."""
+        return await self._json("GET", "/json/list", node=node)
+
+    async def open_tab(
+        self, url: str, *, session_id: str, node: str | None = None
+    ) -> dict[str, Any]:
+        return await self._json(
+            "PUT", "/json/new", node=node, params={"url": url, "session_id": session_id}
+        )
+
+    async def close_tab(self, page_id: str, node: str | None = None) -> None:
+        await self._request("PUT", f"/json/close/{quote(page_id, safe='')}", node=node)
+
+    async def export_auth(
+        self,
+        page_id: str,
+        *,
+        session_id: str | None = None,
+        urls: list[str] | None = None,
+        storage: bool = False,
+        node: str | None = None,
+    ) -> dict[str, Any]:
+        """A page's cookies (and local/session storage): its login, for an API client.
+
+        The answer is credentials: never log it.
+        """
+        body: dict[str, Any] = {"urls": urls or [], "storage": storage}
+        if session_id:
+            body["session_id"] = session_id
+        return await self._json(
+            "POST", f"/api/pages/{quote(page_id, safe='')}/auth", node=node, json=body
+        )
+
+
+class step:
+    """Builders for run steps (docs/run.md, "Steps"). `as_` names the value."""
+
+    @staticmethod
+    def _make(action: str, as_: str | None = None, **fields: Any) -> dict[str, Any]:
+        out = {"action": action, **{k: v for k, v in fields.items() if v is not None}}
+        if as_:
+            out["as"] = as_
+        return out
+
+    @staticmethod
+    def goto(url: str, *, wait_until: str | None = None, **kw: Any) -> dict[str, Any]:
+        return step._make("goto", url=url, wait_until=wait_until, **kw)
+
+    @staticmethod
+    def click(selector: str, **kw: Any) -> dict[str, Any]:
+        return step._make("click", selector=selector, **kw)
+
+    @staticmethod
+    def fill(
+        selector: str, value: str | None = None, *, arg: str | None = None, **kw: Any
+    ) -> dict[str, Any]:
+        """Fill an input with `value`, or with `args[arg]` (keeps secrets out of the steps)."""
+        return step._make("fill", selector=selector, value=value, value_arg=arg, **kw)
+
+    @staticmethod
+    def type(
+        selector: str, value: str | None = None, *, arg: str | None = None, **kw: Any
+    ) -> dict[str, Any]:
+        return step._make("type", selector=selector, value=value, value_arg=arg, **kw)
+
+    @staticmethod
+    def press(key: str, selector: str | None = None, **kw: Any) -> dict[str, Any]:
+        return step._make("press", key=key, selector=selector, **kw)
+
+    @staticmethod
+    def select(
+        selector: str, value: Any = None, *, arg: str | None = None, **kw: Any
+    ) -> dict[str, Any]:
+        return step._make("select", selector=selector, value=value, value_arg=arg, **kw)
+
+    @staticmethod
+    def check(selector: str, checked: bool = True, **kw: Any) -> dict[str, Any]:
+        return step._make("check", selector=selector, checked=checked, **kw)
+
+    @staticmethod
+    def wait_for(
+        selector: str | None = None,
+        *,
+        state: str | None = None,
+        url: str | None = None,
+        load_state: str | None = None,
+        ms: int | None = None,
+        **kw: Any,
+    ) -> dict[str, Any]:
+        return step._make(
+            "wait_for", selector=selector, state=state, url=url, load_state=load_state, ms=ms, **kw
+        )
+
+    @staticmethod
+    def text(selector: str, *, all: bool | None = None, **kw: Any) -> dict[str, Any]:
+        return step._make("text", selector=selector, all=all, **kw)
+
+    @staticmethod
+    def value(selector: str, **kw: Any) -> dict[str, Any]:
+        return step._make("value", selector=selector, **kw)
+
+    @staticmethod
+    def attribute(selector: str, name: str, **kw: Any) -> dict[str, Any]:
+        return step._make("attribute", selector=selector, name=name, **kw)
+
+    @staticmethod
+    def count(selector: str, **kw: Any) -> dict[str, Any]:
+        return step._make("count", selector=selector, **kw)
+
+    @staticmethod
+    def visible(selector: str, **kw: Any) -> dict[str, Any]:
+        return step._make("visible", selector=selector, **kw)
+
+    @staticmethod
+    def evaluate(expression: str, arg: Any = None, **kw: Any) -> dict[str, Any]:
+        return step._make("evaluate", expression=expression, arg=arg, **kw)
+
+    @staticmethod
+    def screenshot(
+        selector: str | None = None, *, full_page: bool | None = None, **kw: Any
+    ) -> dict[str, Any]:
+        return step._make("screenshot", selector=selector, full_page=full_page, **kw)
+
+    @staticmethod
+    def url(**kw: Any) -> dict[str, Any]:
+        return step._make("url", **kw)
+
+    @staticmethod
+    def title(**kw: Any) -> dict[str, Any]:
+        return step._make("title", **kw)

browser_daemon_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: browser-daemon-client
+Version: 0.1.0
+Summary: Async client for browser-daemon: Playwright runs over HTTP, sessions and logins, with nothing but aiohttp
+License-Expression: GPL-3.0-only
+Project-URL: Homepage, https://github.com/pschmitt/browser-daemon
+Project-URL: Documentation, https://github.com/pschmitt/browser-daemon/blob/main/docs/run.md
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.9
+
+# browser-daemon-client
+
+Async Python client for [browser-daemon](https://github.com/pschmitt/browser-daemon),
+with nothing but `aiohttp`: made for Home Assistant integrations and other code
+that cannot carry Playwright.
+
+```python
+import aiohttp
+from browser_daemon_client import BrowserDaemon, RunError, step
+
+async with aiohttp.ClientSession() as http:
+    bd = BrowserDaemon(
+        http, "https://browser.example.org", secret, client="Home Assistant · HR WORKS"
+    )
+    try:
+        res = await bd.run(
+            profile="work",
+            url="https://hr.example.org/login",
+            steps=[
+                step.fill("#user", arg="user"),
+                step.fill("#password", arg="password"),
+                step.click("role=button[name='Sign in']"),
+                step.wait_for(".dashboard"),
+                step.text(".balance", as_="balance"),
+            ],
+            args={"user": user, "password": password},
+        )
+    except RunError as err:
+        print(err, err.run.url)  # err.run.screenshot: the tab, as a base64 PNG
+    else:
+        print(res.result["balance"])
+```
+
+- `run()`: a Playwright `script` (a JavaScript function expression) or `steps`,
+  in a profile's browser, a session or a throwaway browser. Runs for a profile
+  go to the node that has it. See [docs/run.md](../docs/run.md).
+- `overview()`, `find_profile()`, `sessions()`, `session()`, `create_session()`,
+  `delete_session()`, `set_idle_timeout()`, `tabs()`, `open_tab()`,
+  `close_tab()`, `export_auth()` (a page's cookies and storage; never log them).
+- `node=` sends a request to another node of the mesh through this one.
+- `read_secret()` reads the cluster secret from its file.
+
+Errors are `BrowserDaemonError` (with `status`), and for runs `RunError` and
+`RunTimeout` (with the whole answer in `.run`).
+
+## Releasing
+
+Bump `version` in `pyproject.toml`, commit, and push a signed tag
+`python-vX.Y.Z`: the `python-client` workflow tests, builds and publishes it to
+PyPI through trusted publishing (the `pypi` environment, tags `python-v*` only;
+no token is stored anywhere).

browser_daemon_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+browser_daemon_client/__init__.py,sha256=mx6bGrXMWFwLNYx59e41wC1u-7EdgduQEMQzRctp8Eo,14154
+browser_daemon_client-0.1.0.dist-info/METADATA,sha256=Nc-jOXCXaACblSNWAtH4izZhX8cqfCc7BWlavUfWWOI,2556
+browser_daemon_client-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+browser_daemon_client-0.1.0.dist-info/top_level.txt,sha256=hyobKNFfO8NXBIa5aquGmSgBpWIkjcaGhLcHRvlYZSs,22
+browser_daemon_client-0.1.0.dist-info/RECORD,,

browser_daemon_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

browser_daemon_client-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+browser_daemon_client