cdpify 0.1.0__tar.gz

cdpify-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: cdpify
+Version: 0.1.0
+Summary: Add your description here
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pre-commit>=4.5.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: websockets>=15.0.1
+
+# Pydantic CDP
+
+Type-safe Python client for the Chrome DevTools Protocol (CDP) with Pydantic validation.
+
+## Installation
+
+```bash
+pip install cdpify
+```
+
+## What it does
+
+This library provides Python bindings for the Chrome DevTools Protocol with full type safety through Pydantic models. All CDP domains, commands, events, and types are automatically generated from the official Chrome DevTools Protocol specifications.
+
+## Usage
+
+### Basic Connection
+
+```python
+import asyncio
+from cdpify import CDPClient
+
+async def main():
+    async with CDPClient("ws://localhost:9222/devtools/browser/...") as client:
+        # Send CDP commands
+        result = await client.send_raw(
+            method="Target.getTargets",
+            params=None
+        )
+        print(f"Targets: {result}")
+
+asyncio.run(main())
+```
+
+### Using Domain Clients
+
+Domain-specific clients provide typed methods for all CDP commands:
+
+```python
+from cdpify import CDPClient
+from cdpify.domains import PageClient, RuntimeClient
+
+async def main():
+    async with CDPClient("ws://localhost:9222/devtools/page/...") as client:
+        # Initialize domain clients
+        page = PageClient(client)
+        runtime = RuntimeClient(client)
+
+        # Navigate to a page
+        await page.navigate(url="https://example.com")
+
+        # Evaluate JavaScript
+        result = await runtime.evaluate(
+            expression="document.title",
+            return_by_value=True
+        )
+        print(f"Page title: {result.result.value}")
+
+asyncio.run(main())
+```
+
+### Event Handling
+
+Register handlers for CDP events:
+
+```python
+from cdpify import CDPClient
+from cdpify.domains import PageClient
+
+async def main():
+    client = CDPClient("ws://localhost:9222/devtools/page/...")
+    await client.connect()
+
+    # Register event handler
+    @client.on("Page.loadEventFired")
+    async def on_load(params, session_id):
+        print(f"Page loaded at timestamp: {params['timestamp']}")
+
+    # Wildcard handler for all events
+    @client.on()
+    async def on_any_event(params, session_id):
+        print(f"Event received: {params}")
+
+    page = PageClient(client)
+    await page.enable()
+    await page.navigate(url="https://example.com")
+
+    await asyncio.sleep(5)
+    await client.disconnect()
+
+asyncio.run(main())
+```
+
+### Configuration
+
+```python
+client = CDPClient(
+    url="ws://localhost:9222/devtools/browser/...",
+    additional_headers={"Authorization": "Bearer token"},
+    max_frame_size=100 * 1024 * 1024,  # 100MB
+    default_timeout=30.0  # seconds
+)
+```
+
+## Available Domain Clients
+
+All CDP domains are available as typed clients:
+
+- `PageClient` - Page lifecycle, navigation, screenshots
+- `RuntimeClient` - JavaScript execution, console, objects
+- `NetworkClient` - Network monitoring, request interception
+- `DOMClient` - DOM tree access and manipulation
+- `DebuggerClient` - JavaScript debugging
+- `EmulationClient` - Device emulation, geolocation
+- `PerformanceClient` - Performance metrics
+- `SecurityClient` - Security state, certificates
+- And 40+ more domains...
+
+Import them from the root package:
+
+```python
+from cdpify import (
+    CDPClient,
+    PageClient,
+    NetworkClient,
+    RuntimeClient,
+    # ... all other domain clients
+)
+```
+
+## Type Safety
+
+All commands and events use Pydantic models for validation:
+
+```python
+# Parameters are validated
+await page.navigate(
+    url="https://example.com",
+    referrer="https://google.com",  # Optional parameter
+    transition_type="link"  # Validated against allowed values
+)
+
+# Return values are typed
+result = await runtime.evaluate(expression="1 + 1")
+print(result.result.value)  # Pydantic model with full IDE support
+```
+
+## Code Generation
+
+The CDP bindings are generated from the official Chrome DevTools Protocol specifications. To regenerate:
+
+```bash
+uv run python -m pydantic_cpd.generator
+```
+
+This downloads the latest protocol definitions and generates:
+- `pydantic_cpd/domains/*/types.py` - Type definitions
+- `pydantic_cpd/domains/*/commands.py` - Command parameters and results
+- `pydantic_cpd/domains/*/events.py` - Event definitions
+- `pydantic_cpd/domains/*/library.py` - Domain client classes
+
+## Project Structure
+
+```
+pydantic_cpd/
+├── client.py           # Core CDP WebSocket client
+├── events.py           # Event dispatcher
+├── exceptions.py       # CDP exceptions
+├── domains/           # Generated CDP bindings
+│   ├── page/
+│   ├── runtime/
+│   ├── network/
+│   └── ... (42 domains)
+└── generator/         # Code generation tools
+```
+
+## Requirements
+
+- Python 3.14+
+- pydantic >= 2.12
+- websockets >= 15.0
+- httpx >= 0.28
+
+
+## Inspiration
+
+The idea for automatic code generation and the overall approach is inspired by [cdp-use](https://github.com/browser-use/cdp-use). This project adapts that concept for Python, with a slightly different API design and type system using Pydantic models.
+
+## Links
+
+- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)
+- [Protocol Repository](https://github.com/ChromeDevTools/devtools-protocol)

cdpify-0.1.0/README.md

@@ -0,0 +1,192 @@
+# Pydantic CDP
+
+Type-safe Python client for the Chrome DevTools Protocol (CDP) with Pydantic validation.
+
+## Installation
+
+```bash
+pip install cdpify
+```
+
+## What it does
+
+This library provides Python bindings for the Chrome DevTools Protocol with full type safety through Pydantic models. All CDP domains, commands, events, and types are automatically generated from the official Chrome DevTools Protocol specifications.
+
+## Usage
+
+### Basic Connection
+
+```python
+import asyncio
+from cdpify import CDPClient
+
+async def main():
+    async with CDPClient("ws://localhost:9222/devtools/browser/...") as client:
+        # Send CDP commands
+        result = await client.send_raw(
+            method="Target.getTargets",
+            params=None
+        )
+        print(f"Targets: {result}")
+
+asyncio.run(main())
+```
+
+### Using Domain Clients
+
+Domain-specific clients provide typed methods for all CDP commands:
+
+```python
+from cdpify import CDPClient
+from cdpify.domains import PageClient, RuntimeClient
+
+async def main():
+    async with CDPClient("ws://localhost:9222/devtools/page/...") as client:
+        # Initialize domain clients
+        page = PageClient(client)
+        runtime = RuntimeClient(client)
+
+        # Navigate to a page
+        await page.navigate(url="https://example.com")
+
+        # Evaluate JavaScript
+        result = await runtime.evaluate(
+            expression="document.title",
+            return_by_value=True
+        )
+        print(f"Page title: {result.result.value}")
+
+asyncio.run(main())
+```
+
+### Event Handling
+
+Register handlers for CDP events:
+
+```python
+from cdpify import CDPClient
+from cdpify.domains import PageClient
+
+async def main():
+    client = CDPClient("ws://localhost:9222/devtools/page/...")
+    await client.connect()
+
+    # Register event handler
+    @client.on("Page.loadEventFired")
+    async def on_load(params, session_id):
+        print(f"Page loaded at timestamp: {params['timestamp']}")
+
+    # Wildcard handler for all events
+    @client.on()
+    async def on_any_event(params, session_id):
+        print(f"Event received: {params}")
+
+    page = PageClient(client)
+    await page.enable()
+    await page.navigate(url="https://example.com")
+
+    await asyncio.sleep(5)
+    await client.disconnect()
+
+asyncio.run(main())
+```
+
+### Configuration
+
+```python
+client = CDPClient(
+    url="ws://localhost:9222/devtools/browser/...",
+    additional_headers={"Authorization": "Bearer token"},
+    max_frame_size=100 * 1024 * 1024,  # 100MB
+    default_timeout=30.0  # seconds
+)
+```
+
+## Available Domain Clients
+
+All CDP domains are available as typed clients:
+
+- `PageClient` - Page lifecycle, navigation, screenshots
+- `RuntimeClient` - JavaScript execution, console, objects
+- `NetworkClient` - Network monitoring, request interception
+- `DOMClient` - DOM tree access and manipulation
+- `DebuggerClient` - JavaScript debugging
+- `EmulationClient` - Device emulation, geolocation
+- `PerformanceClient` - Performance metrics
+- `SecurityClient` - Security state, certificates
+- And 40+ more domains...
+
+Import them from the root package:
+
+```python
+from cdpify import (
+    CDPClient,
+    PageClient,
+    NetworkClient,
+    RuntimeClient,
+    # ... all other domain clients
+)
+```
+
+## Type Safety
+
+All commands and events use Pydantic models for validation:
+
+```python
+# Parameters are validated
+await page.navigate(
+    url="https://example.com",
+    referrer="https://google.com",  # Optional parameter
+    transition_type="link"  # Validated against allowed values
+)
+
+# Return values are typed
+result = await runtime.evaluate(expression="1 + 1")
+print(result.result.value)  # Pydantic model with full IDE support
+```
+
+## Code Generation
+
+The CDP bindings are generated from the official Chrome DevTools Protocol specifications. To regenerate:
+
+```bash
+uv run python -m pydantic_cpd.generator
+```
+
+This downloads the latest protocol definitions and generates:
+- `pydantic_cpd/domains/*/types.py` - Type definitions
+- `pydantic_cpd/domains/*/commands.py` - Command parameters and results
+- `pydantic_cpd/domains/*/events.py` - Event definitions
+- `pydantic_cpd/domains/*/library.py` - Domain client classes
+
+## Project Structure
+
+```
+pydantic_cpd/
+├── client.py           # Core CDP WebSocket client
+├── events.py           # Event dispatcher
+├── exceptions.py       # CDP exceptions
+├── domains/           # Generated CDP bindings
+│   ├── page/
+│   ├── runtime/
+│   ├── network/
+│   └── ... (42 domains)
+└── generator/         # Code generation tools
+```
+
+## Requirements
+
+- Python 3.14+
+- pydantic >= 2.12
+- websockets >= 15.0
+- httpx >= 0.28
+
+
+## Inspiration
+
+The idea for automatic code generation and the overall approach is inspired by [cdp-use](https://github.com/browser-use/cdp-use). This project adapts that concept for Python, with a slightly different API design and type system using Pydantic models.
+
+## Links
+
+- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)
+- [Protocol Repository](https://github.com/ChromeDevTools/devtools-protocol)

cdpify-0.1.0/cdpify/__init__.py

@@ -0,0 +1,17 @@
+from .client import CDPClient
+from .exceptions import (
+    CDPCommandException,
+    CDPConnectionException,
+    CDPException,
+    CDPTimeoutException,
+)
+
+__all__ = [
+    # CDPClient
+    "CDPClient",
+    # Exceptions
+    "CDPException",
+    "CDPConnectionException",
+    "CDPCommandException",
+    "CDPTimeoutException",
+]

cdpify-0.1.0/cdpify/client.py

@@ -0,0 +1,243 @@
+import asyncio
+import json
+import logging
+from typing import Any
+
+import websockets
+from websockets.asyncio.client import ClientConnection, connect
+
+from cdpify.events import EventDispatcher, EventHandler
+from cdpify.exceptions import (
+    CDPCommandException,
+    CDPConnectionException,
+    CDPTimeoutException,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class CDPClient:
+    def __init__(
+        self,
+        url: str,
+        *,
+        additional_headers: dict[str, str] | None = None,
+        max_frame_size: int = 100 * 1024 * 1024,
+        default_timeout: float = 30.0,
+    ) -> None:
+        self.url: str = url
+        self.additional_headers: dict[str, str] | None = additional_headers
+        self.max_frame_size: int = max_frame_size
+        self.default_timeout: float = default_timeout
+
+        self._ws: ClientConnection | None = None
+        self._next_message_id: int = 0
+        self._pending_requests: dict[int, asyncio.Future[dict[str, Any]]] = {}
+        self._message_loop_task: asyncio.Task[None] | None = None
+        self._events: EventDispatcher = EventDispatcher()
+        self._is_shutting_down: bool = False
+
+    async def __aenter__(self) -> CDPClient:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.disconnect()
+
+    @property
+    def is_connected(self) -> bool:
+        return self._ws is not None
+
+    def on(self, event_name: str | None = None):
+        """
+        Register event handler.
+
+        Usage:
+            @client.on("Page.loadEventFired")
+            async def on_load(params, session_id):
+                print("Page loaded!")
+
+            @client.on()  # Wildcard - all events
+            async def on_any(params, session_id):
+                print(f"Event: {params}")
+        """
+
+        def decorator(func: EventHandler) -> EventHandler:
+            self._events.add_handler(event_name, func)
+            return func
+
+        return decorator
+
+    def add_event_listener(self, event_name: str | None, handler: EventHandler) -> None:
+        self._events.add_handler(event_name, handler)
+
+    def remove_event_listener(
+        self, event_name: str | None, handler: EventHandler
+    ) -> None:
+        self._events.remove_handler(event_name, handler)
+
+    async def connect(self) -> None:
+        if self._ws is not None:
+            raise CDPConnectionException("Already connected")
+
+        logger.info(f"Connecting to {self.url}")
+
+        try:
+            self._ws = await connect(
+                self.url,
+                max_size=self.max_frame_size,
+                additional_headers=self.additional_headers,
+            )
+            self._is_shutting_down = False
+            self._message_loop_task = asyncio.create_task(self._run_message_loop())
+            logger.info("Connected")
+        except Exception as e:
+            raise CDPConnectionException(f"Connection failed: {e}") from e
+
+    async def disconnect(self) -> None:
+        if self._is_shutting_down:
+            return
+
+        self._is_shutting_down = True
+        logger.info("Disconnecting...")
+
+        await self._stop_message_loop()
+        self._cancel_pending_requests()
+        await self._close_websocket()
+
+        logger.info("Disconnected")
+
+    async def send_raw(
+        self,
+        method: str,
+        params: dict[str, Any] | None = None,
+        session_id: str | None = None,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        if not self.is_connected:
+            raise CDPConnectionException("Not connected")
+
+        timeout = timeout or self.default_timeout
+        msg_id = self._next_message_id
+        self._next_message_id += 1
+
+        message = self._build_message(msg_id, method, params, session_id)
+        future = self._create_pending_request(msg_id)
+
+        try:
+            await self._send(msg_id, method, message)
+            return await self._await_response(msg_id, method, future, timeout)
+        finally:
+            self._pending_requests.pop(msg_id, None)
+
+    def _build_message(
+        self,
+        msg_id: int,
+        method: str,
+        params: dict[str, Any] | None,
+        session_id: str | None,
+    ) -> dict[str, Any]:
+        message = {"id": msg_id, "method": method, "params": params or {}}
+        if session_id:
+            message["sessionId"] = session_id
+        return message
+
+    def _create_pending_request(self, msg_id: int) -> asyncio.Future[dict[str, Any]]:
+        future: asyncio.Future[dict[str, Any]] = asyncio.Future()
+        self._pending_requests[msg_id] = future
+        return future
+
+    async def _send(self, msg_id: int, method: str, message: dict[str, Any]) -> None:
+        logger.debug(f"→ #{msg_id}: {method}")
+        await self._ws.send(json.dumps(message))
+
+    async def _await_response(
+        self, msg_id: int, method: str, future: asyncio.Future, timeout: float
+    ) -> dict[str, Any]:
+        try:
+            result = await asyncio.wait_for(future, timeout=timeout)
+            logger.debug(f"← #{msg_id}: OK")
+            return result
+        except asyncio.TimeoutError:
+            raise CDPTimeoutException(f"{method} timed out after {timeout}s") from None
+        except (CDPCommandException, CDPConnectionException):
+            raise
+        except Exception as e:
+            raise CDPConnectionException(f"Command failed: {e}") from e
+
+    async def _run_message_loop(self) -> None:
+        try:
+            async for raw_message in self._ws:
+                if self._is_shutting_down:
+                    break
+                await self._process_message(raw_message)
+        except websockets.exceptions.ConnectionClosed:
+            logger.info("Connection closed")
+        except asyncio.CancelledError:
+            logger.debug("Message loop cancelled")
+            raise
+        except Exception as e:
+            logger.exception(f"Message loop error: {e}")
+        finally:
+            if not self._is_shutting_down:
+                await self.disconnect()
+
+    async def _process_message(self, raw: str) -> None:
+        try:
+            msg = json.loads(raw)
+
+            if "id" in msg:
+                await self._handle_response(msg)
+            elif "method" in msg:
+                await self._handle_event(msg)
+            else:
+                logger.warning(f"Unknown message format: {msg}")
+        except json.JSONDecodeError as e:
+            logger.error(f"Invalid JSON: {e}")
+
+    async def _handle_response(self, msg: dict[str, Any]) -> None:
+        msg_id = msg["id"]
+        future = self._pending_requests.get(msg_id)
+
+        if not future or future.done():
+            return
+
+        if "error" in msg:
+            future.set_exception(CDPCommandException(msg["error"]))
+        else:
+            future.set_result(msg.get("result", {}))
+
+    async def _handle_event(self, msg: dict[str, Any]) -> None:
+        method = msg["method"]
+        params = msg.get("params", {})
+        session_id = msg.get("sessionId")
+
+        logger.debug(f"Event: {method}")
+        handled = await self._events.dispatch(method, params, session_id)
+
+        if not handled:
+            logger.debug(f"Unhandled event: {method}")
+
+    async def _stop_message_loop(self) -> None:
+        if self._message_loop_task and not self._message_loop_task.done():
+            self._message_loop_task.cancel()
+            try:
+                await self._message_loop_task
+            except asyncio.CancelledError:
+                pass
+
+    def _cancel_pending_requests(self) -> None:
+        error = CDPConnectionException("Disconnected")
+        for future in self._pending_requests.values():
+            if not future.done():
+                future.set_exception(error)
+        self._pending_requests.clear()
+
+    async def _close_websocket(self) -> None:
+        if self._ws:
+            try:
+                await self._ws.close()
+            except Exception as e:
+                logger.debug(f"Websocket close error: {e}")
+            finally:
+                self._ws = None