pybroswer 0.3.1__py3-none-any.whl

pybroswer/__init__.py

@@ -0,0 +1,40 @@
+"""Python browser for PyDroid. HTTP engine in-app; optional remote Chromium."""
+
+from pybroswer.client import Browser
+from pybroswer.exceptions import ActionFailed, ApiError, EngineError, PyBroswerError, SessionNotFound
+from pybroswer.models import (
+    DevicePreset,
+    FrameInfo,
+    FrameTarget,
+    Health,
+    InspectResult,
+    LogEntry,
+    SessionInfo,
+    Snapshot,
+    UploadFile,
+    Viewport,
+)
+from pybroswer.session import Session
+
+__all__ = [
+    "ActionFailed",
+    "ApiError",
+    "Browser",
+    "DevicePreset",
+    "EngineError",
+    "FrameInfo",
+    "FrameTarget",
+    "Health",
+    "InspectResult",
+    "LogEntry",
+    "PyBroswerError",
+    "Session",
+    "SessionInfo",
+    "SessionNotFound",
+    "Snapshot",
+    "UploadFile",
+    "Viewport",
+    "__version__",
+]
+
+__version__ = "0.3.1"

pybroswer/__main__.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import argparse
+
+from pybroswer.server import serve
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="pybroswer", description="Local Chromium REST for PyDroid")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    serve_p = sub.add_parser("serve", help="Start Chromium on this PC and expose REST for phones")
+    serve_p.add_argument("--host", default="0.0.0.0")
+    serve_p.add_argument("--port", type=int, default=5173)
+    serve_p.add_argument("--headed", action="store_true", help="Show the browser window")
+
+    args = parser.parse_args()
+    if args.cmd == "serve":
+        serve(host=args.host, port=args.port, headless=not args.headed)
+
+
+if __name__ == "__main__":
+    main()

pybroswer/_http.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+import httpx
+
+from pybroswer.exceptions import ActionFailed, ApiError, SessionNotFound
+
+
+class Transport(Protocol):
+    base_url: str
+
+    def close(self) -> None: ...
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        expect_json: bool = True,
+    ) -> Any: ...
+
+
+class HttpTransport:
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        timeout: float = 60.0,
+        headers: dict[str, str] | None = None,
+        client: httpx.Client | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._owns = client is None
+        self._client = client or httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={"Accept": "application/json", **(headers or {})},
+            follow_redirects=True,
+        )
+
+    def close(self) -> None:
+        if self._owns:
+            self._client.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        expect_json: bool = True,
+    ) -> Any:
+        response = self._client.request(method, path, json=json, params=params)
+        if response.status_code == 404:
+            payload = _safe_json(response)
+            message = _error_message(payload, response)
+            if "session" in message.lower():
+                raise SessionNotFound(message, status_code=404, payload=payload)
+            raise ApiError(message, status_code=404, payload=payload)
+        if response.status_code >= 400:
+            payload = _safe_json(response)
+            raise ApiError(_error_message(payload, response), status_code=response.status_code, payload=payload)
+        if not expect_json:
+            return response.content
+        if not response.content:
+            return {}
+        ctype = response.headers.get("content-type", "")
+        if "application/json" not in ctype:
+            return response.content
+        data = response.json()
+        if isinstance(data, dict) and data.get("ok") is False and data.get("error"):
+            raise ActionFailed(str(data["error"]), status_code=response.status_code, payload=data)
+        return data
+
+
+def _safe_json(response: httpx.Response) -> dict[str, Any]:
+    try:
+        data = response.json()
+    except Exception:
+        return {"error": response.text}
+    return data if isinstance(data, dict) else {"error": data}
+
+
+def _error_message(payload: dict[str, Any], response: httpx.Response) -> str:
+    return str(payload.get("error") or response.reason_phrase or f"HTTP {response.status_code}")

pybroswer/client.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pybroswer._http import HttpTransport, Transport
+from pybroswer.models import (
+    DeviceName,
+    DevicePreset,
+    Health,
+    SessionInfo,
+    Snapshot,
+    presets_from,
+    session_info_from,
+    snapshot_from,
+)
+from pybroswer.session import Session
+
+
+class Browser:
+    def __init__(
+        self,
+        base_url: str | None = None,
+        *,
+        timeout: float = 60.0,
+        headers: dict[str, str] | None = None,
+        transport: Transport | None = None,
+        engine: Any | None = None,
+    ) -> None:
+        if transport is not None:
+            self._http: Transport = transport
+        elif engine is not None:
+            from pybroswer.engine import EngineTransport
+
+            self._http = EngineTransport(engine, owns=False)
+        elif base_url:
+            self._http = HttpTransport(base_url, timeout=timeout, headers=headers)
+        else:
+            self._http = _http_engine_transport(max_sessions=5, idle_ms=10 * 60 * 1000, timeout=timeout)
+
+    @classmethod
+    def launch(
+        cls,
+        *,
+        engine: str = "http",
+        headless: bool = True,
+        max_sessions: int = 5,
+        idle_ms: int = 10 * 60 * 1000,
+        timeout: float = 30.0,
+        executable_path: str | None = None,
+        channel: str | None = None,
+    ) -> Browser:
+        from pybroswer.engine import EngineTransport
+
+        if engine in {"chromium", "playwright"}:
+            from pybroswer.engine import ChromiumEngine
+
+            chromium = ChromiumEngine(
+                headless=headless,
+                max_sessions=max_sessions,
+                idle_ms=idle_ms,
+                executable_path=executable_path,
+                channel=channel,
+            )
+            chromium.start()
+            return cls(transport=EngineTransport(chromium, owns=True))
+        return cls(transport=_http_engine_transport(max_sessions=max_sessions, idle_ms=idle_ms, timeout=timeout))
+
+    @classmethod
+    def connect(
+        cls,
+        url: str = "http://127.0.0.1:5173",
+        *,
+        timeout: float = 60.0,
+        headers: dict[str, str] | None = None,
+    ) -> Browser:
+        return cls(url, timeout=timeout, headers=headers)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def health(self) -> Health:
+        data = self._http.request("GET", "/api/v1/health")
+        return Health(
+            ok=bool(data.get("ok")),
+            service=data.get("service"),
+            engine=data.get("engine"),
+            sessions=int(data.get("sessions") or 0),
+            max_sessions=int(data.get("maxSessions") or 0),
+            error=data.get("error"),
+        )
+
+    def ua_presets(self) -> list[DevicePreset]:
+        data = self._http.request("GET", "/api/v1/ua")
+        return presets_from(data.get("presets"))
+
+    def sessions(self) -> list[SessionInfo]:
+        data = self._http.request("GET", "/api/v1/sessions")
+        return [session_info_from(item) for item in data.get("sessions") or []]
+
+    def create_session(
+        self,
+        *,
+        device: DeviceName | str = "mobile",
+        url: str | None = None,
+        user_agent: str | None = None,
+        width: int | None = None,
+        height: int | None = None,
+    ) -> Session:
+        body: dict[str, Any] = {"device": device}
+        if url:
+            body["url"] = url
+        if user_agent:
+            body["userAgent"] = user_agent
+        if width is not None:
+            body["width"] = width
+        if height is not None:
+            body["height"] = height
+        data = self._http.request("POST", "/api/v1/sessions", json=body)
+        return Session(self._http, str(data["id"]))
+
+    def session(self, session_id: str) -> Session:
+        return Session(self._http, session_id)
+
+    def browse(
+        self,
+        url: str,
+        *,
+        device: DeviceName | str = "desktop",
+        user_agent: str | None = None,
+        width: int | None = None,
+        height: int | None = None,
+    ) -> Snapshot:
+        body: dict[str, Any] = {"url": url, "device": device}
+        if user_agent:
+            body["userAgent"] = user_agent
+        if width is not None:
+            body["width"] = width
+        if height is not None:
+            body["height"] = height
+        return snapshot_from(self._http.request("POST", "/api/v1/browse", json=body))
+
+    def __enter__(self) -> Browser:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+def _http_engine_transport(*, max_sessions: int, idle_ms: int, timeout: float) -> Any:
+    from pybroswer.engine import EngineTransport
+    from pybroswer.http_engine import HttpEngine
+
+    engine = HttpEngine(max_sessions=max_sessions, idle_ms=idle_ms, timeout=timeout)
+    engine.start()
+    return EngineTransport(engine, owns=True)

pybroswer/dom.py

@@ -0,0 +1,351 @@
+from __future__ import annotations
+
+import re
+from html.parser import HTMLParser
+from typing import Any
+from urllib.parse import urljoin
+
+VOID = {
+    "area",
+    "base",
+    "br",
+    "col",
+    "embed",
+    "hr",
+    "img",
+    "input",
+    "link",
+    "meta",
+    "param",
+    "source",
+    "track",
+    "wbr",
+}
+
+
+class Node:
+    __slots__ = ("tag", "attrs", "children", "parent")
+
+    def __init__(self, tag: str, attrs: dict[str, str] | None = None, parent: Node | None = None) -> None:
+        self.tag = tag.lower()
+        self.attrs = {k.lower(): v for k, v in (attrs or {}).items()}
+        self.children: list[Node | str] = []
+        self.parent = parent
+
+    @property
+    def id(self) -> str:
+        return self.attrs.get("id", "")
+
+    @property
+    def name(self) -> str:
+        return self.attrs.get("name", "")
+
+    @property
+    def type(self) -> str:
+        return self.attrs.get("type", "")
+
+    @property
+    def classes(self) -> set[str]:
+        return {c for c in self.attrs.get("class", "").split() if c}
+
+    @property
+    def href(self) -> str | None:
+        return self.attrs.get("href")
+
+    @property
+    def value(self) -> str:
+        if "value" in self.attrs:
+            return self.attrs["value"]
+        if self.tag == "textarea":
+            return self.inner_text
+        return ""
+
+    @value.setter
+    def value(self, text: str) -> None:
+        self.attrs["value"] = text
+        if self.tag in {"textarea", "option"}:
+            self.children = [text]
+
+    @property
+    def inner_text(self) -> str:
+        parts: list[str] = []
+        for child in self.children:
+            if isinstance(child, str):
+                parts.append(child)
+            elif child.tag not in {"script", "style"}:
+                parts.append(child.inner_text)
+        return re.sub(r"\s+", " ", "".join(parts)).strip()
+
+    @property
+    def inner_html(self) -> str:
+        return "".join(_serialize(c) for c in self.children)
+
+    def descendants(self) -> list[Node]:
+        out: list[Node] = []
+        for child in self.children:
+            if isinstance(child, Node):
+                out.append(child)
+                out.extend(child.descendants())
+        return out
+
+    def form(self) -> Node | None:
+        node: Node | None = self
+        while node is not None:
+            if node.tag == "form":
+                return node
+            node = node.parent
+        return None
+
+
+def _serialize(node: Node | str) -> str:
+    if isinstance(node, str):
+        return node
+    attrs = "".join(f' {k}="{v}"' for k, v in node.attrs.items())
+    if node.tag in VOID:
+        return f"<{node.tag}{attrs}>"
+    return f"<{node.tag}{attrs}>{''.join(_serialize(c) for c in node.children)}</{node.tag}>"
+
+
+class _Parser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.root = Node("document")
+        self._stack = [self.root]
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        parent = self._stack[-1]
+        node = Node(tag, {k: v or "" for k, v in attrs}, parent)
+        parent.children.append(node)
+        if tag.lower() not in VOID:
+            self._stack.append(node)
+
+    def handle_endtag(self, tag: str) -> None:
+        tag = tag.lower()
+        if tag in VOID:
+            return
+        for i in range(len(self._stack) - 1, 0, -1):
+            if self._stack[i].tag == tag:
+                del self._stack[i:]
+                break
+
+    def handle_data(self, data: str) -> None:
+        if data:
+            self._stack[-1].children.append(data)
+
+
+def parse_html(html: str) -> Node:
+    parser = _Parser()
+    parser.feed(html or "")
+    parser.close()
+    return parser.root
+
+
+def document_element(root: Node) -> Node:
+    for child in root.children:
+        if isinstance(child, Node) and child.tag == "html":
+            return child
+    return root
+
+
+def title_of(root: Node) -> str:
+    for node in root.descendants():
+        if node.tag == "title":
+            return node.inner_text
+    return ""
+
+
+def body_of(root: Node) -> Node | None:
+    for node in root.descendants():
+        if node.tag == "body":
+            return node
+    return None
+
+
+_ATTR_RE = re.compile(
+    r"\[([^\s\]=~|^$*]+)\s*(?:([~|^$*]?=)\s*(?:\"([^\"]*)\"|'([^']*)'|([^\]]+)))?\]"
+)
+_SIMPLE_RE = re.compile(r"([a-zA-Z][\w:-]*|\*)|#([\w-]+)|\.([\w-]+)|(\[[^\]]+\])")
+
+
+def query_all(root: Node, selector: str) -> list[Node]:
+    selector = (selector or "").strip()
+    if not selector:
+        return []
+    found: list[Node] = []
+    seen: set[int] = set()
+    for group in selector.split(","):
+        for node in _query_group(root, group.strip()):
+            key = id(node)
+            if key not in seen:
+                seen.add(key)
+                found.append(node)
+    return found
+
+
+def query_one(root: Node, selector: str) -> Node | None:
+    nodes = query_all(root, selector)
+    return nodes[0] if nodes else None
+
+
+def _query_group(root: Node, selector: str) -> list[Node]:
+    parts = re.split(r"\s*(>|\s+)\s*", selector.strip())
+    parts = [p for p in parts if p and p.strip()]
+    combinators: list[str] = []
+    simples: list[str] = []
+    expect = "simple"
+    for part in parts:
+        if part in {">"}:
+            combinators.append(part)
+            expect = "simple"
+            continue
+        if expect == "simple":
+            if simples:
+                combinators.append(" ")
+            simples.append(part)
+            expect = "combo"
+        else:
+            combinators.append(" ")
+            simples.append(part)
+    if not simples:
+        return []
+    matches = [n for n in _all_nodes(root) if _match_simple(n, simples[0])]
+    for combo, simple in zip(combinators, simples[1:]):
+        nxt: list[Node] = []
+        seen: set[int] = set()
+        for node in matches:
+            candidates = node.children if combo == ">" else node.descendants()
+            for child in candidates:
+                if isinstance(child, Node) and _match_simple(child, simple) and id(child) not in seen:
+                    seen.add(id(child))
+                    nxt.append(child)
+        matches = nxt
+    return matches
+
+
+def _all_nodes(root: Node) -> list[Node]:
+    return [root, *root.descendants()]
+
+
+def _match_simple(node: Node, simple: str) -> bool:
+    tag = None
+    nid = None
+    classes: list[str] = []
+    attrs: list[tuple[str, str | None, str | None]] = []
+    pos = 0
+    for m in _SIMPLE_RE.finditer(simple):
+        if m.start() != pos:
+            return False
+        pos = m.end()
+        if m.group(1):
+            tag = m.group(1).lower()
+        elif m.group(2):
+            nid = m.group(2)
+        elif m.group(3):
+            classes.append(m.group(3))
+        else:
+            am = _ATTR_RE.match(m.group(4))
+            if not am:
+                return False
+            op = am.group(2)
+            val = am.group(3) or am.group(4) or am.group(5)
+            if val:
+                val = val.strip()
+            attrs.append((am.group(1).lower(), op, val))
+    if pos != len(simple):
+        return False
+    if tag and tag != "*" and node.tag != tag:
+        return False
+    if nid is not None and node.id != nid:
+        return False
+    if any(cls not in node.classes for cls in classes):
+        return False
+    for name, op, val in attrs:
+        actual = node.attrs.get(name)
+        if op is None:
+            if actual is None:
+                return False
+            continue
+        if actual is None:
+            return False
+        if op == "=" and actual != val:
+            return False
+        if op == "~=" and val not in actual.split():
+            return False
+        if op == "|=" and actual != val and not actual.startswith(f"{val}-"):
+            return False
+        if op == "^=" and not actual.startswith(val or ""):
+            return False
+        if op == "$=" and not actual.endswith(val or ""):
+            return False
+        if op == "*=" and (val or "") not in actual:
+            return False
+    return True
+
+
+def form_fields(form: Node) -> dict[str, str]:
+    data: dict[str, str] = {}
+    for node in form.descendants():
+        if node.tag not in {"input", "textarea", "select"}:
+            continue
+        name = node.name
+        if not name:
+            continue
+        if node.tag == "input" and node.type in {"submit", "button", "image", "reset", "file"}:
+            continue
+        if node.tag == "input" and node.type in {"checkbox", "radio"} and "checked" not in node.attrs:
+            continue
+        if node.tag == "select":
+            selected = None
+            first = None
+            for opt in node.descendants():
+                if opt.tag != "option":
+                    continue
+                if first is None:
+                    first = opt.attrs.get("value", opt.inner_text)
+                if "selected" in opt.attrs:
+                    selected = opt.attrs.get("value", opt.inner_text)
+                    break
+            data[name] = selected if selected is not None else (first or "")
+            continue
+        data[name] = node.value
+    return data
+
+
+def form_action(form: Node, base: str) -> tuple[str, str]:
+    method = (form.attrs.get("method") or "GET").upper()
+    action = form.attrs.get("action") or base
+    return method, urljoin(base, action)
+
+
+def frames_of(root: Node, page_url: str) -> list[dict[str, Any]]:
+    out = [{"index": 0, "name": "", "url": page_url, "parentUrl": None, "isMain": True}]
+    i = 1
+    for node in root.descendants():
+        if node.tag != "iframe":
+            continue
+        src = node.attrs.get("src") or ""
+        out.append(
+            {
+                "index": i,
+                "name": node.attrs.get("name") or node.id,
+                "url": urljoin(page_url, src) if src else "",
+                "parentUrl": page_url,
+                "isMain": False,
+            }
+        )
+        i += 1
+    return out
+
+
+def inspect_node(node: Node) -> dict[str, Any]:
+    return {
+        "tag": node.tag.upper(),
+        "id": node.id,
+        "name": node.name or None,
+        "type": node.type or None,
+        "value": node.value,
+        "text": node.inner_text[:2000],
+        "href": node.href,
+        "visible": True,
+        "rect": {"x": 0, "y": 0, "width": 0, "height": 0, "top": 0, "right": 0, "bottom": 0, "left": 0},
+    }