cdpify 0.2.8

A Python client for the Chrome DevTools Protocol (CDP) optimized for DX.

cdpify

Type-safe Python client for the Chrome DevTools Protocol (CDP) with Pydantic validation.

Installation

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:

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:

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

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:

from cdpify import (
    CDPClient,
    PageClient,
    NetworkClient,
    RuntimeClient,
    # ... all other domain clients
)

Type Safety

All commands and events use Pydantic models for validation:

# 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:

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.

Links

• Chrome DevTools Protocol
• Protocol Repository