CDP Use
A type-safe Python client generator for the Chrome DevTools Protocol (CDP). This library automatically generates Python bindings with full TypeScript-like type safety from the official CDP protocol specifications.
🚀 Features
- 🔒 Type Safety: Full type hints with
TypedDictclasses for all CDP commands, parameters, and return types - 🎯 Event Registration: Typesafe event handlers with full IDE support
- 🏗️ Auto-Generated: Code generated directly from official Chrome DevTools Protocol specifications
- 🎯 IntelliSense Support: Perfect IDE autocompletion and type checking
- 📦 Domain Separation: Clean organization with separate modules for each CDP domain
- 🔄 Always Up-to-Date: Easy regeneration from latest protocol specs
🛠️ Installation & Setup
- Clone and install dependencies:
git clone https://github.com/browser-use/cdp-use
cd cdp-use
uv sync # or pip install -r requirements.txt
- Generate the CDP client library:
python -m cdp_use.generator
This automatically downloads the latest protocol specifications and generates all type-safe bindings.
📖 Usage Examples
Basic Usage
import asyncio
from cdp_use.client import CDPClient
async def main():
# Connect to Chrome DevTools
async with CDPClient("ws://localhost:9222/devtools/browser/...") as cdp:
# Get all browser targets with full type safety
targets = await cdp.send.Target.getTargets()
print(f"Found {len(targets['targetInfos'])} targets")
# Navigate to a page
await cdp.send.Page.navigate({"url": "https://example.com"})
asyncio.run(main())
Type Safety in Action
# ✅ Fully typed parameters
await cdp.send.Runtime.evaluate(params={
"expression": "document.title",
"returnByValue": True
})
# ✅ Return types are fully typed
result = await cdp.send.DOM.getDocument(params={"depth": 1})
node_id: int = result["root"]["nodeId"] # Full IntelliSense support
# ❌ Type errors caught at development time
await cdp.send.DOM.getDocument(params={"invalid": "param"}) # Type error!
🎧 Event Registration
The library provides typesafe event registration with full IDE support:
Basic Event Registration
import asyncio
from cdp_use.client import CDPClient
from cdp_use.cdp.page.events import FrameAttachedEvent, DomContentEventFiredEvent
from cdp_use.cdp.runtime.events import ConsoleAPICalledEvent
from typing import Optional
def on_frame_attached(event: FrameAttachedEvent, session_id: Optional[str]) -> None:
print(f"Frame {event['frameId']} attached to {event['parentFrameId']}")
def on_dom_content_loaded(event: DomContentEventFiredEvent, session_id: Optional[str]) -> None:
print(f"DOM content loaded at: {event['timestamp']}")
def on_console_message(event: ConsoleAPICalledEvent, session_id: Optional[str]) -> None:
print(f"Console: {event['type']}")
async def main():
async with CDPClient("ws://localhost:9222/devtools/page/...") as client:
# Register event handlers with camelCase method names (matching CDP)
client.register.Page.frameAttached(on_frame_attached)
client.register.Page.domContentEventFired(on_dom_content_loaded)
client.register.Runtime.consoleAPICalled(on_console_message)
# Enable domains to start receiving events
await client.send.Page.enable()
await client.send.Runtime.enable()
# Navigate and receive events
await client.send.Page.navigate({"url": "https://example.com"})
await asyncio.sleep(5) # Keep listening for events
Event Registration Features
✅ Type Safety: Event handlers are validated at compile time
✅ IDE Support: Full autocomplete for domains and event methods
✅ Parameter Validation: Callback signatures are type-checked
✅ Event Type Definitions: Each event has its own TypedDict interface
Registration Syntax
client.register.Domain.eventName(callback_function)
Where:
Domainis any CDP domain (Page, Runtime, Network, etc.)eventNameis the camelCase CDP event name (matching CDP specs)callback_functionmust accept(event_data, session_id)parameters
Available Event Domains
- Page:
client.register.Page.*- Page lifecycle, navigation, frames - Runtime:
client.register.Runtime.*- JavaScript execution, console, exceptions - Network:
client.register.Network.*- HTTP requests, responses, WebSocket - DOM:
client.register.DOM.*- DOM tree changes, attributes - CSS:
client.register.CSS.*- Stylesheet changes, media queries - Debugger:
client.register.Debugger.*- Breakpoints, script parsing - Performance:
client.register.Performance.*- Performance metrics - Security:
client.register.Security.*- Security state changes - And many more...
Type Safety Examples
✅ Correct Usage:
def handle_console(event: ConsoleAPICalledEvent, session_id: Optional[str]) -> None:
print(f"Console: {event['type']}")
client.register.Runtime.consoleAPICalled(handle_console)
❌ Type Error - Wrong signature:
def bad_handler(event): # Missing session_id parameter
pass
client.register.Runtime.consoleAPICalled(bad_handler) # Type error!
📋 What Gets Generated
cdp_use/cdp/
├── library.py # Main CDPLibrary class
├── registry.py # Event registry system
├── registration_library.py # Event registration interface
├── dom/ # DOM domain
│ ├── types.py # DOM-specific types
│ ├── commands.py # Command parameter/return types
│ ├── events.py # Event types
│ ├── library.py # DOMClient class
│ └── registration.py # DOM event registration
├── page/ # Page domain
│ └── ...
└── ... (50+ domains total)
🏛️ Architecture
Main Components
class CDPClient:
def __init__(self, url: str):
self.send: CDPLibrary # Send commands
self.register: CDPRegistrationLibrary # Register events
# Domain-specific clients
class CDPLibrary:
def __init__(self, client: CDPClient):
self.DOM = DOMClient(client) # DOM operations
self.Network = NetworkClient(client) # Network monitoring
self.Runtime = RuntimeClient(client) # JavaScript execution
# ... 50+ more domains
# Event registration
class CDPRegistrationLibrary:
def __init__(self, registry: EventRegistry):
self.Page = PageRegistration(registry)
self.Runtime = RuntimeRegistration(registry)
# ... all domains with events
🔧 Development
Regenerating Types
# Using task (recommended)
task generate
# Or directly with uv
uv run python -m cdp_use.generator
# Or with python
python -m cdp_use.generator
This will:
- Download the latest protocol files from Chrome DevTools repository
- Generate all Python type definitions and event registrations
- Create domain-specific client classes
- Format the code
Version Pinning
By default, the generator downloads the latest CDP specification from the master branch. To pin a specific version, edit cdp_use/generator/constants.py:
# Pin to a specific commit
CDP_VERSION = "4b0c3f2e8c5d6a7b9e1f2a3c4d5e6f7a8b9c0d1e"
# Or use master for latest
CDP_VERSION = "refs/heads/master"
To find specific commits, visit: https://github.com/ChromeDevTools/devtools-protocol/commits/master
Available Tasks
task generate # Regenerate CDP types from protocol definitions
task build # Build the distribution package
task lint # Run ruff linter
task format # Format code with ruff
task format-json # Format JSON protocol files
task example # Run the simple example
task clean # Clean generated files and build artifacts
Project Structure
cdp-use/
├── cdp_use/
│ ├── client.py # Core CDP WebSocket client
│ ├── generator/ # Code generation tools
│ └── cdp/ # Generated CDP library (auto-generated)
├── simple.py # Example usage
└── README.md
🤝 Contributing
- Fork the repository
- Make changes to generator code (not the generated
cdp_use/cdp/directory) - Run
python -m cdp_use.generatorto regenerate - Test with
python simple.py - Submit a pull request
🔗 Related
Generated from Chrome DevTools Protocol specifications • Type-safe • Zero runtime overhead
Metadata
Release files for cdp-use 1.4.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cdp_use-1.4.5.tar.gz | 194.0 kB | Without provenance | Details for cdp_use-1.4.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cdp_use-1.4.5-py3-none-any.whl | Python 3 | none | any | Details for cdp_use-1.4.5-py3-none-any.whl |
Total release size: 544.5 kB
Release files / cdp_use-1.4.5.tar.gz
| Download URL | cdp_use-1.4.5.tar.gz |
|---|---|
| Size | 194.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0da3a32df46336a03ff5a22bc6bc442cd7d2f2d50a118fd4856f29d37f6d26a0
|
|
BLAKE2b-256 checksum How to use checksums |
f77ac549417e8c5e4dface6d5d828cd7dc72502dcea33a99f5324abf5a853ce9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.7.19
|
Release files / cdp_use-1.4.5-py3-none-any.whl
| Download URL | cdp_use-1.4.5-py3-none-any.whl |
|---|---|
| Size | 350.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8f8e2435e3a20e4009d2974144192cf3c132f6c2971338e156198814d9b91ecb
|
|
BLAKE2b-256 checksum How to use checksums |
5612386d8c6bf0448c43674e24d6194c3b57d62e5361e90bca3d58108819ad32
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.7.19
|
Security for cdp-use 1.4.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.