ConnectionHandler

管理与浏览器的 WebSocket 连接，并路由 CDP 命令和事件。详见 远程连接。

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: int | None DEFAULT: None
page_id	Target page ID. If None, connects to browser-level endpoint. TYPE: str | None 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: str | None 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=60)

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: 60

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

RAISES	DESCRIPTION
CommandFailed	If the browser answers with a CDP error instead of a result.
InvalidResponse	If the response carries neither a result nor an error.
CommandExecutionTimeout	If browser doesn't respond within timeout.
WebSocketConnectionClosed	If connection closes during execution.

execute_command_nowait async

execute_command_nowait(command)

Send a CDP command and return as soon as it is on the wire.

The answer is still consumed when it arrives, so the pending table stays clean, and a CDP error is logged instead of raised. Meant for streams of input events whose order the socket already guarantees: awaiting each answer would add a network round trip between consecutive mouse moves, which no real input device has.

PARAMETER	DESCRIPTION
command	CDP command to send. TYPE: Command[T_CommandParams, T_CommandResponse]

RAISES	DESCRIPTION
WebSocketConnectionClosed	If the connection cannot be (re)established.

execute_commands async

execute_commands(commands, timeout=60)

Send several commands back to back and wait for all of their answers.

The browser handles the commands of one session in the order they arrive, so sending a sequence without waiting for each answer keeps the ordering (keydown before keyup, for example) while paying one round trip for the whole batch instead of one per command.

PARAMETER	DESCRIPTION
commands	Commands to send, in order. TYPE: Sequence[Command[T_CommandParams, T_CommandResponse]]
timeout	Seconds to wait for the last answer. TYPE: int DEFAULT: 60

RETURNS	DESCRIPTION
list[T_CommandResponse]	The responses, in the same order as commands.

RAISES	DESCRIPTION
CommandFailed	If the browser rejects any command in the batch.
CommandExecutionTimeout	If the answers do not all arrive in time.
WebSocketConnectionClosed	If the connection closes meanwhile.

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.