ddp_utils.browser.backends.selenium.proxy

import ddp_utils.browser.backends.selenium.proxy

Backend-neutral proxy configuration for browser sessions.

The module models fixed, per-protocol, PAC, system, direct, and provider-backed proxy modes. Windscribe is one possible ProxyProvider implementation; the browser factory does not import or depend on it.

exception ddp_utils.browser.backends.selenium.proxy.ProxyConfigurationError

Bases: ValueError

A proxy configuration is incomplete, contradictory, or malformed.

Examples

Use this public operation:

instance = ProxyConfigurationError()

class ddp_utils.browser.backends.selenium.proxy.ProxyLease(*args, **kwargs)

Bases: Protocol

Resource acquired from a managed proxy provider.

Examples

Use this public operation:

instance = ProxyLease()

property proxy_url: str

Return the browser-reachable proxy endpoint.

Returns

Provider-managed proxy URL accepted by the browser backend.

Examples

Consume a lease without depending on its concrete provider:

def endpoint(lease: ProxyLease) -> str:
    return lease.proxy_url

close() → None

Release provider-owned resources.

Examples

Use this public operation:

result = proxy_lease.close()

class ddp_utils.browser.backends.selenium.proxy.ProxyMode(value)

Bases: str, Enum

Supported browser proxy selection modes.

Examples

Use this public operation:

instance = ProxyMode()

classmethod parse(value: Any) → ProxyMode

Normalize a user-provided proxy mode.

Parameters

Name	Type	Description
value	Any	Existing enum value or case-insensitive string.

Returns

Type	Description
ProxyMode	A normalized ProxyMode.

Raises

Exception	Description
ValueError	If the mode is unknown.

Examples

Use this public operation:

result = proxy_mode.parse(value)

class ddp_utils.browser.backends.selenium.proxy.ProxyProvider(*args, **kwargs)

Bases: Protocol

Create a temporary browser proxy endpoint for a logical location.

Examples

Use this public operation:

instance = ProxyProvider()

acquire(location: Any, **options: Any) → ProxyLease

Acquire a provider lease.

Parameters

Name	Type	Description
location	Any	Provider-specific location or endpoint descriptor.
**options	Any	Provider-specific acquisition options.

Returns

Type	Description
ProxyLease	A lease exposing proxy_url and close().

Examples

Use this public operation:

result = proxy_provider.acquire(location)

class ddp_utils.browser.backends.selenium.proxy.ProxySettings(mode: ProxyMode, server: str | None = None, http: str | None = None, https: str | None = None, socks: str | None = None, pac_url: str | None = None, username: str | None = None, password: str | None = None, bypass: tuple[str, ...]=(), provider: ProxyProvider | None = None, location: Any = None, provider_options: Mapping[str, ~typing.Any]=<factory>, prevent_leaks: bool = True, verification: ProxyVerificationSettings | None = None)

Bases: object

Describe one proxy policy independently of Selenium or SeleniumBase.

Parameters

Name	Type	Description
mode	ProxyMode	Fixed, manual, PAC, system, direct, or provider mode.
server	str | None	Single proxy URL for all protocols in fixed mode.
http	str | None	HTTP proxy URL in manual mode.
https	str | None	HTTPS destination proxy URL in manual mode.
socks	str | None	SOCKS4/SOCKS5 proxy URL in manual mode.
pac_url	str | None	Proxy Auto-Configuration URL.
username	str | None	Optional proxy authentication username.
password	str | None	Optional proxy authentication password.
bypass	tuple[str, ...]	Host patterns that bypass the proxy.
provider	ProxyProvider | None	Managed proxy provider.
location	Any	Provider-specific logical location.
provider_options	Mapping[str, Any]	Keyword options passed to provider.acquire.
prevent_leaks	bool	Apply browser DNS, QUIC, and WebRTC leak protections.
verification	ProxyVerificationSettings | None	Optional egress verification.

Credentials may also be embedded in server or a manual URL. Explicit username and password take precedence and are excluded from repr.

Examples

Use this public operation:

instance = ProxySettings()

property has_authentication: bool

Return whether explicit or embedded credentials are configured.

Returns

True when separate credentials are present or any configured endpoint embeds a username; otherwise False.

Examples

Detect credentials embedded in a fixed endpoint:

settings = ProxySettings.fixed(
    "http://user:secret@127.0.0.1:8080"
)
assert settings.has_authentication

property authentication: tuple[str | None, str | None]

Return effective proxy username and password.

Returns

(username, password) with URL-decoding applied.

Examples

Use this public operation:

result = proxy_settings.authentication()

property uses_socks_authentication: bool

Return whether an authenticated SOCKS endpoint is configured.

Returns

True when effective credentials exist and the applicable fixed or protocol-specific endpoint uses a SOCKS scheme.

Examples

Detect an authenticated SOCKS endpoint:

settings = ProxySettings.fixed(
    "socks5://user:secret@127.0.0.1:1080"
)
assert settings.uses_socks_authentication

classmethod fixed(server: str, *, username: str | None = None, password: str | None = None, bypass: Iterable[str] = (), prevent_leaks: bool = True, verification: ProxyVerificationSettings | None = None) → ProxySettings

Create a single endpoint used for every browser protocol.

Parameters

Name	Type	Description
server	str	HTTP, HTTPS, SOCKS4, or SOCKS5 proxy URL.
username	str | None	Optional proxy username.
password	str | None	Optional proxy password.
bypass	Iterable[str]	Host patterns routed directly.
prevent_leaks	bool	Apply DNS, QUIC, and WebRTC protections.
verification	ProxyVerificationSettings | None	Optional egress verification.

Returns

Type	Description
ProxySettings	Validated fixed proxy settings.

Examples

Use this public operation:

result = proxy_settings.fixed(server)

classmethod manual(*, http: str | None = None, https: str | None = None, socks: str | None = None, username: str | None = None, password: str | None = None, bypass: Iterable[str] = (), prevent_leaks: bool = True, verification: ProxyVerificationSettings | None = None) → ProxySettings

Create per-protocol proxy settings.

Parameters

Name	Type	Description
http	str | None	HTTP destination proxy.
https	str | None	HTTPS destination proxy.
socks	str | None	SOCKS fallback proxy.
username	str | None	Optional shared proxy username.
password	str | None	Optional shared proxy password.
bypass	Iterable[str]	Host patterns routed directly.
prevent_leaks	bool	Apply DNS, QUIC, and WebRTC protections.
verification	ProxyVerificationSettings | None	Optional egress verification.

Returns

Type	Description
ProxySettings	Validated manual proxy settings.

Examples

Use this public operation:

result = proxy_settings.manual()

classmethod pac(pac_url: str, *, username: str | None = None, password: str | None = None, bypass: Iterable[str] = (), verification: ProxyVerificationSettings | None = None) → ProxySettings

Create Proxy Auto-Configuration settings.

Parameters

Name	Type	Description
pac_url	str	URL of a PAC script.
username	str | None	Optional challenge username.
password	str | None	Optional challenge password.
bypass	Iterable[str]	Additional browser bypass patterns.
verification	ProxyVerificationSettings | None	Optional egress verification.

Returns

Type	Description
ProxySettings	Validated PAC settings.

Examples

Use this public operation:

result = proxy_settings.pac(pac_url)

classmethod system() → ProxySettings

Use operating-system proxy configuration.

Returns

Type	Description
ProxySettings	Validated settings in ProxyMode.SYSTEM mode with no explicit proxy endpoint.

Examples

Defer proxy selection to the operating system:

settings = ProxySettings.system()
assert settings.mode is ProxyMode.SYSTEM

classmethod direct() → ProxySettings

Force a direct connection and ignore system proxy settings.

Returns

Type	Description
ProxySettings	Validated settings in ProxyMode.DIRECT mode with no proxy endpoint.

Examples

Disable proxy use explicitly:

settings = ProxySettings.direct()
assert settings.mode is ProxyMode.DIRECT

classmethod managed(provider: ProxyProvider, location: Any, *, bypass: Iterable[str] = (), provider_options: Mapping[str, Any] | None = None, prevent_leaks: bool = True, verification: ProxyVerificationSettings | None = None) → ProxySettings

Create provider-backed proxy settings.

Parameters

Name	Type	Description
provider	ProxyProvider	Object implementing ProxyProvider.
location	Any	Provider-specific location descriptor.
bypass	Iterable[str]	Host patterns routed directly.
provider_options	Mapping[str, Any] | None	Options forwarded to provider.acquire.
prevent_leaks	bool	Apply DNS, QUIC, and WebRTC protections.
verification	ProxyVerificationSettings | None	Optional egress verification.

Returns

Type	Description
ProxySettings	Validated provider settings.

Examples

Use this public operation:

result = proxy_settings.managed(provider, location)

without_url_credentials() → ProxySettings

Return equivalent settings with credentials removed from URLs.

Explicit credentials are preserved in the dedicated fields so a BiDi authentication handler can answer proxy challenges.

Returns

Type	Description
ProxySettings	Sanitized proxy settings.

Examples

Use this public operation:

result = proxy_settings.without_url_credentials()

class ddp_utils.browser.backends.selenium.proxy.ProxyVerificationResult(ip: str | None, country_code: str | None, raw: Any)

Bases: object

Normalized result returned by the default proxy verifier.

Parameters

Name	Type	Description
ip	str | None	Observed egress IP.
country_code	str | None	Observed two-letter country code.
raw	Any	Parsed response payload or original text.

Examples

Use this public operation:

instance = ProxyVerificationResult()

class ddp_utils.browser.backends.selenium.proxy.ProxyVerificationSettings(url: str, expected_ip: str | None = None, expected_country_code: str | None = None, direct_ip: str | None = None, parser: Callable[[...], Any] | None = None)

Bases: object

Configure in-browser proxy egress verification.

Parameters

Name	Type	Description
url	str	Endpoint returning the browser’s observed IP/location.
expected_ip	str | None	Exact expected egress IP.
expected_country_code	str | None	Expected two-letter country code.
direct_ip	str | None	Known non-proxied IP that must not be observed.
parser	Callable[[...], Any] | None	Optional custom parser accepting body plus keyword context.

Examples

Use this public operation:

instance = ProxyVerificationSettings()

class ddp_utils.browser.backends.selenium.proxy.ResolvedProxy(settings: ProxySettings, lease: ProxyLease | None = None)

Bases: object

Proxy settings resolved after provider acquisition.

Parameters

Name	Type	Description
settings	ProxySettings	Concrete non-provider proxy settings.
lease	ProxyLease | None	Optional provider lease that must be closed with the session.

Examples

Use this public operation:

instance = ResolvedProxy()

ddp_utils.browser.backends.selenium.proxy.is_loopback_proxy(settings: ProxySettings) → bool

Return whether any configured endpoint resolves to loopback syntax.

Parameters

Name	Type	Description
settings	ProxySettings	Concrete proxy settings.

Returns

Type	Description
bool	True for localhost, loopback IPs, or loopback PAC hosts.

Examples

Use this public operation:

result = is_loopback_proxy(settings)

ddp_utils.browser.backends.selenium.proxy.normalize_proxy_url(value: str) → str

Normalize and validate a proxy URL.

Parameters

Name	Type	Description
value	str	Proxy endpoint with or without an explicit scheme.

Returns

Type	Description
str	URL containing a supported scheme, host, and port.

Raises

Exception	Description
ProxyConfigurationError	If the URL is malformed or unsupported.

Examples

Use this public operation:

result = normalize_proxy_url(value)

ddp_utils.browser.backends.selenium.proxy.parse_proxy_verification(body: str, **_context: Any) → ProxyVerificationResult

Parse common IP-check JSON or plain-text responses.

Parameters

Name	Type	Description
body	str	HTTP response body.
**_context	Any	Accepted for custom-parser signature compatibility.

Returns

Type	Description
ProxyVerificationResult	Normalized IP and country metadata.

Examples

Use this public operation:

result = parse_proxy_verification(body)

ddp_utils.browser.backends.selenium.proxy.proxy_url_credentials(url: str) → tuple[str | None, str | None]

Extract decoded credentials from a proxy URL.

Parameters

Name	Type	Description
url	str	Valid proxy URL.

Returns

Type	Description
tuple[str | None, str | None]	(username, password); both may be None.

Examples

Use this public operation:

result = proxy_url_credentials(url)

ddp_utils.browser.backends.selenium.proxy.proxy_url_with_credentials(url: str, username: str | None, password: str | None) → str

Insert URL-encoded credentials into a proxy URL.

Parameters

Name	Type	Description
url	str	Valid proxy URL.
username	str | None	Proxy username.
password	str | None	Proxy password.

Returns

Type	Description
str	Credential-bearing URL, or the original URL when username is absent.

Examples

Use this public operation:

result = proxy_url_with_credentials(url, username, password)

ddp_utils.browser.backends.selenium.proxy.resolve_proxy(settings: ProxySettings | None) → ResolvedProxy | None

Resolve provider-backed settings to a concrete fixed endpoint.

Parameters

Name	Type	Description
settings	ProxySettings | None	Optional proxy settings.

Returns

Type	Description
ResolvedProxy | None	Resolved settings, or None when no proxy policy is configured.

Examples

Use this public operation:

result = resolve_proxy(settings)

ddp_utils.browser.backends.selenium.proxy.strip_proxy_url_credentials(url: str) → str

Remove credentials from a proxy URL without changing its endpoint.

Parameters

Name	Type	Description
url	str	Valid proxy URL.

Returns

Type	Description
str	Sanitized URL.

Examples

Use this public operation:

result = strip_proxy_url_credentials(url)

ddp_utils.browser.backends.selenium.proxy.validate_proxy_verification(result: ProxyVerificationResult, settings: ProxyVerificationSettings) → ProxyVerificationResult

Validate normalized egress metadata against expectations.

Parameters

Name	Type	Description
result	ProxyVerificationResult	Parsed verification result.
settings	ProxyVerificationSettings	Expected IP/country/direct-IP constraints.

Returns

Type	Description
ProxyVerificationResult	The unchanged result.

Raises

Exception	Description
RuntimeError	If any expectation is violated.

Examples

Use this public operation:

result = validate_proxy_verification(result, settings)