ddp_utils.browser.profile

import ddp_utils.browser.profile

Own browser identity, persistent profiles, and safe profile copying.

class ddp_utils.browser.profile.BrowserIdentityProfile(requested_mode: IdentityMode, effective_mode: IdentityMode, name: str, provider: str, fidelity: str, uses_uc: bool, limitations: tuple[str, ...] = ())

Bases: object

Describe the effective identity implementation for one configuration.

Parameters

Name	Type	Description
requested_mode	IdentityMode	Identity mode requested by the project.
effective_mode	IdentityMode	Identity mode actually provided by the backend.
name	str	Stable diagnostic profile name.
provider	str	Concrete provider selected for the profile.
fidelity	str	standard, uc, best_effort, natural, or fallback_standard.
uses_uc	bool	Whether SeleniumBase UC mode is available and selected.
limitations	tuple[str, ...]	Honest limitations of this browser combination.

Examples

Inspect the provider before startup:

assert profile.provider in {"seleniumbase", "camoufox"}

class ddp_utils.browser.profile.ChromiumProfile(browser: str, user_data_dir: Path, profile_directory: str = 'Default', unpacked_extensions: tuple[Path, ...] = (), generated: bool = False, copy_report: ChromiumProfileCopyReport | None = None)

Bases: object

Describe one Chromium user-data directory and profile subdirectory.

Variables

Name	Type	Description
browser	str	Normalized Chromium product name.
user_data_dir	pathlib.Path	Absolute root containing the product’s profile data.
profile_directory	str	Profile subdirectory name, or . when the root itself is the profile directory.
unpacked_extensions	tuple[pathlib.Path, ...]	Absolute unpacked-extension directories associated with this profile.
generated	bool	Whether the profile was created or reopened through this API.
copy_report	ChromiumProfileCopyReport | None	Optional report describing data copied into a generated profile. None means no copy report is available.

Examples

Describe an existing profile location without opening Chromium:

from pathlib import Path

from ddp_utils.browser.profile import ChromiumProfile

profile = ChromiumProfile(
    browser="chrome",
    user_data_dir=Path("profiles/chrome"),
    profile_directory="Default",
)

property profile_path: Path

Return the concrete profile directory inside the user-data root.

Returns

The absolute user-data root when profile_directory is .; otherwise that root joined with the configured subdirectory name.

Examples

Resolve the selected profile directory:

path = profile.profile_path

property is_system_default: bool

Return whether this object points at the product’s standard data root.

Returns

True when user_data_dir equals the platform-specific default for the configured browser; otherwise False.

Examples

Check whether profile data uses the browser’s default root:

uses_default_root = profile.is_system_default

ensure_closed() → None

Fail conservatively when the selected browser profile may be in use.

Raises

Exception	Description
ChromiumProfileError	If the browser appears to be running with this profile.

Examples

Use this public operation:

result = chromium_profile.ensure_closed()

classmethod default(browser: str, *, profile_directory: str | None = None) → ChromiumProfile

Describe the browser’s platform-default user-data directory.

This operation computes paths only; it does not create directories or start a browser process.

Parameters

Name	Type	Description
browser	str	Supported Chromium product name or recognized Chrome or Edge alias.
profile_directory	str | None	Profile subdirectory name. None selects the product’s default profile directory.

Returns

Type	Description
ChromiumProfile	A normalized profile descriptor for the current platform.

Raises

Exception	Description
ValueError	browser is empty or profile_directory is not one directory name.
KeyError	The normalized browser product is unsupported.

Examples

Describe Chrome’s standard default profile:

from ddp_utils.browser.profile import ChromiumProfile

profile = ChromiumProfile.default("chrome")

classmethod minimal(browser: str, destination: Path | str, *, profile_directory: str | None = None, source: ChromiumProfile | None = None, copy: ChromiumProfileCopyOptions | None = None, unpacked_extensions: Sequence[Path | str] = ()) → ChromiumProfile

Create a new minimal profile and optionally seed selected data.

The destination must be absent or empty. Existing files are never overwritten. The source browser profile must be completely closed. Data is assembled in a temporary staging directory and then moved into the destination; filesystem failures may therefore leave a partially moved destination, but existing destination content is never deleted.

Parameters

Name	Type	Description
browser	str	Supported Chromium product name or recognized alias.
destination	Path | str	New or empty user-data directory to populate.
profile_directory	str | None	Destination profile subdirectory. None uses the product default.
source	ChromiumProfile | None	Optional closed source profile. None selects the system default profile only when copy requests source data.
copy	ChromiumProfileCopyOptions | None	Optional data-selection policy. None uses the default policy, which creates an empty minimal profile.
unpacked_extensions	Sequence[Path | str]	Additional unpacked-extension directories to validate and associate with the result.

Returns

Type	Description
ChromiumProfile	A generated profile descriptor whose copy_report records copied, missing, and warned-about entries and discovered extensions.

Raises

Exception	Description
ChromiumProfileError	Source and destination browsers differ, the source is missing or may be open, the destination lies inside the source, or the destination is not an empty directory.
ValueError	A browser or profile-directory value is invalid.
FileNotFoundError	A requested unpacked extension or selected source entry does not exist.
OSError	Directory creation, copying, validation, or the final move fails.

Examples

Create an empty disposable Chrome profile:

from pathlib import Path
from tempfile import TemporaryDirectory

from ddp_utils.browser.profile import ChromiumProfile

with TemporaryDirectory() as directory:
    profile = ChromiumProfile.minimal(
        "chrome",
        Path(directory, "profile"),
    )
    assert profile.generated

classmethod existing(browser: str, user_data_dir: Path | str, *, profile_directory: str | None = None) → ChromiumProfile

Open a generated profile and rediscover its copied unpacked extensions.

This operation validates the root and inspects its Unpacked Extensions directory. It does not start Chromium or verify that the profile is closed.

Parameters

Name	Type	Description
browser	str	Supported Chromium product name or recognized alias.
user_data_dir	Path | str	Existing user-data root to describe.
profile_directory	str | None	Profile subdirectory name. None uses the product default.

Returns

Type	Description
ChromiumProfile	A generated profile descriptor containing each valid unpacked extension discovered below the user-data root.

Raises

Exception	Description
ChromiumProfileError	user_data_dir is not an existing directory.
ValueError	The browser is empty or the profile directory is invalid.

Examples

Reopen a previously generated profile:

from tempfile import TemporaryDirectory

from ddp_utils.browser.profile import ChromiumProfile

with TemporaryDirectory() as directory:
    profile = ChromiumProfile.existing("chrome", directory)
    assert profile.generated

class ddp_utils.browser.profile.ChromiumProfileCopyOptions(cookies: bool = False, site_data: bool = False, local_storage: bool = False, session_storage: bool = False, indexed_db: bool = False, service_worker_storage: bool = False, cache: bool = False, history: bool = False, download_history: bool = False, bookmarks: bool = False, favicons: bool = False, saved_passwords: bool = False, autofill: bool = False, sessions: bool = False, site_settings: bool = False, extension_ids: tuple[str, ...] = (), copy_unpacked_extension_sources: bool = False, shared_extension_storage: bool = False)

Bases: object

Select data copied from a closed source profile.

history and download_history must have the same value because Chromium stores both in the same versioned SQLite History database. Extension-local data can be selected by ID. Shared extension stores are excluded unless shared_extension_storage is explicitly enabled.

Examples

Use this public operation:

instance = ChromiumProfileCopyOptions()

class ddp_utils.browser.profile.ChromiumProfileCopyReport(copied: tuple[str, ...], missing: tuple[str, ...], warnings: tuple[str, ...], unpacked_extensions: tuple[Path, ...])

Bases: object

Report exactly what a minimal profile generator copied or skipped.

Examples

Use this public operation:

instance = ChromiumProfileCopyReport()

exception ddp_utils.browser.profile.ChromiumProfileError

Bases: RuntimeError

Describe an unsafe or unsupported Chromium profile operation.

Examples

Use this public operation:

instance = ChromiumProfileError()

class ddp_utils.browser.profile.IdentityResolution(profile: BrowserIdentityProfile, options: dict[str, Any], user_data_dir: Path | None, normalized_fields: tuple[str, ...] = ())

Bases: object

Contain resolved identity metadata and launch inputs.

Parameters

Name	Type	Description
profile	BrowserIdentityProfile	Effective immutable identity profile.
options	dict[str, Any]	Provider options after safe profile defaults.
user_data_dir	Path | None	Effective profile directory.
normalized_fields	tuple[str, ...]	Explicit fields removed to preserve coherence.

Examples

Apply the resolution once at the factory boundary:

config = config.with_overrides(
    options=resolution.options,
    user_data_dir=resolution.user_data_dir,
)

class ddp_utils.browser.profile.NaturalIdentitySettings(identity: str = 'rotating', humanize: bool = True, geoip: bool = True, os: str = 'host', block_webrtc: bool = False, enable_cache: bool = True, persistent: bool = False, profile_id: str | None = None, profile_dir: Path | None = None, allow_identity_overrides: bool = False)

Bases: object

Define defaults used only by a natural browser identity.

Parameters

Name	Type	Description
identity	str	rotating for an isolated identity per launch or persistent for an explicitly named reusable profile.
humanize	bool	Ask a supporting provider to humanize low-level interaction.
geoip	bool	Derive geolocation-sensitive identity from the active proxy.
os	str	host, windows, macos, or linux fingerprint family.
block_webrtc	bool	Block WebRTC instead of allowing a proxy-coherent route.
enable_cache	bool	Preserve normal browser cache behavior.
persistent	bool	Force persistent mode even when identity is rotating.
profile_id	str | None	Stable project-owned identity identifier.
profile_dir	Path | None	Directory used by a persistent natural profile.
allow_identity_overrides	bool	Preserve explicit locale, User-Agent, timezone, and geolocation overrides even when they may conflict with proxy-derived identity.

Examples

Configure an isolated Camoufox identity:

settings = NaturalIdentitySettings(geoip=True, humanize=True)

classmethod from_mapping(values: Mapping[str, Any] | None) → NaturalIdentitySettings

Create strict natural settings from normalized project values.

Parameters

Name	Type	Description
values	Mapping[str, Any] | None	Mapping using names with or without the natural_ prefix.

Returns

Type	Description
NaturalIdentitySettings	Validated immutable settings.

Raises

Exception	Description
BrowserConfigurationError	A key or value is unsupported.

Examples

Parse manifest-style flat keys:

settings = NaturalIdentitySettings.from_mapping(
    {"natural_identity": "rotating", "natural_geoip": True}
)

property resolved_os: str

Return the concrete operating-system fingerprint family.

Returns

windows, macos, or linux.

Examples

Resolve host before passing options to Camoufox:

family = settings.resolved_os

property is_persistent: bool

Return whether the identity must reuse a stable profile.

Returns

True for explicit or forced persistent mode.

Examples

Select storage ownership before browser startup:

if settings.is_persistent:
    preserve_profile()

validate() → None

Validate natural identity invariants without launching a browser.

Raises

Exception	Description
BrowserConfigurationError	A mode, OS, or persistent profile is incomplete.

Examples

Validate project values during configuration assembly:

settings.validate()

ddp_utils.browser.profile.apply_identity_profile(*, technology: BrowserTechnology | None, browser: BrowserProduct, mode: IdentityMode, settings: NaturalIdentitySettings, options: Mapping[str, Any], user_data_dir: Path | None) → IdentityResolution

Apply provider-scoped defaults without overriding explicit safe values.

Parameters

Name	Type	Description
technology	BrowserTechnology | None	Selenium, Playwright, or None.
browser	BrowserProduct	Requested browser product.
mode	IdentityMode	Requested identity mode.
settings	NaturalIdentitySettings	Natural identity defaults.
options	Mapping[str, Any]	Existing explicit provider options.
user_data_dir	Path | None	Existing browser profile directory.

Returns

Type	Description
IdentityResolution	Resolved profile, detached options, and effective profile directory.

Raises

Exception	Description
BrowserConfigurationError	Persistent natural identity is incomplete.

Examples

Prepare Camoufox defaults before provider construction:

resolution = apply_identity_profile(
    technology=BrowserTechnology.PLAYWRIGHT,
    browser=BrowserProduct.FIREFOX,
    mode=IdentityMode.NATURAL,
    settings=NaturalIdentitySettings(),
    options={},
    user_data_dir=None,
)

ddp_utils.browser.profile.resolve_identity_profile(technology: BrowserTechnology | None, browser: BrowserProduct, mode: IdentityMode) → BrowserIdentityProfile

Resolve identity metadata without mutating launch configuration.

Parameters

Name	Type	Description
technology	BrowserTechnology | None	Selenium, Playwright, or None for native mode.
browser	BrowserProduct	Requested browser product.
mode	IdentityMode	Requested standard or natural identity mode.

Returns

Type	Description
BrowserIdentityProfile	Effective provider profile.

Examples

Resolve natural Playwright Firefox to Camoufox:

profile = resolve_identity_profile(
    BrowserTechnology.PLAYWRIGHT,
    BrowserProduct.FIREFOX,
    IdentityMode.NATURAL,
)
assert profile.provider == "camoufox"