mooncat-browser-client 0.4.7__py3-none-any.whl

behavior.py

@@ -0,0 +1,138 @@
+"""web/behavior — 人类行为模拟 (路由无关, 全走 operate).
+
+忠实复刻 lib/web/behavior.js。
+贝塞尔鼠标轨迹 / 随机点击偏移 / 打字节奏 / 平滑滚动。
+所有页面动作统一走 operate(pageHandle, {action})，本模块只编排动作序列。
+
+依赖: browser (operate)
+"""
+from __future__ import annotations
+import math
+import random
+import time
+from typing import Any
+
+import sys
+sys.path.insert(0, __file__.rsplit("\\", 1)[0] if "\\" in __file__ else __file__.rsplit("/", 1)[0])
+from browser import operate  # noqa: E402
+
+
+def _bezier(p0: float, p1: float, p2: float, p3: float, t: float) -> float:
+    u = 1 - t
+    return u * u * u * p0 + 3 * u * u * t * p1 + 3 * u * t * t * p2 + t * t * t * p3
+
+
+def _trajectory(from_pt: dict, to_pt: dict, steps: int) -> list[dict]:
+    """生成贝塞尔轨迹点 (含随机抖动)."""
+    pts = []
+    mx = (from_pt["x"] + to_pt["x"]) / 2 + (random.random() - 0.5) * abs(to_pt["x"] - from_pt["x"]) * 0.6
+    my = (from_pt["y"] + to_pt["y"]) / 2 + (random.random() - 0.5) * abs(to_pt["y"] - from_pt["y"]) * 0.6
+    c1 = {"x": from_pt["x"] + (mx - from_pt["x"]) * 0.3, "y": from_pt["y"] + (my - from_pt["y"]) * 0.3}
+    c2 = {"x": to_pt["x"] + (mx - to_pt["x"]) * 0.3, "y": to_pt["y"] + (my - to_pt["y"]) * 0.3}
+    for i in range(steps + 1):
+        t = i / steps
+        pts.append({
+            "x": _bezier(from_pt["x"], c1["x"], c2["x"], to_pt["x"], t) + (random.random() - 0.5) * 2,
+            "y": _bezier(from_pt["y"], c1["y"], c2["y"], to_pt["y"], t) + (random.random() - 0.5) * 2,
+        })
+    return pts
+
+
+def _random_point_in_rect(rect: dict) -> dict:
+    return {
+        "x": rect["x"] + rect["width"] * (0.3 + random.random() * 0.4),
+        "y": rect["y"] + rect["height"] * (0.3 + random.random() * 0.4),
+    }
+
+
+def _move_trajectory(page_handle: dict, from_pt: dict, to_pt: dict) -> None:
+    """沿贝塞尔轨迹多点 mouseMove 注入."""
+    pts = _trajectory(from_pt, to_pt, 10 + random.randint(0, 5))
+    for pt in pts:
+        operate(page_handle, {"action": "mouseMove", "x": pt["x"], "y": pt["y"]})
+        time.sleep(0.008 + random.random() * 0.016)
+
+
+def create_behavior(page_handle: dict) -> dict:
+    """创建绑定到 pageHandle 的行为模拟器.
+
+    返回: move_to, click, click_element, type_text, type_in_element, scroll_down, scroll_to_bottom, scroll_to_element
+    """
+    if not page_handle:
+        raise ValueError("create_behavior: page_handle required")
+    last_pos = {"x": 100, "y": 100}
+
+    def move_to(x: float, y: float) -> None:
+        nonlocal last_pos
+        _move_trajectory(page_handle, last_pos, {"x": x, "y": y})
+        last_pos = {"x": x, "y": y}
+
+    def click(x: float, y: float, options: dict | None = None) -> None:
+        nonlocal last_pos
+        _move_trajectory(page_handle, last_pos, {"x": x, "y": y})
+        last_pos = {"x": x, "y": y}
+        time.sleep(0.05 + random.random() * 0.1)
+        operate(page_handle, {"action": "click", "x": x, "y": y})
+        delay = (options or {}).get("delay", 0.05 + random.random() * 0.1)
+        time.sleep(delay)
+
+    def click_element(selector: str, timeout: int = 10000) -> None:
+        nonlocal last_pos
+        operate(page_handle, {"action": "waitForSelector", "selector": selector, "timeout": timeout})
+        box_r = operate(page_handle, {"action": "boundingBox", "selector": selector})
+        box = None
+        if isinstance(box_r, dict) and box_r.get("width") is not None:
+            box = box_r
+        if not box:
+            operate(page_handle, {"action": "click", "selector": selector})
+            time.sleep(0.05 + random.random() * 0.1)
+            return
+        pt = _random_point_in_rect(box)
+        move_to(pt["x"], pt["y"])
+        time.sleep(0.05 + random.random() * 0.1)
+        operate(page_handle, {"action": "click", "x": pt["x"], "y": pt["y"]})
+        time.sleep(0.05 + random.random() * 0.1)
+
+    def type_text(text: str, delay: float = 0.1) -> None:
+        for ch in text:
+            operate(page_handle, {"action": "press", "selector": "body", "key": ch})
+            d = delay * (0.5 + random.random())
+            if random.random() < 0.1:
+                d += 0.2 + random.random() * 0.4
+            time.sleep(d)
+
+    def type_in_element(selector: str, text: str, options: dict | None = None) -> None:
+        opts = options or {}
+        delay = opts.get("delay", 0.1)
+        timeout = opts.get("timeout", 10000)
+        operate(page_handle, {"action": "waitForSelector", "selector": selector, "timeout": timeout})
+        operate(page_handle, {"action": "click", "selector": selector})
+        operate(page_handle, {"action": "type", "selector": selector, "value": text, "delay": delay})
+
+    def scroll_down(pixels: int = 400) -> None:
+        step = 30 + random.randint(0, 29)
+        operate(page_handle, {
+            "action": "evaluate",
+            "source": f"(p) => new Promise((r) => {{ let done = 0; const t = setInterval(() => {{ window.scrollBy(0, {step}); done += {step}; if (done >= p) {{ clearInterval(t); r() }} }}, 30 + Math.random() * 30) }})",
+            "args": pixels
+        })
+
+    def scroll_to_bottom() -> None:
+        operate(page_handle, {
+            "action": "evaluate",
+            "source": "() => new Promise((resolve) => { let last=-1; const t=setInterval(()=>{ window.scrollBy(0,100+Math.random()*100); const h=document.body.scrollHeight; if(h===last){clearInterval(t);resolve()} last=h }, 150) })"
+        })
+
+    def scroll_to_element(selector: str, timeout: int = 10000) -> None:
+        operate(page_handle, {
+            "action": "evaluate",
+            "source": f'(s) => {{ const el = document.querySelector(s); if (el) el.scrollIntoView({{ behavior: "smooth", block: "center" }}) }}',
+            "args": selector
+        })
+
+    return {
+        "move_to": move_to, "click": click, "click_element": click_element,
+        "type_text": type_text, "type_in_element": type_in_element,
+        "scroll_down": scroll_down, "scroll_to_bottom": scroll_to_bottom,
+        "scroll_to_element": scroll_to_element,
+    }

browser.py

@@ -0,0 +1,469 @@
+"""Python client for the local MoonCat browserd HTTP service.
+
+The client contains no browser automation implementation. It only forwards
+requests to browserd, so Python programs and the JavaScript client use the same
+backend behavior.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import threading
+from typing import Any, Pattern
+from urllib.parse import urlparse
+
+import httpx
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 17322
+DEFAULT_TIMEOUT_MS = 60_000
+
+_rpc_seq = 0
+_rpc_seq_lock = threading.Lock()
+
+
+class BrowserdError(RuntimeError):
+    """Raised when browserd cannot be reached or rejects an RPC request."""
+
+
+def _next_id() -> int:
+    global _rpc_seq
+    with _rpc_seq_lock:
+        _rpc_seq += 1
+        return _rpc_seq
+
+
+def _compact(params: dict[str, Any]) -> dict[str, Any]:
+    """Drop None values while preserving false, zero, and empty strings."""
+    return {key: value for key, value in params.items() if value is not None}
+
+
+class Browser:
+    """Thin synchronous client for browserd.
+
+    Connection precedence is ``base_url`` > explicit ``host``/``port`` >
+    ``MOONCAT_BROWSERD_BASE_URL``/``MOONCAT_BROWSERD_HOST``/
+    ``MOONCAT_BROWSERD_PORT`` > local defaults.
+
+    No local "browser open" flag is kept. browserd is the source of truth,
+    which means a process can connect to and operate a browser opened by
+    another process.
+    """
+
+    def __init__(
+        self,
+        host: str | None = None,
+        port: int | None = None,
+        base_url: str | None = None,
+        timeout_ms: int = DEFAULT_TIMEOUT_MS,
+    ) -> None:
+        configured_base = base_url or os.getenv("MOONCAT_BROWSERD_BASE_URL")
+        if configured_base:
+            parsed = urlparse(configured_base if "://" in configured_base else f"http://{configured_base}")
+            if parsed.scheme not in {"http", "https"} or not parsed.hostname:
+                raise ValueError(f"invalid browserd base_url: {configured_base!r}")
+            self.base_url = f"{parsed.scheme}://{parsed.hostname}"
+            if parsed.port:
+                self.base_url += f":{parsed.port}"
+            if parsed.path and parsed.path != "/":
+                self.base_url += parsed.path.rstrip("/")
+        else:
+            resolved_host = host or os.getenv("MOONCAT_BROWSERD_HOST") or DEFAULT_HOST
+            resolved_port = port
+            if resolved_port is None:
+                raw_port = os.getenv("MOONCAT_BROWSERD_PORT")
+                resolved_port = int(raw_port) if raw_port else DEFAULT_PORT
+            self.base_url = f"http://{resolved_host}:{resolved_port}"
+
+        if timeout_ms <= 0:
+            raise ValueError("timeout_ms must be greater than zero")
+        self.default_timeout_ms = timeout_ms
+        self.rpc_url = f"{self.base_url}/rpc"
+        self.health_url = f"{self.base_url}/health"
+
+    def health(self, timeout_ms: int = 2_000) -> dict[str, Any] | None:
+        """Return browserd health data, or ``None`` when it is unavailable."""
+        try:
+            response = httpx.get(self.health_url, timeout=timeout_ms / 1_000)
+            if response.status_code == 200:
+                data = response.json()
+                return data if isinstance(data, dict) else None
+        except (httpx.HTTPError, OSError, json.JSONDecodeError):
+            pass
+        return None
+
+    def _ensure_browserd(self) -> None:
+        if self.health():
+            return
+        raise BrowserdError(
+            f"browserd is not running at {self.base_url}. "
+            "Start the local MoonCat browser service first."
+        )
+
+    def _rpc(
+        self,
+        method: str,
+        params: dict[str, Any] | None = None,
+        timeout_ms: int | None = None,
+    ) -> Any:
+        timeout = timeout_ms if timeout_ms is not None else self.default_timeout_ms
+        payload = {"id": _next_id(), "method": method, "params": params or {}}
+        try:
+            response = httpx.post(self.rpc_url, json=payload, timeout=timeout / 1_000)
+            data = response.json()
+        except (httpx.HTTPError, OSError, json.JSONDecodeError) as exc:
+            raise BrowserdError(f"browserd RPC failed ({method}): {exc}") from exc
+
+        if not isinstance(data, dict):
+            raise BrowserdError(f"{method}: invalid RPC response")
+        if not data.get("ok"):
+            raise BrowserdError(f"{method}: {data.get('error', 'rpc failed')}")
+        return data.get("result")
+
+    def open(
+        self,
+        route_mode: str = "auto",
+        headless: bool = False,
+        browser_owner: str | None = None,
+        extension_connect_timeout_ms: int | None = None,
+        **legacy_options: Any,
+    ) -> dict[str, Any]:
+        """Open or attach to the browser and return its browser handle."""
+        self._ensure_browserd()
+        params = _compact(
+            {
+                "routeMode": route_mode,
+                "headless": headless,
+                "browserOwner": browser_owner,
+                "extensionConnectTimeoutMs": extension_connect_timeout_ms,
+                **legacy_options,
+            }
+        )
+        return self._rpc("open", params, timeout_ms=120_000)
+
+    def new_tab(self, url: str = "", force: bool = False) -> dict[str, Any]:
+        """Create/reuse a tab and return ``TabInfo`` containing ``pageHandle``."""
+        return self._rpc("newTab", {"url": url, "force": force})
+
+    def list_tabs(self) -> list[dict[str, Any]]:
+        """List tabs and normalize each item to a ``TabInfo`` dictionary."""
+        raw = self._rpc("listTabs", {})
+        if not isinstance(raw, list):
+            return []
+        result: list[dict[str, Any]] = []
+        for index, item in enumerate(raw):
+            if not isinstance(item, dict):
+                raise BrowserdError(f"listTabs: tab {index} is not an object")
+            page_handle = item.get("pageHandle", item)
+            if not isinstance(page_handle, dict) or not page_handle.get("pageId"):
+                raise BrowserdError(f"listTabs: tab {index} is missing pageHandle.pageId")
+            result.append(
+                {
+                    **item,
+                    "pageHandle": page_handle,
+                    "url": item.get("url", page_handle.get("url")),
+                }
+            )
+        return result
+
+    def reuse_tab(
+        self,
+        url: str = "",
+        url_match: str | Pattern[str] | None = None,
+    ) -> dict[str, Any]:
+        """Reuse a matching tab, or create one when no match exists."""
+        pattern = url_match.pattern if hasattr(url_match, "pattern") else url_match
+        return self._rpc("reuseTab", _compact({"url": url, "urlMatch": pattern}))
+
+    def find_or_new_tab(
+        self,
+        url: str,
+        match: str = "includes",
+        new_if_missing: bool = True,
+    ) -> dict[str, Any] | None:
+        """Compatibility helper that returns a page handle, not ``TabInfo``."""
+        if match not in {"includes", "exact"}:
+            raise ValueError("match must be 'includes' or 'exact'")
+        tabs = self.list_tabs()
+        for tab in tabs:
+            current_url = str(tab.get("url", ""))
+            found = current_url == url if match == "exact" else url in current_url
+            if found:
+                return tab["pageHandle"]
+        if not new_if_missing:
+            return None
+        tab = self.new_tab(url)
+        return tab.get("pageHandle", tab)
+
+    @staticmethod
+    def _page_handle(value: dict[str, Any]) -> dict[str, Any]:
+        """Accept either a PageHandle or the TabInfo returned by new_tab()."""
+        if not isinstance(value, dict):
+            raise BrowserdError("invalid pageHandle: expected a dictionary")
+        page_handle = value.get("pageHandle", value)
+        if not isinstance(page_handle, dict) or not page_handle.get("pageId"):
+            raise BrowserdError("invalid pageHandle: missing pageId")
+        return page_handle
+
+    def operate(
+        self,
+        page_handle: dict[str, Any],
+        action: str,
+        timeout_ms: int | None = None,
+        **params: Any,
+    ) -> Any:
+        """Run one of browserd's page actions."""
+        return self._rpc(
+            "operate",
+            {
+                "pageHandle": self._page_handle(page_handle),
+                "action": action,
+                "params": params,
+            },
+            timeout_ms=timeout_ms,
+        )
+
+    def get_cookies(self, **filters: Any) -> Any:
+        return self._rpc("getCookies", filters)
+
+    def set_cookies(self, cookies: list[dict[str, Any]]) -> Any:
+        return self._rpc("setCookies", {"cookies": cookies})
+
+    def clear_cookies(self, **filters: Any) -> Any:
+        return self._rpc("clearCookies", filters)
+
+    def close_browser(self) -> dict[str, Any]:
+        """Close Chrome but keep browserd running for a later warm open."""
+        return self._rpc("closeBrowser", {})
+
+    def close(self) -> dict[str, Any]:
+        """Close Chrome and stop browserd."""
+        return self._rpc("close", {})
+
+    def list_downloads(self, limit: int = 20) -> dict[str, Any]:
+        return self._rpc("listDownloads", {"limit": limit})
+
+    def download_url(
+        self,
+        url: str,
+        filename: str | None = None,
+        conflict_action: str | None = None,
+        save_as: bool | None = None,
+    ) -> dict[str, Any]:
+        return self._rpc(
+            "downloadUrl",
+            _compact(
+                {
+                    "url": url,
+                    "filename": filename,
+                    "conflictAction": conflict_action,
+                    "saveAs": save_as,
+                }
+            ),
+        )
+
+    def get_download(self, download_id: int) -> dict[str, Any]:
+        return self._rpc("getDownload", {"id": download_id})
+
+    def wait_for_download(
+        self,
+        download_id: int | None = None,
+        filename_regex: str | None = None,
+        since_ms: int | None = None,
+        timeout_ms: int = 60_000,
+        interval_ms: int | None = None,
+    ) -> dict[str, Any]:
+        params = _compact(
+            {
+                "id": download_id,
+                "filenameRegex": filename_regex,
+                "sinceMs": since_ms,
+                "timeoutMs": timeout_ms,
+                "intervalMs": interval_ms,
+            }
+        )
+        return self._rpc("waitForDownload", params, timeout_ms=timeout_ms + 5_000)
+
+    def download_url_and_wait(
+        self,
+        url: str,
+        filename: str | None = None,
+        conflict_action: str | None = None,
+        save_as: bool | None = None,
+        timeout_ms: int = 60_000,
+        interval_ms: int | None = None,
+    ) -> dict[str, Any]:
+        started = self.download_url(url, filename, conflict_action, save_as)
+        waited = self.wait_for_download(
+            download_id=started["id"],
+            timeout_ms=timeout_ms,
+            interval_ms=interval_ms,
+        )
+        return {"id": started["id"], **waited}
+
+    def allow_automatic_downloads(
+        self,
+        primary_pattern: str,
+        secondary_pattern: str | None = None,
+        scope: str | None = None,
+    ) -> dict[str, Any]:
+        return self._rpc(
+            "allowAutomaticDownloads",
+            _compact(
+                {
+                    "primaryPattern": primary_pattern,
+                    "secondaryPattern": secondary_pattern,
+                    "scope": scope,
+                }
+            ),
+        )
+
+    def get_automatic_downloads_setting(
+        self,
+        primary_url: str | None = None,
+        primary_pattern: str | None = None,
+        secondary_url: str | None = None,
+        secondary_pattern: str | None = None,
+        incognito: bool | None = None,
+        scope: str | None = None,
+    ) -> dict[str, Any]:
+        return self._rpc(
+            "getAutomaticDownloadsSetting",
+            _compact(
+                {
+                    "primaryUrl": primary_url,
+                    "primaryPattern": primary_pattern,
+                    "secondaryUrl": secondary_url,
+                    "secondaryPattern": secondary_pattern,
+                    "incognito": incognito,
+                    "scope": scope,
+                }
+            ),
+        )
+
+    def reset_automatic_downloads_setting(
+        self,
+        primary_pattern: str,
+        secondary_pattern: str | None = None,
+        scope: str | None = None,
+    ) -> dict[str, Any]:
+        return self._rpc(
+            "resetAutomaticDownloadsSetting",
+            _compact(
+                {
+                    "primaryPattern": primary_pattern,
+                    "secondaryPattern": secondary_pattern,
+                    "scope": scope,
+                }
+            ),
+        )
+
+    # Small action conveniences. Complex behavior remains in browserd.
+    def goto(self, page_handle: dict[str, Any], url: str) -> Any:
+        return self.operate(page_handle, "goto", url=url)
+
+    def click(
+        self,
+        page_handle: dict[str, Any],
+        selector: str,
+        x: float | None = None,
+        y: float | None = None,
+    ) -> Any:
+        return self.operate(page_handle, "click", **_compact({"selector": selector, "x": x, "y": y}))
+
+    def fill(self, page_handle: dict[str, Any], selector: str, value: str) -> Any:
+        return self.operate(page_handle, "fill", selector=selector, value=value)
+
+    def press(self, page_handle: dict[str, Any], selector: str, key: str) -> Any:
+        return self.operate(page_handle, "press", selector=selector, key=key)
+
+    def status(self, page_handle: dict[str, Any]) -> dict[str, Any]:
+        return self.operate(page_handle, "status")
+
+    def snapshot(self, page_handle: dict[str, Any], **options: Any) -> Any:
+        return self.operate(page_handle, "snapshot", **options)
+
+    def evaluate(self, page_handle: dict[str, Any], source: str, args: Any = None) -> Any:
+        return self.operate(page_handle, "evaluate", **_compact({"source": source, "args": args}))
+
+    def screenshot(self, page_handle: dict[str, Any]) -> Any:
+        return self.operate(page_handle, "screenshot")
+
+    def inner_text(self, page_handle: dict[str, Any], selector: str) -> str:
+        return self.operate(page_handle, "innerText", selector=selector)
+
+    def wait_for_selector(
+        self,
+        page_handle: dict[str, Any],
+        selector: str,
+        timeout: int | None = None,
+    ) -> Any:
+        return self.operate(
+            page_handle,
+            "waitForSelector",
+            **_compact({"selector": selector, "timeout": timeout}),
+        )
+
+
+_default_browser: Browser | None = None
+
+
+def _get_browser() -> Browser:
+    global _default_browser
+    if _default_browser is None:
+        _default_browser = Browser()
+    return _default_browser
+
+
+def configure(**options: Any) -> Browser:
+    """Replace and return the module-level client with custom connection options."""
+    global _default_browser
+    _default_browser = Browser(**options)
+    return _default_browser
+
+
+def health(timeout_ms: int = 2_000) -> dict[str, Any] | None:
+    return _get_browser().health(timeout_ms)
+
+
+def open_browser(**options: Any) -> dict[str, Any]:
+    return _get_browser().open(**options)
+
+
+def new_tab(url: str = "", force: bool = False) -> dict[str, Any]:
+    return _get_browser().new_tab(url, force)
+
+
+def list_tabs(browser_handle: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+    del browser_handle
+    return _get_browser().list_tabs()
+
+
+def reuse_tab(url: str = "", url_match: str | Pattern[str] | None = None) -> dict[str, Any]:
+    return _get_browser().reuse_tab(url, url_match)
+
+
+def find_or_new_tab(
+    url: str,
+    match: str = "includes",
+    new_if_missing: bool = True,
+) -> dict[str, Any] | None:
+    return _get_browser().find_or_new_tab(url, match, new_if_missing)
+
+
+def operate(page_handle: dict[str, Any], params: dict[str, Any]) -> Any:
+    action = params.get("action")
+    if not action:
+        raise ValueError("operate: params is missing 'action'")
+    timeout_ms = params.get("timeoutMs")
+    kwargs = {
+        key: value
+        for key, value in params.items()
+        if key not in {"action", "timeoutMs", "_skipVisualize", "_skipHumanize", "label"}
+    }
+    return _get_browser().operate(page_handle, str(action), timeout_ms=timeout_ms, **kwargs)
+
+
+def close_browser(stop_daemon: bool = True) -> dict[str, Any]:
+    return _get_browser().close() if stop_daemon else _get_browser().close_browser()