ddp_utils.browser.backends.selenium.extensions

import ddp_utils.browser.backends.selenium.extensions

Runtime WebExtension management for a managed browser session.

exception ddp_utils.browser.backends.selenium.extensions.ExtensionError

Bases: RuntimeError

A WebExtension could not be installed, removed, or contacted.

Examples

Use this public operation:

instance = ExtensionError()

class ddp_utils.browser.backends.selenium.extensions.ExtensionInfo(extension_id: str, target_type: str | None, title: str | None, url: str)

Bases: object

Describe an extension target visible to the browser.

Parameters

Name	Type	Description
extension_id	str	Browser extension identifier.
target_type	str | None	CDP target type such as service_worker.
title	str | None	Target title.
url	str	Extension target URL.

Examples

Use this public operation:

instance = ExtensionInfo()

class ddp_utils.browser.backends.selenium.extensions.ExtensionManager(driver: Any, *, browser: str)

Bases: object

Install, uninstall, discover, and message browser extensions.

Examples

Use this public operation:

instance = ExtensionManager(driver, browser)

Bind extension operations to one WebDriver.

Parameters

Name	Type	Description
driver	Any	Active Selenium WebDriver.
browser	str	Canonical browser name.

property is_chromium: bool

Return whether the browser uses the Chromium extension platform.

Returns

True for Chrome, Chromium, Edge, Brave, Opera, Comet, and Atlas; otherwise False.

Examples

Inspect a manager without contacting its driver:

manager = ExtensionManager(None, browser="chrome")
assert manager.is_chromium

property installed_ids: tuple[str, ...]

Return extension identifiers installed through this manager.

Returns

An immutable snapshot of identifiers in installation order. The tuple is empty until an installation succeeds.

Examples

Read the current installation snapshot:

manager = ExtensionManager(None, browser="chrome")
assert manager.installed_ids == ()

install(path: str | Path, *, temporary: bool = True) → str

Install an unpacked directory or packed extension at runtime.

Parameters

Name	Type	Description
path	str | Path	Extension directory, CRX, ZIP, or XPI path.
temporary	bool	Firefox temporary-install flag.

Returns

Type	Description
str	Installed extension identifier.

Raises

Exception	Description
FileNotFoundError	If path does not exist.
ExtensionError	If the browser exposes no runtime install API.

Examples

Use this public operation:

result = extension_manager.install(path)

install_all(paths: Iterable[str | Path], *, temporary: bool = True) → list[str]

Install multiple runtime extensions in order.

Parameters

Name	Type	Description
paths	Iterable[str | Path]	Extension directories or archives.
temporary	bool	Firefox temporary-install flag.

Returns

Type	Description
list[str]	Installed extension identifiers.

Examples

Use this public operation:

result = extension_manager.install_all(paths)

install_from_directory(directory: str | Path, *, recursive: bool = True, temporary: bool = True) → list[str]

Install each unpacked extension below a directory.

Parameters

Name	Type	Description
directory	str | Path	Root containing extension manifest.json files.
recursive	bool	Search nested directories.
temporary	bool	Firefox temporary-install flag.

Returns

Type	Description
list[str]	Installed extension identifiers.

Raises

Exception	Description
NotADirectoryError	If directory is invalid.

Examples

Use this public operation:

result = extension_manager.install_from_directory(directory)

uninstall(extension_id: str) → None

Uninstall an extension by identifier.

Parameters

Name	Type	Description
extension_id	str	Browser extension identifier.

Raises

Exception	Description
ExtensionError	If uninstall is unavailable or fails.

Examples

Use this public operation:

result = extension_manager.uninstall(extension_id)

discover_active() → list[ExtensionInfo]

Discover active Chromium extension targets through CDP.

Returns

Type	Description
list[ExtensionInfo]	Deduplicated extension target information.

Raises

Exception	Description
ExtensionError	If CDP target discovery is unavailable.

Examples

Use this public operation:

result = extension_manager.discover_active()

send_external_message(extension_id: str, message: Mapping[str, Any], *, timeout: float = 10.0) → Any

Send chrome.runtime.sendMessage from the current web page.

The target extension must declare the page origin in externally_connectable and register an external message listener.

Parameters

Name	Type	Description
extension_id	str	Target Chromium extension identifier.
message	Mapping[str, Any]	JSON-serializable message payload.
timeout	float	Selenium asynchronous-script timeout.

Returns

Type	Description
Any	Extension response.

Raises

Exception	Description
ExtensionError	If messaging is unsupported or fails.

Examples

Use this public operation:

result = extension_manager.send_external_message(extension_id, message)