pip install cdpifyThis 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.
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())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.
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
)All CDP domains are available as typed clients:
PageClient- Page lifecycle, navigation, screenshotsRuntimeClient- JavaScript execution, console, objectsNetworkClient- Network monitoring, request interceptionDOMClient- DOM tree access and manipulationDebuggerClient- JavaScript debuggingEmulationClient- Device emulation, geolocationPerformanceClient- Performance metricsSecurityClient- Security state, certificates- And 40+ more domains...
Import them from the root package:
from cdpify import (
CDPClient,
PageClient,
NetworkClient,
RuntimeClient,
# ... all other domain clients
)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 supportThe CDP bindings are generated from the official Chrome DevTools Protocol specifications. To regenerate:
uv run python -m cdpify.generatorThis downloads the latest protocol definitions and generates:
pydantic_cpd/domains/*/types.py- Type definitionspydantic_cpd/domains/*/commands.py- Command parameters and resultspydantic_cpd/domains/*/events.py- Event definitionspydantic_cpd/domains/*/client.py- Domain client classes
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
- Python 3.14+
- pydantic >= 2.12
- websockets >= 15.0
- httpx >= 0.28
The concept of automatic code generation from the CDP specification is inspired by cdp-use.