ddp_utils.browser.backends.base¶

import ddp_utils.browser.backends.base

Abstract contracts implemented by every browser backend.

class ddp_utils.browser.backends.base.BackendSession(*args, **kwargs)¶

Bases: Protocol

Minimum lifecycle exposed by a concrete backend session.

Examples

Close a backend session without knowing its technology:

if not session.closed:
    session.close()

property descriptor: BackendDescriptor¶

Return the immutable descriptor for this backend session.

Returns

Backend identity and capability descriptor.

Examples

Inspect the concrete provider selected by configuration:

print(session.descriptor.provider)

property native: Any¶

Return the explicit backend-native escape-hatch object.

Returns

Native driver, page, process handle, or backend session object.

Examples

Use a backend-specific operation intentionally:

native = session.native

property closed: bool¶

Return whether this backend session is closed.

Returns

True after owned resources have been released.

Examples

Avoid scheduling work on a closed session:

if session.closed:
    return

close() → None¶

Release every resource owned by this backend session exactly once.

Examples

Close explicitly when a context manager is not used:

session.close()

class ddp_utils.browser.backends.base.BrowserBackend¶

Bases: ABC

Technology adapter that creates backend sessions for validated config.

Examples

Backend selection remains outside business logic:

backend = registry.resolve(config)
session = backend.start(config)

abstract property descriptor: BackendDescriptor¶

Return static backend identity and potential capabilities.

Returns

Descriptor for this backend implementation.

Examples

Display the selected concrete provider:

print(backend.descriptor.provider)

capability(capability: BrowserCapability | str) → CapabilityResult[BrowserCapability]¶

Return a structured capability result for this backend.

Parameters

Name	Type	Description
capability	BrowserCapability \| str	Capability enum or normalized name.

Returns

Type	Description
CapabilityResult[BrowserCapability]	Supported result containing the normalized capability, or an unsupported result with remediation context.

Raises

Exception	Description
BrowserConfigurationError	The capability name is unknown.

Examples

Check CDP support without raising:

result = backend.capability("cdp")
if not result.supported:
    print(result.reason)

abstractmethod start(config: BrowserConfig) → BackendSession¶

Create or attach a concrete backend session.

Parameters

Name	Type	Description
config	BrowserConfig	Validated neutral browser configuration.

Returns

Type	Description
BackendSession	Started backend session owning its lifecycle resources.

Raises

Exception	Description
BrowserConfigurationError	The config does not target this backend.
BrowserStartupError	Startup or attachment fails.

Examples

Start a selected backend with validated project configuration:

session = backend.start(config)