ddp_utils.browser.backends.selenium.middleware_wait

import ddp_utils.browser.backends.selenium.middleware_wait

Priority middleware scenarios for Selenium WebDriverWait.

class ddp_utils.browser.backends.selenium.middleware_wait.MiddlewareScenario(condition: Callable[[DriverT], Literal[False] | TriggerT], handler: Callable[[WaitMiddlewareContext[DriverT, TriggerT]], MiddlewareT], timeout: float = 10.0, name: str | None = None)

Bases: Generic[DriverT, TriggerT, MiddlewareT]

Describe a cheap trigger probe and its time-bounded handler.

condition must be a short, non-blocking probe. Its truthy return value activates handler and becomes context.trigger_value. The handler is allowed to perform a longer recovery flow, but is limited by timeout.

Examples

Use this public operation:

instance = MiddlewareScenario()

property resolved_name: str

Return an explicit name or a stable callable-derived fallback.

Returns

name when it is nonempty; otherwise the handler’s qualified name, simple name, or type name, in that order.

Examples

Prefer an explicitly configured diagnostic name:

scenario = MiddlewareScenario(
    condition=lambda driver: False,
    handler=lambda context: None,
    name="dismiss-cookie-banner",
)
assert scenario.resolved_name == "dismiss-cookie-banner"

exception ddp_utils.browser.backends.selenium.middleware_wait.MiddlewareTimeoutException(middleware: str, timeout: float, attempt: int)

Bases: TimeoutException

Indicate that a triggered middleware handler exceeded its own timeout.

Examples

Use this public operation:

instance = MiddlewareTimeoutException(middleware, timeout, attempt)

Create a timeout attributed only to one middleware scenario.

Parameters

Name	Type	Description
middleware	str	Name of the middleware scenario that exceeded its timeout.
timeout	float	Time limit of that scenario, in seconds.
attempt	int	Number of the handler attempt during which the limit was exceeded.

class ddp_utils.browser.backends.selenium.middleware_wait.MiddlewareWaitResult(value: ValueT, middleware_results: Tuple[WaitMiddlewareRecord, ...])

Bases: Generic[ValueT]

Combine the standard Selenium value with middleware scenario results.

Examples

Use this public operation:

instance = MiddlewareWaitResult()

class ddp_utils.browser.backends.selenium.middleware_wait.MiddlewareWebDriverWait(driver: DriverT, timeout: float, poll_frequency: float = 0.5, ignored_exceptions: Iterable[type[Exception]] | None = None, *, middlewares: Iterable[MiddlewareScenario[DriverT, Any, Any]] = ())

Bases: WebDriverWait[DriverT]

Run priority middleware scenarios before Selenium’s main condition.

Each polling cycle probes scenarios in registration order. Triggered handlers finish before the main condition is evaluated. Successful handler time is excluded from the main WebDriverWait timeout. A handler exceeding its own limit raises MiddlewareTimeoutException; the standard TimeoutException remains reserved for the main condition only.

With no scenarios configured, both methods delegate directly to Selenium.

Examples

Use this public operation:

instance = MiddlewareWebDriverWait(driver, timeout)

Initialize the main wait and validate middleware scenarios.

Parameters

Name	Type	Description
driver	DriverT	WebDriver instance passed to the wait conditions.
timeout	float	Maximum time to wait for the main condition, in seconds.
poll_frequency	float	Seconds between polling cycles.
ignored_exceptions	Optional[Iterable[type[Exception]]]	Exception types ignored while the main condition is polled.
middlewares	Iterable[MiddlewareScenario[DriverT, Any, Any]]	Scenarios registered immediately, in priority order.

use(middleware: MiddlewareScenario[DriverT, Any, Any]) → MiddlewareWebDriverWait[DriverT]

Register a middleware scenario and return this wait instance.

Parameters

Name	Type	Description
middleware	MiddlewareScenario[DriverT, Any, Any]	Validated scenario appended after existing scenarios.

Returns

Type	Description
MiddlewareWebDriverWait[DriverT]	This wait instance, enabling fluent scenario registration.

Raises

Exception	Description
TypeError	middleware is not a MiddlewareScenario.

Examples

Register a non-triggering scenario:

wait = MiddlewareWebDriverWait(object(), 1.0)
scenario = MiddlewareScenario(
    condition=lambda driver: False,
    handler=lambda context: None,
)
assert wait.use(scenario) is wait

property middlewares: Tuple[MiddlewareScenario[DriverT, Any, Any], ...]

Return an immutable snapshot of configured middleware scenarios.

Returns

Registered scenarios in evaluation order. Later registrations do not mutate a previously returned tuple.

Examples

Read the registration order:

configured = wait.middlewares
assert configured == (scenario,)

until(method: Callable[[DriverT], Literal[False] | ValueT], message: str = '') → ValueT | MiddlewareWaitResult[ValueT]

Wait for a truthy main condition after handling middleware scenarios.

Parameters

Name	Type	Description
method	Callable[[DriverT], Literal[False] | ~ddp_utils.browser.backends.selenium.middleware_wait.ValueT]	Polling callable receiving the driver and returning either a truthy result or literal False.
message	str	Optional text included in the main timeout exception.

Returns

Type	Description
ValueT | MiddlewareWaitResult[ValueT]	The main condition’s truthy value when no middleware ran; otherwise a result containing that value and all completed middleware records.

Raises

Exception	Description
MiddlewareTimeoutException	A triggered handler exceeds its own timeout.
selenium.common.exceptions.TimeoutException	The main condition does not become truthy before its adjusted deadline.

Examples

Return immediately when the condition is already true:

wait = MiddlewareWebDriverWait(object(), 1.0)
assert wait.until(lambda driver: "ready") == "ready"

until_not(method: Callable[[DriverT], ValueT], message: str = '') → ValueT | Literal[True] | MiddlewareWaitResult[ValueT | Literal[True]]

Wait for a falsy main condition after handling middleware scenarios.

Parameters

Name	Type	Description
method	Callable[[DriverT], ValueT]	Polling callable receiving the driver. Waiting succeeds when its value becomes falsy.
message	str	Optional text included in the main timeout exception.

Returns

Type	Description
ValueT | Literal[True] | ~ddp_utils.browser.backends.selenium.middleware_wait.MiddlewareWaitResult[~ddp_utils.browser.backends.selenium.middleware_wait.ValueT | ~typing.Literal[True]]	The falsy condition value, or True when an ignored exception signals success. When middleware ran, the value and completed middleware records are wrapped in MiddlewareWaitResult.

Raises

Exception	Description
MiddlewareTimeoutException	A triggered handler exceeds its own timeout.
selenium.common.exceptions.TimeoutException	The main condition does not become falsy before its adjusted deadline.

Examples

Return when the condition is already false:

wait = MiddlewareWebDriverWait(object(), 1.0)
assert wait.until_not(lambda driver: False) is False

class ddp_utils.browser.backends.selenium.middleware_wait.WaitMiddlewareContext(driver: DriverT, mode: Literal['until', 'until_not'], attempt: int, trigger_value: TriggerT, main_elapsed: float, cancel_event: Event, middleware_timeout: float)

Bases: Generic[DriverT, TriggerT]

Context passed to a triggered middleware scenario handler.

Examples

Use this public operation:

instance = WaitMiddlewareContext()

property cancelled: bool

Return whether the middleware deadline has requested cancellation.

Returns

The current state of the context’s cancellation event.

Examples

Inspect cancellation without mutating the event:

assert context.cancelled is False

class ddp_utils.browser.backends.selenium.middleware_wait.WaitMiddlewareRecord(middleware: str, value: Any, trigger_value: Any, attempt: int, duration: float)

Bases: object

Result and timing of one completed middleware scenario.

Examples

Use this public operation:

instance = WaitMiddlewareRecord()