ddp_utils.browser.config¶

import ddp_utils.browser.config

Normalized configuration for managed, attached, and native browsers.

class ddp_utils.browser.config.BrowserTimeouts(startup: float = 60.0, navigation: float = 30.0, action: float = 10.0, condition: float = 10.0, download: float = 120.0, script: float = 30.0)¶

Bases: object

Timeout budgets shared by browser facade operations.

Parameters

Name	Type	Description
startup	float	Maximum browser startup or attach time in seconds.
navigation	float	Maximum navigation time in seconds.
action	float	Default actionability and action time in seconds.
condition	float	Default explicit condition wait in seconds.
download	float	Default download lifecycle time in seconds.
script	float	Maximum asynchronous JavaScript time in seconds.

Examples

Increase only the download budget:

timeouts = BrowserTimeouts(download=180)

validate() → None¶

Validate that every timeout is finite and non-negative.

Raises

Exception	Description
BrowserConfigurationError	A timeout is negative or not finite.

Examples

Validate user-supplied timeout settings before backend selection:

BrowserTimeouts(action=5).validate()

class ddp_utils.browser.config.BrowserConfig(technology: BrowserTechnology | None = BrowserTechnology.SELENIUM, browser: BrowserProduct = BrowserProduct.CHROME, identity_mode: IdentityMode = IdentityMode.STANDARD, launch_mode: LaunchMode = LaunchMode.MANAGED, headless: bool = False, user_data_dir: Path | None = None, profile_name: str | None = None, downloads_dir: Path | None = None, attach_endpoint: str | None = None, extensions: tuple[~pathlib.Path, ...]=(), timeouts: BrowserTimeouts = <factory>, natural: NaturalIdentitySettings = <factory>, proxy_controller: Any | None = None, network: NetworkCaptureSettings = <factory>, options: dict[str, ~typing.Any]=<factory>)¶

Bases: object

Resolve project configuration into one browser launch contract.

Parameters

Name	Type	Description
technology	BrowserTechnology \| None	Selenium or Playwright automation technology. It is `None` only for native process mode.
browser	BrowserProduct	Requested browser product.
identity_mode	IdentityMode	Standard or coherent natural identity policy.
launch_mode	LaunchMode	Managed, attached, or native process mode.
headless	bool	Whether a managed automation session should be headless.
user_data_dir	Path \| None	Optional browser profile root.
profile_name	str \| None	Optional named profile within `user_data_dir`.
downloads_dir	Path \| None	Dedicated session download directory.
attach_endpoint	str \| None	Remote-debugging or automation endpoint for attach mode.
extensions	tuple[Path, ...]	Extension paths prepared before browser startup.
timeouts	BrowserTimeouts	Facade timeout budgets.
natural	NaturalIdentitySettings	Defaults applied only to a supported natural identity.
proxy_controller	Any \| None	Optional runtime controller that can verify, rotate, and release an already configured proxy allocation.
network	NetworkCaptureSettings	Session-owned network capture configuration.
options	dict[str, Any]	Backend-specific options that have no neutral contract yet.

Examples

Request a natural Camoufox session:

config = BrowserConfig(
    technology=BrowserTechnology.PLAYWRIGHT,
    browser=BrowserProduct.FIREFOX,
    identity_mode=IdentityMode.NATURAL,
)

classmethod from_mapping(values: Mapping[str, Any]) → BrowserConfig¶

Create normalized configuration from case-insensitive mapping keys.

Parameters

Name	Type	Description
values	Mapping[str, Any]	Configuration values. Keys are normalized to lowercase and spaces become underscores. `technology=native` is accepted as shorthand for native launch mode without an automation technology.

Returns

Type	Description
BrowserConfig	Validated browser configuration.

Raises

Exception	Description
BrowserConfigurationError	A value is invalid or contradictory.

Examples

Build configuration from a manifest section:

config = BrowserConfig.from_mapping(
    {
        "TECHNOLOGY": "playwright",
        "BROWSER": "firefox",
        "IDENTITY_MODE": "natural",
    }
)

property provider: str¶

Return the concrete provider selected by the neutral configuration.

Returns

native, camoufox, seleniumbase, selenium, or playwright.

Examples

Resolve Playwright natural Firefox to Camoufox:

assert config.provider == "camoufox"

property warnings: tuple[str, ...]¶

Return non-fatal configuration limitations.

Returns

Stable human-readable warnings. An empty tuple means no known limitation was detected.

Examples

Display a warning when natural Chromium is requested through plain Playwright:

for warning in config.warnings:
    print(warning)

property identity_profile: BrowserIdentityProfile¶

Return effective provider identity metadata before startup.

Returns

Immutable resolved profile with honest fidelity and limitations.

Examples

Report whether natural mode is full or best-effort:

print(config.identity_profile.fidelity)

resolve_identity() → BrowserConfig¶

Return a launch-ready copy with provider-scoped identity defaults.

Returns

Type	Description
BrowserConfig	Validated detached configuration ready for backend selection.

Raises

Exception	Description
BrowserConfigurationError	Natural persistent identity is incomplete or contradictory.

Examples

Resolve Camoufox options once at the factory boundary:

resolved = config.resolve_identity()
assert resolved.options["camoufox_options"]["geoip"] is True

validate() → None¶

Validate cross-field browser configuration invariants.

Raises

Exception	Description
BrowserConfigurationError	Fields contradict the selected launch mode or a timeout is invalid.

Examples

Validate configuration before selecting a backend:

config.validate()

with_overrides(**overrides: Any) → BrowserConfig¶

Return a validated copy with explicit runtime overrides.

Parameters

Name	Type	Description
**overrides	Any	Dataclass fields to replace for this process.

Returns

Type	Description
BrowserConfig	New validated browser configuration.

Raises

Exception	Description
BrowserConfigurationError	The resulting configuration is invalid.
TypeError	An override name is not a configuration field.

Examples

Enable headless mode for one launch only:

headless_config = config.with_overrides(headless=True)