ddp_utils.ws_intercom.windscribe_api

import ddp_utils.ws_intercom.windscribe_api

Complete Windscribe adapter facade for page and native Chromium contexts.

Examples

Use this public operation:

import ddp_utils.ws_intercom.windscribe_api

exception ddp_utils.ws_intercom.windscribe_api.WindscribeAPIError(message: str, *, code: str = 'WINDSCRIBE_ERROR', retryable: bool = False, details: Any = None, operation: Mapping[str, Any] | None = None)

Bases: RuntimeError

Preserve canonical Windscribe adapter error metadata.

Examples

Use this public operation:

instance = WindscribeAPIError(...)

Create an adapter error without exposing request credentials.

Parameters

Name	Type	Description
message	str	Human-readable error text.
code	str	Canonical error code.
retryable	bool	Whether repeating the request may succeed.
details	Any	Extra structured error details.
operation	Optional[Mapping[str, Any]]	Snapshot of the failed operation; copied.

class ddp_utils.ws_intercom.windscribe_api.WindscribeBrowserScenario(browser: LocalChromiumBrowser)

Bases: object

Use the installed Windscribe extension through a generic CDP browser.

The scenario never installs, loads, enables, disables, or updates the extension. It only opens an allowed loopback page and verifies its API.

Examples

Use this public operation:

instance = WindscribeBrowserScenario(...)

Bind an already configured local Chromium browser.

Parameters

Name	Type	Description
browser	LocalChromiumBrowser	Already configured local Chromium browser.

start() → WindscribeBrowserScenario

Open the bridge page and verify the installed extension API.

Returns

Type	Description
WindscribeBrowserScenario	This scenario, started and verified.

Raises

Exception	Description
RuntimeError	If the local Chromium CDP connection is unavailable.
WindscribeAPIError	If the page API of the extension is unavailable (code WINDSCRIBE_EXTENSION_UNAVAILABLE).

Examples

Use this public operation:

result = instance.start()

client(*, timeout: float = 30.0, operation_timeout: float = 120.0) → WindscribeClient

Return a Python facade bound to the active browser scenario.

Parameters

Name	Type	Description
timeout	float	Default request timeout, in seconds.
operation_timeout	float	Default time to wait for an operation, in seconds.

Returns

Type	Description
WindscribeClient	WindscribeClient bound to the scenario transport.

Raises

Exception	Description
RuntimeError	If the scenario is not started.

Examples

Use this public operation:

result = instance.client()

close() → None

Release only resources owned by this scenario.

Examples

Use this public operation:

result = instance.close()

class ddp_utils.ws_intercom.windscribe_api.WindscribeCDPTransport(connection: CDPConnection, *, timeout: float = 30.0)

Bases: object

Canonical transport evaluated through a raw Chrome DevTools connection.

Examples

Use this public operation:

instance = WindscribeCDPTransport(...)

Bind a generic connection to a Chromium page target.

Parameters

Name	Type	Description
connection	CDPConnection	CDP connection to a Chromium page target.
timeout	float	Default timeout for evaluations, in seconds.

evaluate(expression: str, *, await_promise: bool = False) → Any

Evaluate JavaScript and return its JSON-compatible by-value result.

Parameters

Name	Type	Description
expression	str	JavaScript expression to evaluate.
await_promise	bool	Wait for the promise returned by the expression.

Returns

Type	Description
Any	JSON-compatible by-value result of the expression.

Examples

Use this public operation:

result = instance.evaluate(expression=expression_value)

install_client(javascript: str) → None

Install the packaged JavaScript facade in the native bridge page.

Parameters

Name	Type	Description
javascript	str	Source of the packaged JavaScript client.

Examples

Use this public operation:

result = instance.install_client(javascript=javascript_value)

request(command: str, params: Mapping[str, Any], *, timeout: float, idempotency_key: str | None = None) → Mapping[str, Any]

Await one JavaScript facade request through CDP without Selenium.

Parameters

Name	Type	Description
command	str	Canonical command name, for example "state.get".
params	Mapping[str, Any]	Command parameters.
timeout	float	Seconds to wait for the response.
idempotency_key	str | None	Optional key that makes a repeated request idempotent.

Returns

Type	Description
Mapping[str, Any]	Result mapping of the command.

Raises

Exception	Description
WindscribeAPIError	If the CDP response is invalid, contains no result object, or reports an adapter error.

Examples

Use this public operation:

result = instance.request(command=command_value, params=params_value, timeout=timeout_value)

class ddp_utils.ws_intercom.windscribe_api.WindscribeClient(transport: WindscribeTransport, *, timeout: float = 30.0, operation_timeout: float = 120.0, poll_interval: float = 0.5)

Bases: object

Complete synchronous Python facade for canonical Windscribe commands.

Examples

Use this public operation:

instance = WindscribeClient(...)

Bind a transport and common request/operation timeout defaults.

Parameters

Name	Type	Description
transport	WindscribeTransport	Transport that executes the canonical commands.
timeout	float	Default request timeout, in seconds; must be greater than zero.
operation_timeout	float	Default time to wait for an operation, in seconds; must be greater than zero.
poll_interval	float	Seconds between operation polls; must be greater than zero.

Raises

Exception	Description
ValueError	If a timeout or poll_interval is not greater than zero.

request(command: str, params: Mapping[str, Any] | None = None, *, timeout: float | None = None, idempotency_key: str | None = None) → Mapping[str, Any]

Execute any canonical command through the configured transport.

Parameters

Name	Type	Description
command	str	Canonical command name, for example "state.get".
params	Mapping[str, Any] | None	Command parameters; empty when omitted.
timeout	float | None	Request timeout in seconds; the client default when omitted.
idempotency_key	str | None	Optional key that makes a repeated request idempotent.

Returns

Type	Description
Mapping[str, Any]	Result mapping of the command.

Examples

Use this public operation:

result = instance.request(command=command_value)

mutate(command: str, params: Mapping[str, Any] | None = None, *, timeout: float | None = None, operation_timeout: float | None = None, idempotency_key: str | None = None) → Mapping[str, Any]

Create an idempotent mutation and wait for terminal operation success.

Parameters

Name	Type	Description
command	str	Canonical command name of the mutation.
params	Mapping[str, Any] | None	Command parameters; empty when omitted.
timeout	float | None	Request timeout in seconds; the client default when omitted.
operation_timeout	float | None	Time to wait for the operation in seconds; the client default when omitted.
idempotency_key	str | None	Idempotency key; generated when omitted.

Returns

Type	Description
Mapping[str, Any]	Mapping of the successful terminal operation.

Raises

Exception	Description
WindscribeAPIError	If the command returns no operation, or the operation fails or times out.

Examples

Use this public operation:

result = instance.mutate(command=command_value)

wait_operation(operation_id: str, *, timeout: float | None = None) → Mapping[str, Any]

Poll until an operation succeeds or raises its terminal error.

Parameters

Name	Type	Description
operation_id	str	Identifier of the operation to wait for.
timeout	float | None	Time to wait in seconds; the client operation timeout when omitted.

Returns

Type	Description
Mapping[str, Any]	Mapping of the successful terminal operation.

Raises

Exception	Description
WindscribeAPIError	If the operation ends in a failed terminal state, no operation snapshot is returned, or the wait times out (code CLIENT_OPERATION_TIMEOUT).

Examples

Use this public operation:

result = instance.wait_operation(operation_id=operation_id_value)

system_describe() → Mapping[str, Any]

Return adapter capabilities and protocol metadata.

Returns

Type	Description
Mapping[str, Any]	Adapter capabilities and protocol metadata.

Examples

Use this public operation:

result = instance.system_describe()

state_get() → Mapping[str, Any]

Return the current extension state snapshot.

Returns

Type	Description
Mapping[str, Any]	Current extension state snapshot.

Examples

Use this public operation:

result = instance.state_get()

locations_list() → Mapping[str, Any]

Return the currently cached VPN location catalog.

Returns

Type	Description
Mapping[str, Any]	Cached VPN location catalog.

Examples

Use this public operation:

result = instance.locations_list()

locations_refresh(**params: Any) → Mapping[str, Any]

Refresh locations and wait for the operation to finish.

Parameters

Name	Type	Description
**params	Any	Command parameters passed to the adapter.

Returns

Type	Description
Mapping[str, Any]	Mapping of the successful terminal operation.

Examples

Use this public operation:

result = instance.locations_refresh()

auth_get() → Mapping[str, Any]

Return current authentication state.

Returns

Type	Description
Mapping[str, Any]	Current authentication state.

Examples

Use this public operation:

result = instance.auth_get()

auth_check(**params: Any) → Mapping[str, Any]

Check authentication and wait for the operation to finish.

Parameters

Name	Type	Description
**params	Any	Command parameters passed to the adapter.

Returns

Type	Description
Mapping[str, Any]	Mapping of the successful terminal operation.

Examples

Use this public operation:

result = instance.auth_check()

auth_store_credentials(username: str, password: str, *, two_fa: str | None = None) → Mapping[str, Any]

Store login credentials without retaining or logging them in Python.

Parameters

Name	Type	Description
username	str	Account user name.
password	str	Account password.
two_fa	str | None	Optional two-factor authentication code.

Returns

Type	Description
Mapping[str, Any]	Adapter response mapping.

Examples

Use this public operation:

result = instance.auth_store_credentials(username=username_value, password=password_value)

auth_login(**params: Any) → Mapping[str, Any]

Log in and wait for the operation to finish.

Parameters

Name	Type	Description
**params	Any	Command parameters passed to the adapter.

Returns

Type	Description
Mapping[str, Any]	Mapping of the successful terminal operation.

Examples

Use this public operation:

result = instance.auth_login()

auth_logout(**params: Any) → Mapping[str, Any]

Log out and wait for the operation to finish.

Parameters

Name	Type	Description
**params	Any	Command parameters passed to the adapter.

Returns

Type	Description
Mapping[str, Any]	Mapping of the successful terminal operation.

Examples

Use this public operation:

result = instance.auth_logout()

vpn_connect(**params: Any) → Mapping[str, Any]

Connect the VPN and wait for the operation to finish.

Parameters

Name	Type	Description
**params	Any	Command parameters passed to the adapter.

Returns

Type	Description
Mapping[str, Any]	Mapping of the successful terminal operation.

Examples

Use this public operation:

result = instance.vpn_connect()

vpn_disconnect(**params: Any) → Mapping[str, Any]

Disconnect the VPN and wait for the operation to finish.

Parameters

Name	Type	Description
**params	Any	Command parameters passed to the adapter.

Returns

Type	Description
Mapping[str, Any]	Mapping of the successful terminal operation.

Examples

Use this public operation:

result = instance.vpn_disconnect()

vpn_change_location(**params: Any) → Mapping[str, Any]

Change location and wait for the operation to finish.

Parameters

Name	Type	Description
**params	Any	Command parameters passed to the adapter.

Returns

Type	Description
Mapping[str, Any]	Mapping of the successful terminal operation.

Examples

Use this public operation:

result = instance.vpn_change_location()

operation_get(operation_id: str) → Mapping[str, Any]

Return one operation snapshot.

Parameters

Name	Type	Description
operation_id	str	Identifier of the operation.

Returns

Type	Description
Mapping[str, Any]	Mapping with the operation snapshot.

Examples

Use this public operation:

result = instance.operation_get(operation_id=operation_id_value)

events_subscribe(topics: Sequence[str] = ('all',)) → Mapping[str, Any]

Create an adapter event subscription.

Parameters

Name	Type	Description
topics	Sequence[str]	Event topics to subscribe to; all events by default.

Returns

Type	Description
Mapping[str, Any]	Mapping describing the new subscription.

Examples

Use this public operation:

result = instance.events_subscribe()

events_unsubscribe(subscription_id: str) → Mapping[str, Any]

Remove an adapter event subscription.

Parameters

Name	Type	Description
subscription_id	str	Identifier of the subscription to remove.

Returns

Type	Description
Mapping[str, Any]	Adapter response mapping.

Examples

Use this public operation:

result = instance.events_unsubscribe(subscription_id=subscription_id_value)

events_poll(*, cursor: int = 0, topics: Sequence[str] = ('all',), limit: int = 100) → Mapping[str, Any]

Poll canonical events and retain the returned worker instance ID.

Parameters

Name	Type	Description
cursor	int	Position after which events are read.
topics	Sequence[str]	Event topics to read; all events by default.
limit	int	Maximum number of events returned.

Returns

Type	Description
Mapping[str, Any]	Mapping with the polled events.

Examples

Use this public operation:

result = instance.events_poll()

file_download(data_url: str, filename: str, *, subfolder: str | None = None) → Mapping[str, Any]

Request a browser download from a data URL.

Parameters

Name	Type	Description
data_url	str	Data URL whose content is downloaded.
filename	str	Name of the downloaded file.
subfolder	str | None	Optional subfolder for the downloaded file.

Returns

Type	Description
Mapping[str, Any]	Adapter response mapping.

Examples

Use this public operation:

result = instance.file_download(data_url=data_url_value, filename=filename_value)

external_access_get() → Mapping[str, Any]

Return the extension external-access allowlist.

Returns

Type	Description
Mapping[str, Any]	External-access allowlist of the extension.

Examples

Use this public operation:

result = instance.external_access_get()

external_access_configure(ids: Mapping[str, Any]) → Mapping[str, Any]

Replace the extension external-access allowlist explicitly.

Parameters

Name	Type	Description
ids	Mapping[str, Any]	Mapping that replaces the external-access allowlist.

Returns

Type	Description
Mapping[str, Any]	Adapter response mapping.

Examples

Use this public operation:

result = instance.external_access_configure(ids=ids_value)

class ddp_utils.ws_intercom.windscribe_api.WindscribePageTransport(executor: Any)

Bases: object

Canonical page transport for Selenium-compatible browser executors.

Examples

Use this public operation:

instance = WindscribePageTransport(...)

Bind an object that provides execute_async_script.

Parameters

Name	Type	Description
executor	Any	Object that provides execute_async_script, such as a Selenium driver.

Raises

Exception	Description
TypeError	If executor provides no execute_async_script.

request(command: str, params: Mapping[str, Any], *, timeout: float, idempotency_key: str | None = None) → Mapping[str, Any]

Send a canonical postMessage request from the current page.

Parameters

Name	Type	Description
command	str	Canonical command name, for example "state.get".
params	Mapping[str, Any]	Command parameters.
timeout	float	Seconds to wait for the response.
idempotency_key	str | None	Optional key that makes a repeated request idempotent.

Returns

Type	Description
Mapping[str, Any]	Result mapping of the command.

Examples

Use this public operation:

result = instance.request(command=command_value, params=params_value, timeout=timeout_value)

class ddp_utils.ws_intercom.windscribe_api.WindscribeTransport(*args, **kwargs)

Bases: Protocol

Minimal synchronous transport required by WindscribeClient.

Examples

Use this public operation:

instance = WindscribeTransport(...)

request(command: str, params: Mapping[str, Any], *, timeout: float, idempotency_key: str | None = None) → Mapping[str, Any]

Execute one canonical adapter command and return its result.

Parameters

Name	Type	Description
command	str	Canonical command name, for example "state.get".
params	Mapping[str, Any]	Command parameters.
timeout	float	Seconds to wait for the response.
idempotency_key	str | None	Optional key that makes a repeated request idempotent.

Returns

Type	Description
Mapping[str, Any]	Result mapping of the command.

Examples

Use this public operation:

result = instance.request(command=command_value, params=params_value, timeout=timeout_value)

ddp_utils.ws_intercom.windscribe_api.get_windscribe_javascript_api() → str

Return the packaged complete page-context JavaScript client source.

Returns

Type	Description
str	JavaScript source text of the client.

Examples

Use this public operation:

result = ddp_utils.ws_intercom.windscribe_api.get_windscribe_javascript_api()