PyCDP

Python Chrome DevTools Protocol (shortened to PyCDP) is a library that provides Python wrappers for the types, commands, and events specified in the Chrome DevTools Protocol.

The Chrome DevTools Protocol provides for remote control of a web browser by sending JSON messages over a WebSocket. That JSON format is described by a machine-readable specification. This specification is used to automatically generate the classes and methods found in this library.

You could write a CDP client by connecting a WebSocket and then sending JSON objects, but this would be tedious and error-prone: the Python interpreter would not catch any typos in your JSON objects, and you wouldn't get autocomplete for any parts of the JSON data structure. By providing a set of native Python wrappers, this project makes it easier and faster to write CDP client code.

Two Usage Modes

Sans-I/O Mode (original): The core library provides type wrappers without performing any I/O. This maximizes flexibility and allows integration with any async framework. This is ideal for users who want to integrate CDP with their own I/O stack or use libraries like trio-chrome-devtools-protocol.

I/O Mode (new): The library now includes cdp.connection module that provides WebSocket I/O, JSON-RPC message framing, and command multiplexing out of the box. This makes it easy to get started with CDP without writing any I/O code yourself.

Installation

Basic installation (Sans-I/O mode only):

pip install chrome-devtools-protocol

With I/O support:

pip install chrome-devtools-protocol[io]

Quick Start with I/O Mode

import asyncio
from cdp.connection import CDPConnection
from cdp import page

async def main():
    # Connect to a Chrome DevTools Protocol endpoint
    async with CDPConnection("ws://localhost:9222/devtools/page/YOUR_PAGE_ID") as conn:
        # Navigate to a URL
        frame_id, loader_id, error = await conn.execute(
            page.navigate(url="https://example.com")
        )
        print(f"Navigated to example.com, frame_id: {frame_id}")

asyncio.run(main())

Key Features of I/O Mode

• WebSocket Management: Automatic connection lifecycle management with async context managers
• JSON-RPC Framing: Automatic message ID assignment and request/response matching
• Command Multiplexing: Execute multiple commands concurrently with proper tracking
• Event Handling: Async iterator for receiving browser events
• Error Handling: Comprehensive error handling with typed exceptions

See the examples directory for more usage patterns.

Sans-I/O Mode (Original)

For users who prefer to manage their own I/O:

from cdp import page

frame_id = page.FrameId('my id')
assert repr(frame_id) == "FrameId('my id')"

API Documentation

For detailed API documentation, see:

• Complete Documentation - Full API reference on Read the Docs
• Chrome DevTools Protocol - Official CDP specification
• Examples - Code examples demonstrating usage patterns

Key Modules

• cdp.connection - WebSocket I/O and connection management (I/O mode)
• cdp.<domain> - Type wrappers for each CDP domain (e.g., cdp.page, cdp.network, cdp.runtime)
• Each domain module provides types, commands, and events for that CDP domain

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Setting up your development environment
• Running tests and type checking
• Submitting pull requests
• Reporting issues

Please also read our Code of Conduct before contributing.

Security

For information about reporting security vulnerabilities, please see our Security Policy.

License

This project is licensed under the MIT License - see the LICENSE file for details.

API Reference

The library provides Python wrappers for all Chrome DevTools Protocol domains:

• Page: Page control (navigation, screenshots, etc.)
• DOM: DOM inspection and manipulation
• Network: Network monitoring and interception
• Runtime: JavaScript execution and evaluation
• Debugger: JavaScript debugging
• Performance: Performance metrics and profiling
• Security: Security-related information
• And many more...

For complete API documentation, visit py-cdp.readthedocs.io.

Type System

All CDP types, commands, and events are fully typed with Python type hints, providing:

• IDE autocomplete support
• Static type checking with mypy
• Clear API contracts
• Inline documentation

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• How to report bugs and request features
• Development setup and workflow
• Coding standards and testing requirements
• Pull request process

For questions or discussions, feel free to open an issue on GitHub.

License

This project is licensed under the MIT License - see the LICENSE file for details.