ddp_utils.browser.backends.selenium.cloudflare¶

import ddp_utils.browser.backends.selenium.cloudflare

Passive Cloudflare challenge detection for ordinary Selenium drivers.

The helpers in this module observe known challenge markers and wait for them to clear. They do not click challenge widgets, solve CAPTCHAs, or bypass access controls.

class ddp_utils.browser.backends.selenium.cloudflare.CloudflareChallengeResult(detected: bool, signals: tuple[str, ...], title: str, error: str | None = None)¶

Bases: object

One passive Cloudflare detection snapshot.

Parameters

Name	Type	Description
detected	bool	Whether strong challenge evidence was found.
signals	tuple[str, ...]	Stable identifiers for the matched evidence.
title	str	Current document title when readable.
error	str \| None	WebDriver inspection error, if inspection failed.

Examples

Represent a detected challenge page:

result = CloudflareChallengeResult(
    detected=True,
    signals=("challenge_error",),
    title="Attention Required",
)

property challenge_error: bool¶

Return whether Cloudflare rendered an explicit challenge error.

Returns

True when signals contains challenge_error; otherwise False.

Examples

Inspect the normalized detection signals:

has_error = result.challenge_error

class ddp_utils.browser.backends.selenium.cloudflare.CloudflareWaitOutcome(value)¶

Bases: str, Enum

Terminal outcomes returned by wait_for_cloudflare_clear().

Examples

Use this public operation:

instance = CloudflareWaitOutcome()

class ddp_utils.browser.backends.selenium.cloudflare.CloudflareWaitResult(outcome: CloudflareWaitOutcome, elapsed: float, challenge_seen: bool, last_detection: CloudflareChallengeResult, last_error: str | None = None)¶

Bases: object

Result of waiting for a Cloudflare challenge to clear.

Parameters

Name	Type	Description
outcome	CloudflareWaitOutcome	Terminal wait condition.
elapsed	float	Monotonic elapsed seconds.
challenge_seen	bool	Whether a challenge was observed during the wait.
last_detection	CloudflareChallengeResult	Most recent detection snapshot.
last_error	str \| None	Most recent driver inspection error, if any.

Examples

Represent a challenge that cleared successfully:

detection = CloudflareChallengeResult(False, (), "Example Domain")
result = CloudflareWaitResult(
    outcome=CloudflareWaitOutcome.CLEARED,
    elapsed=1.5,
    challenge_seen=True,
    last_detection=detection,
)

property succeeded: bool¶

Return whether the challenge cleared or success content appeared.

Returns

True for CLEARED and SUCCESS_LOCATOR outcomes; otherwise False.

Examples

Check the terminal wait outcome:

assert result.succeeded

class ddp_utils.browser.backends.selenium.cloudflare.Locator(by: str, value: str)¶

Bases: object

Describe one raw Selenium locator used by provider-only helpers.

Parameters

Name	Type	Description
by	str	Selenium locator strategy, such as `css selector`.
value	str	Locator expression.

Examples

Wait for an application marker after an interstitial:

locator = Locator("css selector", "main[data-ready]")

classmethod css(value: str) → Locator¶

Create a CSS locator.

Parameters

Name	Type	Description
value	str	CSS selector.

Returns

Type	Description
Locator	Selenium CSS locator.

Examples

Target the application root:

locator = Locator.css("#app")

classmethod xpath(value: str) → Locator¶

Create an XPath locator.

Parameters

Name	Type	Description
value	str	XPath expression.

Returns

Type	Description
Locator	Selenium XPath locator.

Examples

Target a successful result:

locator = Locator.xpath("//main[@data-ready]")

classmethod text(value: str) → Locator¶

Create an exact-text XPath locator.

Parameters

Name	Type	Description
value	str	Exact visible text.

Returns

Type	Description
Locator	Selenium XPath locator with a safely quoted literal.

Examples

Target a Continue control:

locator = Locator.text("Continue")

ddp_utils.browser.backends.selenium.cloudflare.detect_cloudflare_challenge(driver: Any) → CloudflareChallengeResult¶

Inspect a WebDriver page for strong Cloudflare challenge indicators.

Parameters

Name	Type	Description
driver	Any	Active Selenium-compatible WebDriver.

Returns

Type	Description
CloudflareChallengeResult	Typed detection snapshot. Driver failures are reported through `error` instead of being mistaken for a challenge.

Examples

Use this public operation:

result = detect_cloudflare_challenge(driver)

ddp_utils.browser.backends.selenium.cloudflare.wait_for_cloudflare_clear(driver: Any, *, timeout: float = 120.0, poll_interval: float = 0.5, success_locator: Locator | None = None) → CloudflareWaitResult¶

Wait until a detected challenge clears or success content appears.

Parameters

Name	Type	Description
driver	Any	Active Selenium-compatible WebDriver.
timeout	float	Maximum wait in seconds; cannot be negative.
poll_interval	float	Positive polling interval in seconds.
success_locator	Locator \| None	Optional application-specific success marker.

Returns

Type	Description
CloudflareWaitResult	Structured terminal result without printing or swallowing state.

Raises

Exception	Description
ValueError	If timeout settings are invalid.

Examples

Use this public operation:

result = wait_for_cloudflare_clear(driver)