cdpify

🚀 An async, typed Python client for the Chrome DevTools Protocol.

cdpify turns the Chrome DevTools Protocol (CDP) into a Pythonic, IDE-friendly API. Commands, results, events, and protocol types are generated from the official CDP specifications, so you get autocomplete and typed responses without working with raw JSON messages.

Contents

• Why cdpify?
• Installation
• Quick start
• Supported domains
• Listening for events
• Working with target sessions
• Configuration
• Development
• Resources

Why cdpify?

• Typed by default — generated models for commands, results, events, and shared protocol types
• Complete domain coverage — access all 58 generated CDP domains through properties such as client.page, client.network, and client.runtime
• Async throughout — transport-neutral core with an optional WebSocket implementation
• Typed event streams — consume CDP events with async iterators
• Multi-target support — use immutable, concurrency-safe session views
• Low-level protocol access — execute any CDP method through execute() when needed

Installation

pip install "cdpify[websocket]"

Requires Python 3.12 or newer. The WebSocket extra provides the recommended default transport used by Client(url). Install cdpify without an extra when supplying your own Transport implementation.

Install the generator dependencies only when regenerating protocol modules:

pip install "cdpify[generator]"

Quick start

Start Chrome or Chromium with remote debugging enabled, then obtain a page's webSocketDebuggerUrl from http://localhost:9222/json.

import asyncio
import json
from urllib.request import urlopen

from cdpify import Client


def get_websocket_url() -> str:
    with urlopen("http://localhost:9222/json", timeout=5) as response:
        return json.load(response)[0]["webSocketDebuggerUrl"]


async def main() -> None:
    ws_url = get_websocket_url()

    async with Client(ws_url) as client:
        await client.page.navigate(url="https://example.com")

        result = await client.runtime.evaluate(
            expression="document.title",
            return_by_value=True,
        )
        print(result.result.value)


asyncio.run(main())

Domains are available as lazy properties on Client. Parameters use Python's snake_case; cdpify handles conversion to and from CDP's wire format.

Supported domains

The generated client currently includes all 58 domains from the bundled CDP specifications. Each domain is available as a lazy property on Client and CDPSession:

Listening for events

Events are exposed as typed async streams:

from cdpify.domains.network.events import NetworkEvent, RequestWillBeSentEvent


await client.network.enable()

async for event in client.listen(
    event_name=NetworkEvent.REQUEST_WILL_BE_SENT,
    event_type=RequestWillBeSentEvent,
):
    print(event.request.method, event.request.url)

client.listen() accepts an optional timeout in seconds and yields only events from the root connection. A session view applies the same rule to its bound target:

tab = client.session("session-id")

async for event in tab.listen(
    event_name=NetworkEvent.REQUEST_WILL_BE_SENT,
    event_type=RequestWillBeSentEvent,
):
    # This stream contains events from this session only.
    print(event.request.url)

To observe the root connection and all attached sessions together, use listen_all(). Routing metadata is returned separately from the generated CDP event model:

async for received in client.listen_all(
    event_name=NetworkEvent.REQUEST_WILL_BE_SENT,
    event_type=RequestWillBeSentEvent,
):
    print(received.session_id, received.value.request.url)

received.session_id is None for a root event. Generated event dataclasses contain only fields defined by the CDP specification.

Working with target sessions

Attach to a target in flat mode and create an immutable session view with client.session(). Every generated command on that view is routed to the bound session:

from cdpify import Client


async with Client(browser_ws_url) as root_client:
    attached = await root_client.target.attach_to_target(
        target_id="target-id",
        flatten=True,
    )
    tab = root_client.session(attached.session_id)

    await tab.page.enable()
    await tab.runtime.evaluate(expression="console.log('Hello from CDP')")

There is no mutable "active session". Create one view per attached target and use them safely from concurrent tasks:

import asyncio


tab_a = root_client.session(session_a)
tab_b = root_client.session(session_b)

await asyncio.gather(
    tab_a.runtime.evaluate(expression="document.title"),
    tab_b.runtime.evaluate(expression="document.title"),
)

Session routing is transport metadata, not a generated command parameter. Generated methods therefore never accept an additional routing session_id. A real sessionId declared by the CDP specification remains a normal typed parameter. For low-level access, root_client.execute() optionally accepts a session ID, while tab.execute() is always bound and cannot be overridden:

await root_client.execute("Page.enable", session_id=session_a)
await tab.execute("Runtime.evaluate", {"expression": "1 + 1"})

Configuration

client = Client(
    url="ws://localhost:9222/devtools/browser/...",
    additional_headers={"Authorization": "Bearer token"},
    max_frame_size=100 * 1024 * 1024,
    default_timeout=30.0,
)

For another transport protocol, implement the exported Transport protocol and inject it directly:

from cdpify import Client

client = Client(transport=my_transport)

For methods not covered by the generated API, use the low-level escape hatch:

result = await client.execute(
    "Runtime.evaluate",
    {"expression": "1 + 1", "returnByValue": True},
)

Development

Install the project and its development dependencies with uv:

uv sync --dev
uv run pytest
uv run ruff check . --exclude cdpify/domains

To download the latest protocol definitions and regenerate all domain clients:

uv run python -m cdpify.generator

Generate only selected domains by repeating --domain:

uv run python -m cdpify.generator --domain Page --domain Runtime

Use --spec-dir and --output-dir to override where downloaded specifications and generated modules are written.

The generated output lives in cdpify/domains/ and should not be edited by hand. The repository also refreshes the upstream specification automatically once a week and opens a pull request when generated code changes.

Resources

• Chrome DevTools Protocol documentation
• Chrome DevTools Protocol repository
• Examples

The code-generation approach was inspired by cdp-use.