ddp_utils.browser.errors¶

import ddp_utils.browser.errors

Typed errors for backend-neutral browser automation.

exception ddp_utils.browser.errors.BrowserError¶

Bases: RuntimeError

Base error for browser facade failures.

Examples

Catch every browser-specific failure at a process boundary:

try:
    run_browser_workflow()
except BrowserError as error:
    report_failure(error)

exception ddp_utils.browser.errors.BrowserConfigurationError¶

Bases: BrowserError, ValueError

Report an invalid or contradictory browser configuration.

Examples

BrowserConfig.validate() raises this error for attach mode without an endpoint:

try:
    config.validate()
except BrowserConfigurationError as error:
    print(error)

exception ddp_utils.browser.errors.BrowserStartupError¶

Bases: BrowserError

Report a failure while creating or attaching to a browser session.

Examples

Surface a launch failure without exposing a backend exception:

raise BrowserStartupError("Chrome did not become ready")

exception ddp_utils.browser.errors.BrowserClosedError¶

Bases: BrowserError

Report an operation attempted after the session was closed.

Examples

A facade method raises this error instead of using stale native state:

if session.closed:
    raise BrowserClosedError("browser session is closed")

exception ddp_utils.browser.errors.UnsupportedCapabilityError(capability: str, *, backend: str, reason: str, details: dict[str, Any] | None = None)¶

Bases: BrowserError

Report a required capability that the active backend cannot provide.

Parameters

Name	Type	Description
capability	str	Stable capability identifier.
backend	str	Active backend identifier.
reason	str	Human-readable explanation of the limitation.
details	dict[str, Any] \| None	Optional structured diagnostic details.

Examples

Require CDP while using a backend that does not expose it:

raise UnsupportedCapabilityError(
    "cdp",
    backend="native",
    reason="Native process mode has no automation protocol.",
)

Initialize a capability failure.

Parameters

Name	Type	Description
capability	str	Stable capability identifier.
backend	str	Active backend identifier.
reason	str	Human-readable explanation of the limitation.
details	dict[str, Any] \| None	Optional structured diagnostic details.

Examples

Create a structured native-backend error:

error = UnsupportedCapabilityError(
    "dom",
    backend="native",
    reason="Attach through Selenium or Playwright first.",
)

exception ddp_utils.browser.errors.ElementActionError¶

Bases: BrowserError

Report an element action whose documented postcondition was not met.

Examples

Fail when show() cannot make an attached element visible:

raise ElementActionError("element remained hidden after show()")

exception ddp_utils.browser.errors.WaitTimeoutError¶

Bases: BrowserError, TimeoutError

Report a facade wait condition that exceeded its timeout budget.

Examples

Raise a typed timeout with the failed condition:

raise WaitTimeoutError("element did not become clickable")

exception ddp_utils.browser.errors.DownloadError¶

Bases: BrowserError

Base error for download lifecycle and durable-file failures.

Examples

Catch every download-specific failure:

try:
    download.wait_complete(timeout=60)
except DownloadError as error:
    preserve_diagnostics(error)

exception ddp_utils.browser.errors.DownloadTimeoutError¶

Bases: DownloadError, TimeoutError

Report a download that did not start or complete before its deadline.

Examples

Signal that no matching download started:

raise DownloadTimeoutError("download did not start within 30 seconds")

exception ddp_utils.browser.errors.DownloadFailedError¶

Bases: DownloadError

Report a browser or filesystem download failure.

Examples

Preserve a backend failure reason:

raise DownloadFailedError("server cancelled the download")

exception ddp_utils.browser.errors.BlobAccessError¶

Bases: DownloadError

Report blob data that cannot be accessed in its owning page or frame.

Examples

Fail after navigation revoked a blob URL:

raise BlobAccessError("blob URL is no longer valid")

exception ddp_utils.browser.errors.BlobValidationError¶

Bases: DownloadError

Report blob content that does not satisfy the requested validation.

Examples

Reject an HTML error page returned instead of a PDF:

raise BlobValidationError("payload does not start with %PDF-")