cdpwave 2.2.1

Chrome DevTools Protocol for Python — direct CDP over WebSocket, no Selenium, no Playwright

cdpwave

Chrome DevTools Protocol for Python — direct, typed, async.

cdpwave talks to Chrome over a raw WebSocket. No Node.js, no ChromeDriver, no browser downloads. Just pure Python with full type hints and async-first design.

Why cdpwave?

• Full CDP coverage — all 48 CDP domains implemented with 386 typed methods
• Direct WebSocket — single connection to Chrome's DevTools Protocol, no intermediate layers
• Fully typed — mypy --strict across the entire codebase, IDE autocomplete everywhere
• Async-first — built on asyncio, no threading, no blocking calls
• Browser detection — finds Chrome, Edge, Brave, or Chromium already on your system
• Flatten sessions — one WebSocket for all tabs via Target.attachToTarget + sessionId
• Escape hatch — session.send("Any.CDPMethod", params) for any uncovered command
• HTTP discovery — typed access to /json/version and /json/list endpoints
• WebSocket keepalive — automatic ping/pong with configurable interval and timeout
• Direct WebSocket URL — CDPClient.connect(ws_url=...) bypasses HTTP discovery
• Event helpers — session.wait_for_event() and session.on() for async event handling
• Multi-tab sessions — client.sessions property tracks all active sessions
• MIT licensed — permissive, compatible with any use

Install

pip install cdpwave

Quick start

import asyncio
from cdpwave import CDPClient

async def main() -> None:
    async with await CDPClient.launch(headless=True) as client:
        session = await client.new_page("https://example.com")
        result = await session.runtime.evaluate("document.title", return_by_value=True)
        print(result["result"]["value"])  # "Example Domain"
        await session.close()

asyncio.run(main())

Documentation

Full documentation at mathiaspaulenko.github.io/cdpwave.

• Quickstart — 10-minute tutorial
• Guide — in-depth feature coverage
• Cookbook — common recipes
• API Reference — auto-generated docs
• Migration — from pyppeteer or pychrome

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines on development setup, code style, testing, and pull request process.

Please read our Code of Conduct before participating.

Security

Found a vulnerability? See SECURITY.md for responsible disclosure.

License

MIT