ddp_utils.browser.facade.extensions¶

import ddp_utils.browser.facade.extensions

Backend-neutral browser extension inventory and lifecycle service.

class ddp_utils.browser.facade.extensions.BrowserExtension(identifier: str, name: str, path: Path | None = None, enabled: bool | None = None, state: str = 'configured', source: str = 'configuration')¶

Bases: object

Describe one configured or runtime-installed browser extension.

Parameters

Name	Type	Description
identifier	str	Provider identifier when known, otherwise stable path text.
name	str	Human-readable extension name.
path	Path \| None	Source path when the extension was loaded from disk.
enabled	bool \| None	Known enabled state, or `None` when the provider cannot tell.
state	str	`configured`, `installed`, `disabled`, or `removed`.
source	str	Discovery source such as `configuration` or `runtime`.

Examples

Inspect a configured extension without claiming browser verification:

print(extension.state, extension.enabled)

class ddp_utils.browser.facade.extensions.BrowserExtensions(browser: Browser)¶

Bases: object

Manage extension state without hiding provider restrictions.

Parameters

Name	Type	Description
browser	Browser	Owning browser facade.

Note

Chromium extensions normally must be supplied before startup. Selenium Firefox alone exposes a portable runtime install/uninstall operation.

Examples

Inspect startup extensions uniformly:

for extension in browser.extensions.list():
    print(extension.name, extension.state)

Bind extension inventory to one browser lifecycle.

Parameters

Name	Type	Description
browser	Browser	Owning browser facade.

Examples

Browser constructs this service once:

extensions = BrowserExtensions(browser)

property available: bool¶

Return whether this backend accepts browser extensions.

Returns

True when extensions are a declared backend capability.

Examples

Guard an optional extension workflow:

if browser.extensions.available:
    inspect_extensions()

list() → tuple[BrowserExtension, ...]¶

Return known extensions in stable insertion order.

Returns

Type	Description
tuple[BrowserExtension, …]	Configured and runtime-installed extension descriptions.

Examples

Record extension inventory:

inventory = browser.extensions.list()

get(id_or_name: str) → BrowserExtension | None¶

Find one extension by identifier, name, or source path.

Parameters

Name	Type	Description
id_or_name	str	Provider identifier, display name, or path.

Returns

Type	Description
BrowserExtension \| None	Matching extension or `None`.

Examples

Resolve a configured VPN extension:

vpn = browser.extensions.get("Windscribe")

install(path: str | Path, *, required: bool = False, restart: bool = False) → CapabilityResult[BrowserExtension]¶

Install an extension when the live provider supports it.

Parameters

Name	Type	Description
path	str \| Path	Extension package or unpacked extension path.
required	bool	Raise when runtime installation is unsupported.
restart	bool	Permit a provider/controller to require restart. The built-in facade never restarts an owned session implicitly.

Returns

Type	Description
CapabilityResult[BrowserExtension]	Supported result containing the installed extension, or a precise soft unsupported result.

Raises

Exception	Description
BrowserError	Source does not exist or provider installation fails.
UnsupportedCapabilityError	Installation is required but absent.

Examples

Install a temporary Firefox add-on:

result = browser.extensions.install("helper.xpi", required=True)

remove(id_or_name: str, *, required: bool = False) → CapabilityResult[bool]¶

Remove a runtime-installed extension when supported.

Parameters

Name	Type	Description
id_or_name	str	Extension identifier or name.
required	bool	Raise when removal is unsupported or the item is absent.

Returns

Type	Description
CapabilityResult[bool]	Supported result with `True` after removal, or soft unsupported.

Raises

Exception	Description
BrowserError	If the extension cannot be removed.

Examples

Remove a temporary Firefox extension:

browser.extensions.remove(extension.identifier)

enable(id_or_name: str) → CapabilityResult[bool]¶

Enable an extension when the provider exposes a live control.

Parameters

Name	Type	Description
id_or_name	str	Extension identifier or name.

Returns

Type	Description
CapabilityResult[bool]	Soft unsupported result for current standard providers.

Examples

Attempt optional live enabling:

result = browser.extensions.enable("helper")

disable(id_or_name: str) → CapabilityResult[bool]¶

Disable an extension when the provider exposes a live control.

Parameters

Name	Type	Description
id_or_name	str	Extension identifier or name.

Returns

Type	Description
CapabilityResult[bool]	Soft unsupported result for current standard providers.

Examples

Attempt optional live disabling:

result = browser.extensions.disable("helper")

reload(id_or_name: str) → CapabilityResult[bool]¶

Reload an extension when a provider-specific controller exists.

Parameters

Name	Type	Description
id_or_name	str	Extension identifier or name.

Returns

Type	Description
CapabilityResult[bool]	Soft unsupported result for current standard providers.

Examples

Attempt optional extension reload:

browser.extensions.reload("helper")

verify(id_or_name: str, *, timeout: float | None = None) → ExtensionVerification¶

Return honest presence and runtime-verification evidence.

Parameters

Name	Type	Description
id_or_name	str	Extension identifier or name.
timeout	float \| None	Reserved verification deadline for provider controllers.

Returns

Type	Description
ExtensionVerification	Verification record. Startup configuration alone is marked present but not runtime verified.

Examples

Distinguish configuration from proven installation:

status = browser.extensions.verify("helper")
assert status.present

class ddp_utils.browser.facade.extensions.ExtensionVerification(extension: BrowserExtension | None, present: bool, enabled: bool | None, verified: bool, reason: str | None = None)¶

Bases: object

Report whether an extension is present and operationally verified.

Parameters

Name	Type	Description
extension	BrowserExtension \| None	Resolved extension description, when found.
present	bool	Whether the facade has evidence that it is present.
enabled	bool \| None	Known enabled state, or `None` when unknowable.
verified	bool	Whether the active provider verified runtime installation.
reason	str \| None	Honest explanation of incomplete verification.

Examples

Require runtime evidence before relying on an extension:

status = browser.extensions.verify("vpn")
if not status.verified:
    print(status.reason)