Registry / web-framework / cdp-socket

cdp-socket

JSON →
library1.2.8pypypi✓ verified 89d ago

cdp-socket is a Python library designed for programmatically interacting with the Chrome DevTools Protocol (CDP). It provides a high-level asynchronous API to control Chrome-based browsers, enabling tasks such as browser automation, scraping, and debugging. The library is currently at version 1.2.8, with its last release in April 2024, indicating active maintenance and a regular, albeit not fixed, release cadence.

pip install cdp-socket
INSTALL
IMPORT
SIG · CDP-SOCKET
C
cdp-socket
web-frameworkpythonv1.2.8
Install
6.4s avg
Import
516ms
Disk
28MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v1.2.8 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.543s · 29MB
glibc
py 3.10–3.920 runs
installs and imports cleanly · install 6.4s · import 0.489s · 31MB
28MB installed
● package 28MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

SingleCDPSocket
✓ from cdp_socket.socket import SingleCDPSocket
launch_chrome
✓ from cdp_socket.utils.utils import launch_chrome
random_port
✓ from cdp_socket.utils.utils import random_port
get_websock_url
✓ from cdp_socket.utils.conn import get_websock_url

This quickstart launches a headless Chrome instance, connects to its DevTools Protocol WebSocket, retrieves active targets, and then gracefully closes the browser. It includes setup for a temporary data directory and clean-up. Ensure a Chrome-based browser is installed on your system.

import asyncio import os import shutil from cdp_socket.utils.utils import launch_chrome, random_port from cdp_socket.utils.conn import get_websock_url from cdp_socket.socket import SingleCDPSocket async def main(): data_dir = os.path.join(os.getcwd(), "cdp_data_dir") port = random_port() process = None try: process = launch_chrome(data_dir, port) websock_url = await get_websock_url(port, timeout=5) async with SingleCDPSocket(websock_url, timeout=5) as sock: targets = await sock.exec("Target.getTargets") print(f"Active targets: {targets}") # Example: Navigate to a page # This assumes you have a page target. The 'Target.getTargets' output helps identify it. # For browser-level commands, you directly use the 'sock' object. # For page-specific commands, you might need to attach to a page target first. # For simplicity, this example just fetches targets. except Exception as e: print(f"An error occurred: {e}") finally: if process and process.poll() is None: # Check if process is still running os.kill(process.pid, 15) # Terminate Chrome gracefully if os.path.exists(data_dir): shutil.rmtree(data_dir) if __name__ == "__main__": asyncio.run(main())
Debug
Known issues
gotchaChrome/Chromium browser must be installed and accessible in the system's PATH, or its path explicitly provided to `launch_chrome`. If the browser is not found, `launch_chrome` will fail.
fix
Ensure Chrome or Chromium is installed. On Linux, verify `google-chrome` or `chromium-browser` is in PATH. On Windows/macOS, ensure the default installation path is used or add it to PATH.
affects: All
breakingConnecting to the wrong CDP endpoint (e.g., browser-level vs. page-level) will cause commands to fail with 'command not found' or 'invalid session ID' errors. Browser-level commands require a browser target, while DOM/Page/Network commands require a page target.
fix
After launching Chrome, retrieve available targets using `Target.getTargets()`. Identify the correct `webSocketDebuggerUrl` for the specific page or context you intend to control. For page-specific operations, ensure you're connecting to a page target's WebSocket URL.
affects: All
gotchaAs `cdp-socket` is an asynchronous library, operations must be awaited within an `async` function. Improper handling of `await` calls will lead to `RuntimeWarning: coroutine '...' was never awaited` or blocks in execution.
fix
Always `await` calls to `SingleCDPSocket` methods and `get_websock_url` within an `async` function. Run the main asynchronous function using `asyncio.run()`.
affects: All
Errors
Common errors & fixes
RuntimeWarning: Enable tracemalloc to get the object allocation traceback
The `launch_chrome` function or subsequent operations are not correctly terminating the Chrome browser process, leading to orphaned processes and resource leaks.
fix
Ensure `os.kill(process.pid, 15)` is called in a `finally` block to guarantee the Chrome process is terminated even if errors occur. Also, consider removing the temporary data directory with `shutil.rmtree()`.
cdp_socket.utils.conn.WebSocketConnectionError: Failed to connect to websocket url ... after ... seconds
The Chrome browser did not start correctly, or the remote debugging port was not exposed, or the connection attempt timed out.
fix
Verify that Chrome is installed and runnable. Check the logs for `launch_chrome` to see if it printed any errors. Increase the `timeout` parameter for `get_websock_url` and `SingleCDPSocket` if running on a slower system.
await sock.exec("Page.navigate", {"url": "https://example.com"}) resulted in an error like 'Target.navigate' was not found.
You are attempting to use a page-specific command (like 'Page.navigate') on a browser-level target, or vice-versa. Some commands are scoped to the overall browser, while others are specific to a particular page or execution context.
fix
First, use `Target.getTargets()` to list all available targets. Identify the 'page' target's WebSocket URL. You may need to create a new `SingleCDPSocket` instance connected to that specific page URL if you're not already, or ensure your initial connection is to a page target if that's your intent. The `sock.exec` method can target specific sessions using a `sessionId` if you attach to a target.
Upgrade
Version history
1.2.8latest on PyPI · released Apr 28, 2024
Audit
Dependencies
PythonrequiredRuntime environment
Chrome-BrowserrequiredRequired for Chrome DevTools Protocol communication
Agent activity
20 hits · last 30 days
node
18
OpenAI (training)
1
Resources
cdp-socket — pip install cdp-socket · libregistry