Connection Handler

pydoll.connection.connection_handler.ConnectionHandler

ConnectionHandler(connection_port=None, page_id=None, ws_address_resolver=get_browser_ws_address, ws_connector=connect, ws_address=None)

WebSocket connection manager for Chrome DevTools Protocol endpoints.

Handles connection lifecycle, command execution, and event subscription for both browser-level and page-level CDP endpoints.

Initialize connection handler.

PARAMETER	DESCRIPTION
connection_port	Browser's debugging server port. TYPE: Optional[int] DEFAULT: None
page_id	Target page ID. If None, connects to browser-level endpoint. TYPE: Optional[str] DEFAULT: None
ws_address_resolver	Function to resolve WebSocket URL from port. TYPE: Callable[[int], Coroutine[Any, Any, str]] DEFAULT: get_browser_ws_address
ws_connector	WebSocket connection factory (mainly for testing). TYPE: type[connect] DEFAULT: connect
ws_address	WebSocket address. It has priority over connection_port and page_id. TYPE: Optional[str] DEFAULT: None

network_logs property

network_logs

Access captured network request and response logs.

dialog property

dialog

Access currently active JavaScript dialog information.

ping async

ping()

Test if WebSocket connection is active and responsive.

execute_command async

execute_command(command, timeout=10)

Send CDP command and await response.

PARAMETER	DESCRIPTION
command	CDP command to send. TYPE: Command[T_CommandParams, T_CommandResponse]
timeout	Maximum seconds to wait for response. TYPE: int DEFAULT: 10

RETURNS	DESCRIPTION
T_CommandResponse	Parsed response object matching command's expected type.

RAISES	DESCRIPTION
CommandExecutionTimeout	If browser doesn't respond within timeout.
WebSocketConnectionClosed	If connection closes during execution.

register_callback async

register_callback(event_name, callback, temporary=False)

Register event listener for CDP events.

PARAMETER	DESCRIPTION
event_name	CDP event name (e.g., 'Page.loadEventFired'). TYPE: str
callback	Async function called when event occurs. TYPE: Callable[[dict], Awaitable[None]]
temporary	If True, callback removed after first trigger. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
int	Callback ID for later removal.

Note

Corresponding CDP domain must be enabled before events fire.

remove_callback async

remove_callback(callback_id)

Remove registered event callback by ID.

clear_callbacks async

clear_callbacks()

Remove all registered event callbacks.

close async

close()

Close WebSocket connection and release resources.