cdpwave 0.1.0__py3-none-any.whl

cdpwave/__init__.py

@@ -0,0 +1,34 @@
+__version__ = "0.1.0"
+
+from cdpwave.client import CDPClient, CDPSession
+from cdpwave.events.dispatcher import EventDispatcher
+from cdpwave.events.handlers import EventHandler, Subscription
+from cdpwave.exceptions import (
+    BrowserNotFoundError,
+    CDPError,
+    CommandError,
+    CommandTimeoutError,
+    ConnectionClosedError,
+    DiscoveryError,
+    LaunchError,
+    LaunchTimeoutError,
+    SessionClosedError,
+)
+
+__all__ = [
+    "CDPClient",
+    "CDPSession",
+    "CDPError",
+    "ConnectionClosedError",
+    "CommandError",
+    "CommandTimeoutError",
+    "BrowserNotFoundError",
+    "SessionClosedError",
+    "DiscoveryError",
+    "EventDispatcher",
+    "Subscription",
+    "EventHandler",
+    "LaunchError",
+    "LaunchTimeoutError",
+    "__version__",
+]

cdpwave/browser/discovery.py

@@ -0,0 +1,86 @@
+import asyncio
+import json
+import urllib.request
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class TargetInfo:
+    target_id: str
+    type: str
+    title: str
+    url: str
+    web_socket_debugger_url: str | None
+
+
+@dataclass(frozen=True)
+class VersionInfo:
+    browser: str
+    protocol_version: str
+    user_agent: str
+    web_socket_debugger_url: str
+
+
+def _http_get(url: str) -> Any:
+    with urllib.request.urlopen(url, timeout=10) as resp:
+        data = json.loads(resp.read().decode("utf-8"))
+        return data
+
+
+def _http_put(url: str) -> Any:
+    req = urllib.request.Request(url, method="PUT")
+    with urllib.request.urlopen(req, timeout=10) as resp:
+        data = json.loads(resp.read().decode("utf-8"))
+        return data
+
+
+class TargetDiscovery:
+    def __init__(self, host: str = "localhost", port: int = 9222) -> None:
+        self._base_url = f"http://{host}:{port}"
+
+    async def get_version(self) -> VersionInfo:
+        data: dict[str, Any] = await asyncio.to_thread(
+            _http_get, f"{self._base_url}/json/version"
+        )
+        return VersionInfo(
+            browser=str(data.get("Browser", "")),
+            protocol_version=str(data.get("Protocol-Version", "")),
+            user_agent=str(data.get("User-Agent", "")),
+            web_socket_debugger_url=str(data.get("webSocketDebuggerUrl", "")),
+        )
+
+    async def list_targets(self) -> list[TargetInfo]:
+        data: list[dict[str, Any]] = await asyncio.to_thread(
+            _http_get, f"{self._base_url}/json/list"
+        )
+        targets: list[TargetInfo] = []
+        for item in data:
+            targets.append(
+                TargetInfo(
+                    target_id=str(item.get("id", "")),
+                    type=str(item.get("type", "")),
+                    title=str(item.get("title", "")),
+                    url=str(item.get("url", "")),
+                    web_socket_debugger_url=item.get("webSocketDebuggerUrl"),
+                )
+            )
+        return targets
+
+    async def new_tab(self, url: str = "about:blank") -> TargetInfo:
+        data: dict[str, Any] = await asyncio.to_thread(
+            _http_put, f"{self._base_url}/json/new?{url}"
+        )
+        return TargetInfo(
+            target_id=str(data.get("id", "")),
+            type=str(data.get("type", "")),
+            title=str(data.get("title", "")),
+            url=str(data.get("url", "")),
+            web_socket_debugger_url=data.get("webSocketDebuggerUrl"),
+        )
+
+    async def activate_tab(self, target_id: str) -> None:
+        await asyncio.to_thread(_http_get, f"{self._base_url}/json/activate/{target_id}")
+
+    async def close_tab(self, target_id: str) -> None:
+        await asyncio.to_thread(_http_get, f"{self._base_url}/json/close/{target_id}")

cdpwave/browser/finder.py

@@ -0,0 +1,130 @@
+import os
+import shutil
+import sys
+
+from cdpwave.exceptions import BrowserNotFoundError
+from cdpwave.types import BrowserType
+
+_WIN_CHROME_PATHS = [
+    r"C:\Program Files\Google\Chrome\Application\chrome.exe",
+    r"C:\Program Files (x86)\Google\Chrome\Application\chrome.exe",
+]
+
+_WIN_EDGE_PATHS = [
+    r"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe",
+    r"C:\Program Files\Microsoft\Edge\Application\msedge.exe",
+]
+
+_WIN_BRAVE_PATHS = [
+    os.path.expandvars(r"%LOCALAPPDATA%\BraveSoftware\Brave-Browser\Application\brave.exe"),
+    r"C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe",
+    r"C:\Program Files (x86)\BraveSoftware\Brave-Browser\Application\brave.exe",
+]
+
+_WIN_CHROMIUM_PATHS = [
+    r"C:\Program Files\Chromium\Application\chromium.exe",
+    r"C:\Program Files (x86)\Chromium\Application\chromium.exe",
+]
+
+_MAC_CHROME_PATH = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+_MAC_EDGE_PATH = "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"
+_MAC_BRAVE_PATH = "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
+_MAC_CHROMIUM_PATH = "/Applications/Chromium.app/Contents/MacOS/Chromium"
+
+_LINUX_NAMES: dict[str, list[str]] = {
+    "chrome": ["google-chrome", "google-chrome-stable", "chrome"],
+    "edge": ["microsoft-edge", "microsoft-edge-stable"],
+    "brave": ["brave-browser", "brave"],
+    "chromium": ["chromium", "chromium-browser"],
+}
+
+
+def _check_paths(paths: list[str]) -> str | None:
+    for path in paths:
+        if os.path.isfile(path):
+            return path
+    return None
+
+
+def _find_on_linux(names: list[str]) -> str | None:
+    for name in names:
+        path = shutil.which(name)
+        if path:
+            return path
+    return None
+
+
+def find_chrome() -> str | None:
+    env_path = os.environ.get("CDPWAVE_CHROME_PATH")
+    if env_path and os.path.isfile(env_path):
+        return env_path
+    if sys.platform == "win32":
+        return _check_paths(_WIN_CHROME_PATHS)
+    if sys.platform == "darwin":
+        return _check_paths([_MAC_CHROME_PATH])
+    return _find_on_linux(_LINUX_NAMES["chrome"])
+
+
+def find_edge() -> str | None:
+    env_path = os.environ.get("CDPWAVE_EDGE_PATH")
+    if env_path and os.path.isfile(env_path):
+        return env_path
+    if sys.platform == "win32":
+        return _check_paths(_WIN_EDGE_PATHS)
+    if sys.platform == "darwin":
+        return _check_paths([_MAC_EDGE_PATH])
+    return _find_on_linux(_LINUX_NAMES["edge"])
+
+
+def find_brave() -> str | None:
+    env_path = os.environ.get("CDPWAVE_BRAVE_PATH")
+    if env_path and os.path.isfile(env_path):
+        return env_path
+    if sys.platform == "win32":
+        return _check_paths(_WIN_BRAVE_PATHS)
+    if sys.platform == "darwin":
+        return _check_paths([_MAC_BRAVE_PATH])
+    return _find_on_linux(_LINUX_NAMES["brave"])
+
+
+def find_chromium() -> str | None:
+    env_path = os.environ.get("CDPWAVE_CHROMIUM_PATH")
+    if env_path and os.path.isfile(env_path):
+        return env_path
+    if sys.platform == "win32":
+        return _check_paths(_WIN_CHROMIUM_PATHS)
+    if sys.platform == "darwin":
+        return _check_paths([_MAC_CHROMIUM_PATH])
+    return _find_on_linux(_LINUX_NAMES["chromium"])
+
+
+_FINDER_NAMES: dict[BrowserType, str] = {
+    "chrome": "find_chrome",
+    "edge": "find_edge",
+    "brave": "find_brave",
+    "chromium": "find_chromium",
+}
+
+_SEARCH_ORDER: list[BrowserType] = ["chrome", "edge", "brave", "chromium"]
+
+
+def find_browser(preferred: BrowserType | None = None) -> str:
+    env_override = os.environ.get("CDPWAVE_BROWSER_PATH")
+    if env_override and os.path.isfile(env_override):
+        return env_override
+
+    search_order: list[BrowserType] = []
+    if preferred is not None:
+        search_order.append(preferred)
+    search_order.extend([b for b in _SEARCH_ORDER if b != preferred])
+
+    for browser_type in search_order:
+        finder = globals()[_FINDER_NAMES[browser_type]]
+        path: str | None = finder()
+        if path:
+            return path
+
+    raise BrowserNotFoundError(
+        "No Chromium-based browser found."
+        " Set CDPWAVE_BROWSER_PATH or install Chrome/Edge/Brave/Chromium."
+    )

cdpwave/browser/launcher.py

@@ -0,0 +1,170 @@
+import asyncio
+import contextlib
+import json
+import os
+import shutil
+import socket
+import tempfile
+import urllib.request
+from dataclasses import dataclass
+
+from cdpwave.browser.finder import find_browser
+from cdpwave.exceptions import LaunchError, LaunchTimeoutError
+
+_DEFAULT_FLAGS = [
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--disable-features=Translate",
+]
+
+_CI_ENV_VARS = ["CI", "GITHUB_ACTIONS", "GITLAB_CI", "JENKINS_URL"]
+
+
+def _is_ci() -> bool:
+    return any(os.environ.get(var) for var in _CI_ENV_VARS)
+
+
+def _find_free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        port: int = s.getsockname()[1]
+        return port
+
+
+@dataclass(frozen=True)
+class BrowserInfo:
+    web_socket_debugger_url: str
+    browser_version: str
+    protocol_version: str
+    user_agent: str
+    port: int
+
+
+class BrowserLauncher:
+    def __init__(
+        self,
+        browser_path: str | None = None,
+        port: int = 0,
+        headless: bool = True,
+        user_data_dir: str | None = None,
+        extra_args: list[str] | None = None,
+    ) -> None:
+        self._browser_path = browser_path
+        self._port = port
+        self._headless = headless
+        self._user_data_dir = user_data_dir
+        self._extra_args = extra_args
+        self._process: asyncio.subprocess.Process | None = None
+        self._temp_dir: str | None = None
+        self._info: BrowserInfo | None = None
+
+    def _build_args(self) -> list[str]:
+        if self._browser_path is None:
+            self._browser_path = find_browser()
+
+        port = self._port if self._port != 0 else _find_free_port()
+        self._port = port
+
+        user_data_dir = self._user_data_dir
+        if user_data_dir is None:
+            user_data_dir = self._create_temp_user_dir()
+        self._user_data_dir = user_data_dir
+
+        args = [
+            self._browser_path,
+            f"--remote-debugging-port={port}",
+            f"--user-data-dir={user_data_dir}",
+            *_DEFAULT_FLAGS,
+        ]
+
+        if self._headless:
+            args.append("--headless=new")
+
+        if _is_ci():
+            args.append("--no-sandbox")
+
+        if self._extra_args:
+            args.extend(self._extra_args)
+
+        args.append("about:blank")
+        return args
+
+    def _create_temp_user_dir(self) -> str:
+        self._temp_dir = tempfile.mkdtemp(prefix="cdpwave-")
+        return self._temp_dir
+
+    async def launch(self, timeout: float = 10.0) -> BrowserInfo:
+        if self._process is not None:
+            raise RuntimeError("Browser is already running")
+
+        args = self._build_args()
+
+        self._process = await asyncio.create_subprocess_exec(
+            *args,
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.DEVNULL,
+        )
+
+        self._info = await self._wait_for_endpoint(timeout=timeout)
+        return self._info
+
+    async def _wait_for_endpoint(self, timeout: float = 10.0) -> BrowserInfo:
+        url = f"http://localhost:{self._port}/json/version"
+        delay = 0.1
+        elapsed = 0.0
+
+        while elapsed < timeout:
+            if self._process is not None and self._process.returncode is not None:
+                raise LaunchError(
+                    f"Browser process exited with code {self._process.returncode}"
+                )
+
+            try:
+                data = await asyncio.to_thread(_fetch_version, url)
+                return BrowserInfo(
+                    web_socket_debugger_url=str(data.get("webSocketDebuggerUrl", "")),
+                    browser_version=str(data.get("Browser", "")),
+                    protocol_version=str(data.get("Protocol-Version", "")),
+                    user_agent=str(data.get("User-Agent", "")),
+                    port=self._port,
+                )
+            except Exception:
+                await asyncio.sleep(delay)
+                elapsed += delay
+                delay = min(delay * 1.5, 1.0)
+
+        raise LaunchTimeoutError(
+            f"Browser did not become ready within {timeout}s on port {self._port}"
+        )
+
+    async def close(self) -> None:
+        if self._process is not None:
+            with contextlib.suppress(Exception):
+                if self._process.returncode is None:
+                    self._process.terminate()
+                    try:
+                        await asyncio.wait_for(self._process.wait(), timeout=2.0)
+                    except TimeoutError:
+                        self._process.kill()
+                        await self._process.wait()
+            self._process = None
+
+        if self._temp_dir is not None:
+            shutil.rmtree(self._temp_dir, ignore_errors=True)
+            self._temp_dir = None
+
+        self._info = None
+
+    @property
+    def is_running(self) -> bool:
+        return self._process is not None and self._process.returncode is None
+
+    @property
+    def info(self) -> BrowserInfo | None:
+        return self._info
+
+
+def _fetch_version(url: str) -> dict[str, object]:
+    with urllib.request.urlopen(url, timeout=5) as resp:
+        data = json.loads(resp.read().decode("utf-8"))
+        return data  # type: ignore[no-any-return]