cdpify 0.2.5
A Python client for the Chrome DevTools Protocol (CDP) optimized for DX.
Requires Python: >=3.13

# cdpify

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

### 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

Listen to typed CDP events using async iterators:

```python
from cdpify import CDPClient
from cdpify.domains import PageClient
from cdpify.domains.page.events import ScreencastFrameEvent

async def main():
    async with CDPClient("ws://localhost:9222/devtools/page/...") as client:
        page = PageClient(client)
        await page.enable()

        # Start screencast
        await page.start_screencast(format="jpeg", quality=80)

        # Listen to events with full type safety
        async for frame in client.listen("Page.screencastFrame", ScreencastFrameEvent):
            print(f"Frame received: {frame.data}")
            await page.screencast_frame_ack(
                screencast_frame_ack_session_id=frame.session_id
            )

asyncio.run(main())
```

Events are automatically deserialized into typed Pydantic models with full IDE support.

### 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 cdpify.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/*/client.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 concept of automatic code generation from the CDP specification is inspired by [cdp-use](https://github.com/browser-use/cdp-use).

## Links

- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)
- [Protocol Repository](https://github.com/ChromeDevTools/devtools-protocol)