cdpwave 0.1.0__py3-none-any.whl

cdpwave/domains/page.py

@@ -0,0 +1,86 @@
+from typing import Any
+
+from cdpwave.domains.base import BaseDomain
+
+
+class PageDomain(BaseDomain):
+    async def enable(self) -> dict[str, Any]:
+        return await self._call("Page.enable")
+
+    async def disable(self) -> dict[str, Any]:
+        return await self._call("Page.disable")
+
+    async def navigate(
+        self,
+        url: str,
+        referrer: str | None = None,
+        transition_type: str | None = None,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {"url": url}
+        if referrer is not None:
+            params["referrer"] = referrer
+        if transition_type is not None:
+            params["transitionType"] = transition_type
+        return await self._call("Page.navigate", params)
+
+    async def reload(self, ignore_cache: bool = False) -> dict[str, Any]:
+        return await self._call(
+            "Page.reload",
+            {"ignoreCache": ignore_cache},
+        )
+
+    async def stop(self) -> dict[str, Any]:
+        return await self._call("Page.stop")
+
+    async def capture_screenshot(
+        self,
+        format: str = "png",
+        quality: int = 80,
+        clip: dict[str, Any] | None = None,
+        from_surface: bool = True,
+        capture_beyond_viewport: bool = False,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {
+            "format": format,
+            "quality": quality,
+            "fromSurface": from_surface,
+            "captureBeyondViewport": capture_beyond_viewport,
+        }
+        if clip is not None:
+            params["clip"] = clip
+        return await self._call("Page.captureScreenshot", params)
+
+    async def print_to_pdf(
+        self,
+        landscape: bool = False,
+        display_header_footer: bool = False,
+        print_background: bool = False,
+        scale: float = 1.0,
+        paper_width: float = 8.5,
+        paper_height: float = 11.0,
+        margin_top: float = 0.4,
+        margin_bottom: float = 0.4,
+        margin_left: float = 0.4,
+        margin_right: float = 0.4,
+    ) -> dict[str, Any]:
+        return await self._call(
+            "Page.printToPDF",
+            {
+                "landscape": landscape,
+                "displayHeaderFooter": display_header_footer,
+                "printBackground": print_background,
+                "scale": scale,
+                "paperWidth": paper_width,
+                "paperHeight": paper_height,
+                "marginTop": margin_top,
+                "marginBottom": margin_bottom,
+                "marginLeft": margin_left,
+                "marginRight": margin_right,
+            },
+        )
+
+    async def get_layout_metrics(self) -> dict[str, Any]:
+        return await self._call("Page.getLayoutMetrics")
+
+    async def get_navigation_history(self) -> dict[str, Any]:
+        return await self._call("Page.getNavigationHistory")

cdpwave/domains/runtime.py

@@ -0,0 +1,71 @@
+from typing import Any
+
+from cdpwave.domains.base import BaseDomain
+
+
+class RuntimeDomain(BaseDomain):
+    async def enable(self) -> dict[str, Any]:
+        return await self._call("Runtime.enable")
+
+    async def disable(self) -> dict[str, Any]:
+        return await self._call("Runtime.disable")
+
+    async def evaluate(
+        self,
+        expression: str,
+        return_by_value: bool = True,
+        await_promise: bool = False,
+        user_gesture: bool = False,
+    ) -> dict[str, Any]:
+        return await self._call(
+            "Runtime.evaluate",
+            {
+                "expression": expression,
+                "returnByValue": return_by_value,
+                "awaitPromise": await_promise,
+                "userGesture": user_gesture,
+            },
+        )
+
+    async def call_function_on(
+        self,
+        object_id: str,
+        function_declaration: str,
+        args: list[dict[str, Any]] | None = None,
+        return_by_value: bool = True,
+        await_promise: bool = False,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {
+            "objectId": object_id,
+            "functionDeclaration": function_declaration,
+            "returnByValue": return_by_value,
+            "awaitPromise": await_promise,
+        }
+        if args is not None:
+            params["arguments"] = args
+        return await self._call("Runtime.callFunctionOn", params)
+
+    async def release_object(self, object_id: str) -> dict[str, Any]:
+        return await self._call(
+            "Runtime.releaseObject",
+            {"objectId": object_id},
+        )
+
+    async def release_object_group(self, object_group: str) -> dict[str, Any]:
+        return await self._call(
+            "Runtime.releaseObjectGroup",
+            {"objectGroup": object_group},
+        )
+
+    async def get_properties(
+        self,
+        object_id: str,
+        own_properties: bool = True,
+    ) -> dict[str, Any]:
+        return await self._call(
+            "Runtime.getProperties",
+            {
+                "objectId": object_id,
+                "ownProperties": own_properties,
+            },
+        )

cdpwave/domains/target.py

@@ -0,0 +1,40 @@
+from typing import Any
+
+from cdpwave.domains.base import BaseDomain
+
+
+class TargetDomain(BaseDomain):
+    async def create_target(self, url: str) -> dict[str, Any]:
+        return await self._call("Target.createTarget", {"url": url})
+
+    async def attach_to_target(
+        self,
+        target_id: str,
+        flatten: bool = True,
+    ) -> dict[str, Any]:
+        return await self._call(
+            "Target.attachToTarget",
+            {"targetId": target_id, "flatten": flatten},
+        )
+
+    async def detach_from_target(self, session_id: str) -> dict[str, Any]:
+        return await self._call(
+            "Target.detachFromTarget",
+            {"sessionId": session_id},
+        )
+
+    async def close_target(self, target_id: str) -> dict[str, Any]:
+        return await self._call("Target.closeTarget", {"targetId": target_id})
+
+    async def get_targets(self) -> dict[str, Any]:
+        return await self._call("Target.getTargets")
+
+    async def set_auto_attach(
+        self,
+        auto_attach: bool,
+        flatten: bool = True,
+    ) -> dict[str, Any]:
+        return await self._call(
+            "Target.setAutoAttach",
+            {"autoAttach": auto_attach, "flatten": flatten},
+        )

cdpwave/events/dispatcher.py

@@ -0,0 +1,44 @@
+import logging
+from typing import Any
+
+from cdpwave.events.handlers import EventHandler, Subscription
+
+logger = logging.getLogger("cdpwave.events")
+
+
+class EventDispatcher:
+    def __init__(self) -> None:
+        self._handlers: dict[str, list[EventHandler]] = {}
+
+    def on(self, event_name: str, handler: EventHandler) -> Subscription:
+        if event_name not in self._handlers:
+            self._handlers[event_name] = []
+        self._handlers[event_name].append(handler)
+        return Subscription(self, event_name, handler)
+
+    def off(self, event_name: str, handler: EventHandler) -> None:
+        handlers = self._handlers.get(event_name)
+        if handlers is None:
+            return
+        if handler in handlers:
+            handlers.remove(handler)
+            if not handlers:
+                del self._handlers[event_name]
+
+    async def dispatch(self, event_name: str, params: dict[str, Any]) -> None:
+        handlers = list(self._handlers.get(event_name, []))
+        for handler in handlers:
+            try:
+                await handler(params)
+            except Exception:
+                logger.exception(
+                    "Handler error for event %s",
+                    event_name,
+                )
+
+    @property
+    def handler_count(self) -> int:
+        return sum(len(h) for h in self._handlers.values())
+
+    def clear(self) -> None:
+        self._handlers.clear()

cdpwave/events/handlers.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import weakref
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from cdpwave.events.dispatcher import EventDispatcher
+
+EventHandler = Callable[[dict[str, Any]], Awaitable[None]]
+
+
+class Subscription:
+    def __init__(
+        self,
+        dispatcher: EventDispatcher,
+        event_name: str,
+        handler: EventHandler,
+    ) -> None:
+        self._dispatcher_ref: weakref.ReferenceType[EventDispatcher] = (
+            weakref.ref(dispatcher)
+        )
+        self._event_name = event_name
+        self._handler = handler
+
+    def unsubscribe(self) -> None:
+        dispatcher = self._dispatcher_ref()
+        if dispatcher is not None:
+            dispatcher.off(self._event_name, self._handler)
+
+    @property
+    def event_name(self) -> str:
+        return self._event_name
+
+    @property
+    def handler(self) -> EventHandler:
+        return self._handler

cdpwave/exceptions.py

@@ -0,0 +1,40 @@
+class CDPError(Exception):
+    """Base exception for all cdpwave errors."""
+
+
+class ConnectionClosedError(CDPError):
+    """WebSocket connection was closed."""
+
+
+class CommandError(CDPError):
+    """CDP command returned an error response."""
+
+    def __init__(self, code: int, message: str, data: dict[str, object] | None = None) -> None:
+        self.code = code
+        self.message = message
+        self.data = data
+        super().__init__(f"[{code}] {message}")
+
+
+class CommandTimeoutError(CDPError):
+    """CDP command did not respond within timeout."""
+
+
+class BrowserNotFoundError(CDPError):
+    """No Chromium-based browser found on the system."""
+
+
+class SessionClosedError(CDPError):
+    """CDP session was closed by the browser."""
+
+
+class DiscoveryError(CDPError):
+    """HTTP discovery endpoint request failed."""
+
+
+class LaunchTimeoutError(CDPError):
+    """Browser did not start within the specified timeout."""
+
+
+class LaunchError(CDPError):
+    """Browser crashed or failed during startup."""

cdpwave/session/manager.py

@@ -0,0 +1,32 @@
+from cdpwave.transport.connection import Connection
+
+
+class SessionManager:
+    def __init__(self, connection: Connection) -> None:
+        self._connection = connection
+
+    async def create_target(self, url: str = "about:blank") -> str:
+        result = await self._connection.send_command(
+            "Target.createTarget",
+            {"url": url},
+        )
+        return str(result["targetId"])
+
+    async def attach_to_target(self, target_id: str) -> str:
+        result = await self._connection.send_command(
+            "Target.attachToTarget",
+            {"targetId": target_id, "flatten": True},
+        )
+        return str(result["sessionId"])
+
+    async def detach_session(self, session_id: str) -> None:
+        await self._connection.send_command(
+            "Target.detachFromTarget",
+            {"sessionId": session_id},
+        )
+
+    async def close_target(self, target_id: str) -> None:
+        await self._connection.send_command(
+            "Target.closeTarget",
+            {"targetId": target_id},
+        )

cdpwave/transport/connection.py

@@ -0,0 +1,142 @@
+import asyncio
+import contextlib
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+import websockets
+from websockets.asyncio.client import ClientConnection
+
+from cdpwave.exceptions import CommandError, CommandTimeoutError, ConnectionClosedError
+from cdpwave.transport.correlation import Correlator
+from cdpwave.transport.serializer import (
+    deserialize_message,
+    is_error,
+    is_event,
+    is_response,
+    serialize_command,
+)
+
+logger = logging.getLogger("cdpwave.transport")
+
+EventCallback = Callable[
+    [str, dict[str, Any], str | None],
+    Awaitable[None],
+]
+
+
+class Connection:
+    def __init__(
+        self,
+        url: str,
+        event_callback: EventCallback | None = None,
+        default_timeout: float = 30.0,
+    ) -> None:
+        self._url = url
+        self._correlator = Correlator()
+        self._ws: ClientConnection | None = None
+        self._receive_task: asyncio.Task[None] | None = None
+        self._closed = False
+        self._event_callback = event_callback
+        self._default_timeout = default_timeout
+
+    async def connect(self) -> None:
+        self._ws = await websockets.connect(self._url)
+        self._receive_task = asyncio.create_task(self._receive_loop())
+        logger.info("Connected to %s", self._url)
+
+    async def send_command(
+        self,
+        method: str,
+        params: dict[str, Any] | None = None,
+        session_id: str | None = None,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        if self._ws is None or self._closed:
+            raise ConnectionClosedError("Connection is closed")
+
+        effective_timeout = self._default_timeout if timeout is None else timeout
+
+        cmd_id = self._correlator.next_id()
+        future = self._correlator.register(cmd_id)
+
+        message = serialize_command(cmd_id, method, params, session_id)
+        await self._ws.send(message)
+        logger.debug("→ [%d] %s", cmd_id, method)
+
+        if effective_timeout <= 0:
+            return await future
+
+        try:
+            return await asyncio.wait_for(future, timeout=effective_timeout)
+        except TimeoutError:
+            self._correlator.reject(
+                cmd_id,
+                CommandError(-1, f"Command timeout: {method}"),
+            )
+            raise CommandTimeoutError(f"Command timeout: {method}") from None
+
+    async def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+
+        if self._receive_task is not None:
+            self._receive_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._receive_task
+
+        if self._ws is not None:
+            with contextlib.suppress(Exception):
+                await self._ws.close()
+
+        self._correlator.reject_all(ConnectionClosedError("Connection closed"))
+        logger.info("Connection closed")
+
+    @property
+    def url(self) -> str:
+        return self._url
+
+    @property
+    def is_closed(self) -> bool:
+        return self._closed
+
+    async def _receive_loop(self) -> None:
+        assert self._ws is not None
+        try:
+            async for raw in self._ws:
+                data = deserialize_message(str(raw))
+
+                if is_response(data):
+                    cmd_id = data["id"]
+                    if is_error(data):
+                        error = data.get("error", {})
+                        self._correlator.reject(
+                            cmd_id,
+                            CommandError(
+                                code=int(error.get("code", -1)),
+                                message=str(error.get("message", "Unknown error")),
+                                data=error.get("data"),
+                            ),
+                        )
+                        logger.debug("← [%d] error: %s", cmd_id, error.get("message"))
+                    else:
+                        result = data.get("result", {})
+                        self._correlator.resolve(cmd_id, result)
+                        logger.debug("← [%d] success", cmd_id)
+                elif is_event(data):
+                    method = data.get("method", "unknown")
+                    params = data.get("params", {})
+                    session = data.get("sessionId")
+                    if self._event_callback is not None:
+                        await self._event_callback(method, params, session)
+                    else:
+                        logger.debug("← event: %s (session=%s)", method, session)
+        except websockets.ConnectionClosedOK:
+            logger.info("WebSocket closed normally")
+        except websockets.ConnectionClosed:
+            logger.info("WebSocket closed by remote")
+        finally:
+            if not self._closed:
+                self._closed = True
+            self._correlator.reject_all(ConnectionClosedError("WebSocket closed"))

cdpwave/transport/correlation.py

@@ -0,0 +1,37 @@
+import asyncio
+from typing import Any
+
+
+class Correlator:
+    def __init__(self) -> None:
+        self._next_id: int = 0
+        self._pending: dict[int, asyncio.Future[dict[str, Any]]] = {}
+
+    def next_id(self) -> int:
+        self._next_id += 1
+        return self._next_id
+
+    def register(self, cmd_id: int) -> asyncio.Future[dict[str, Any]]:
+        fut: asyncio.Future[dict[str, Any]] = asyncio.get_running_loop().create_future()
+        self._pending[cmd_id] = fut
+        return fut
+
+    def resolve(self, cmd_id: int, result: dict[str, Any]) -> None:
+        fut = self._pending.pop(cmd_id, None)
+        if fut is not None and not fut.done():
+            fut.set_result(result)
+
+    def reject(self, cmd_id: int, error: Exception) -> None:
+        fut = self._pending.pop(cmd_id, None)
+        if fut is not None and not fut.done():
+            fut.set_exception(error)
+
+    def reject_all(self, error: Exception) -> None:
+        for fut in self._pending.values():
+            if not fut.done():
+                fut.set_exception(error)
+        self._pending.clear()
+
+    @property
+    def pending_count(self) -> int:
+        return len(self._pending)

cdpwave/transport/serializer.py

@@ -0,0 +1,33 @@
+import json
+from typing import Any
+
+
+def serialize_command(
+    cmd_id: int,
+    method: str,
+    params: dict[str, Any] | None = None,
+    session_id: str | None = None,
+) -> str:
+    message: dict[str, Any] = {"id": cmd_id, "method": method}
+    if params is not None:
+        message["params"] = params
+    if session_id is not None:
+        message["sessionId"] = session_id
+    return json.dumps(message)
+
+
+def deserialize_message(raw: str) -> dict[str, Any]:
+    result: dict[str, Any] = json.loads(raw)
+    return result
+
+
+def is_response(msg: dict[str, Any]) -> bool:
+    return "id" in msg
+
+
+def is_event(msg: dict[str, Any]) -> bool:
+    return "method" in msg and "id" not in msg
+
+
+def is_error(msg: dict[str, Any]) -> bool:
+    return "error" in msg

cdpwave/types.py

@@ -0,0 +1,8 @@
+from collections.abc import Awaitable, Callable
+from typing import Any, Literal
+
+CommandSender = Callable[[str, dict[str, Any] | None], Awaitable[dict[str, Any]]]
+
+EventHandler = Callable[[dict[str, Any]], Awaitable[None]]
+
+BrowserType = Literal["chrome", "edge", "brave", "chromium"]

cdpwave-0.1.0.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: cdpwave
+Version: 0.1.0
+Summary: Chrome DevTools Protocol for Python — direct CDP over WebSocket, no Selenium, no Playwright
+Project-URL: Homepage, https://github.com/MathiasPaulenko/cdpwave
+Project-URL: Repository, https://github.com/MathiasPaulenko/cdpwave
+Project-URL: Issues, https://github.com/MathiasPaulenko/cdpwave/issues
+Author-email: Mathias Paulenko <mathias.paulenko@outlook.com>
+License: MIT
+License-File: LICENSE
+Keywords: async,automation,browser,cdp,chrome,chromium,devtools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.5
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# cdpwave
+
+[![CI](https://github.com/MathiasPaulenko/cdpwave/actions/workflows/ci.yml/badge.svg)](https://github.com/MathiasPaulenko/cdpwave/actions/workflows/ci.yml)
+[![Tests](https://github.com/MathiasPaulenko/cdpwave/actions/workflows/test.yml/badge.svg)](https://github.com/MathiasPaulenko/cdpwave/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/cdpwave.svg)](https://pypi.org/project/cdpwave/)
+[![Python](https://img.shields.io/pypi/pyversions/cdpwave.svg)](https://pypi.org/project/cdpwave/)
+[![License: MIT](https://img.shields.io/badge-License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Chrome DevTools Protocol for Python — direct, typed, async.
+
+cdpwave talks to Chrome over a raw WebSocket. No Node.js, no ChromeDriver, no browser downloads. Just pure Python with full type hints and async-first design.
+
+## Why cdpwave?
+
+- **Direct WebSocket** — single connection to Chrome's DevTools Protocol, no intermediate layers
+- **Fully typed** — `mypy --strict` across the entire codebase, IDE autocomplete everywhere
+- **Async-first** — built on `asyncio`, no threading, no blocking calls
+- **Browser detection** — finds Chrome, Edge, Brave, or Chromium already on your system
+- **Flatten sessions** — one WebSocket for all tabs via `Target.attachToTarget` + `sessionId`
+- **Escape hatch** — `session.send("Any.CDPMethod", params)` for uncovered domains
+- **HTTP discovery** — typed access to `/json/version` and `/json/list` endpoints
+- **MIT licensed** — permissive, compatible with any use
+
+## Install
+
+```bash
+pip install cdpwave
+```
+
+## Quick start
+
+```python
+import asyncio
+from cdpwave import CDPClient
+
+async def main() -> None:
+    async with await CDPClient.launch(headless=True) as client:
+        page = await client.new_page("https://example.com")
+        result = await page.runtime.evaluate("document.title", return_by_value=True)
+        print(result["result"]["value"])  # "Example Domain"
+        await page.close()
+
+asyncio.run(main())
+```
+
+## Documentation
+
+Full documentation at [mathiaspaulenko.github.io/cdpwave](https://mathiaspaulenko.github.io/cdpwave/).
+
+- [Quickstart](https://mathiaspaulenko.github.io/cdpwave/quickstart/) — 10-minute tutorial
+- [Guide](https://mathiaspaulenko.github.io/cdpwave/guide/installation/) — in-depth feature coverage
+- [Cookbook](https://mathiaspaulenko.github.io/cdpwave/cookbook/connect-existing/) — common recipes
+- [API Reference](https://mathiaspaulenko.github.io/cdpwave/api/client/) — auto-generated docs
+- [Migration](https://mathiaspaulenko.github.io/cdpwave/migration/pyppeteer/) — from pyppeteer or pychrome
+
+## License
+
+MIT