botonomus.profiles¶

Persistent, exclusively owned profiles and opt-in warm-up.

botonomus.profiles ¶

Persistent, exclusively owned browser profiles, and opt-in profile warm-up.

PROFILE_NAME `module-attribute` ¶

PROFILE_NAME: Final = re.compile('[A-Za-z0-9][A-Za-z0-9_-]{0,63}')

Accepted profile names: 1-64 ASCII letters, digits, _ or -.

DEFAULT_SITES `module-attribute` ¶

DEFAULT_SITES: tuple[str, ...] = ('https://en.wikipedia.org/wiki/Main_Page', 'https://www.bbc.com/news', 'https://www.theguardian.com/international', 'https://www.reuters.com/', 'https://apnews.com/', 'https://weather.com/', 'https://www.accuweather.com/', 'https://www.amazon.com/', 'https://www.ebay.com/', 'https://www.imdb.com/', 'https://www.allrecipes.com/')

News, encyclopedia, weather, shopping and entertainment home pages.

ProfileLease ¶

ProfileLease(root: Path, name: str)

Exclusive ownership of one profile directory under root.

The lock lives in root/.locks and works across processes, so two managers can never drive the same profile. Redirected (symlinked or junctioned) directories are refused so a lease cannot be pointed at an unrelated location.

Parameters:

Name	Type	Description	Default
`root`	`Path`	Profile root directory.	required
`name`	`str`	Profile name; normalized to lowercase. Windows device names are refused.	required

Attributes:

Name	Type	Description
`name`		Normalized profile name.
`root`		Resolved profile root.
`path`		The profile directory, `root / name`.

Raises:

Type	Description
`ConfigurationError`	For an invalid or reserved name.

held `property` ¶

held: bool

Whether this lease currently owns the profile.

acquire ¶

acquire() -> Path

Take ownership without waiting and create the profile directory.

Idempotent while held.

Returns:

Type	Description
`Path`	The profile directory.

Raises:

Type	Description
`ProfileInUseError`	If another lease, in any process, holds the profile.
`ConfigurationError`	If directories are redirected or cannot be created.

release ¶

release() -> None

Give up ownership. Idempotent.

ProfileInfo `dataclass` ¶

ProfileInfo(name: str, path: Path, in_use: bool, modified: str)

One profile directory.

Attributes:

Name	Type	Description
`name`	`str`	Profile name (the directory name).
`path`	`Path`	Absolute profile directory.
`in_use`	`bool`	Whether another lease currently holds the profile.
`modified`	`str`	Last modification time of the directory, UTC ISO 8601.

WarmupReport `dataclass` ¶

WarmupReport(sites_visited: int, sites_failed: int, links_followed: int, elapsed: float)

What a warm-up did.

Attributes:

Name	Type	Description
`sites_visited`	`int`	Sites loaded and browsed without error.
`sites_failed`	`int`	Sites skipped after an error or a per-site timeout.
`links_followed`	`int`	Same-site links followed across all sites.
`elapsed`	`float`	Seconds spent, measured on the `Human`'s clock.

list_profiles ¶

list_profiles(root: Path) -> list[ProfileInfo]

Return the profiles under root, sorted by name.

Directories whose names are not valid profile names (such as .locks) are skipped. A missing root yields an empty list.

Parameters:

Name	Type	Description	Default
`root`	`Path`	Profile root directory.	required

Returns:

Type	Description
`list[ProfileInfo]`	One entry per profile directory.

remove_profile ¶

remove_profile(root: Path, name: str) -> Path

Delete a profile directory after taking its lease.

Parameters:

Name	Type	Description	Default
`root`	`Path`	Profile root directory.	required
`name`	`str`	Profile name.	required

Returns:

Type	Description
`Path`	The removed directory.

Raises:

Type	Description
`ConfigurationError`	For an invalid name, or if the profile does not exist.
`ProfileInUseError`	If another lease, in any process, holds the profile.
`OSError`	If the directory cannot be deleted.

warm_up `async` ¶

warm_up(page: Any, *, sites: Sequence[str] = DEFAULT_SITES, duration: float, human: Human | None = None, rng_seed: int | None = None, max_links_per_site: int = 3) -> WarmupReport

Browse sites humanly for at most duration seconds.

Sites are visited in a random order. Each gets a share of the remaining time, in which the page is read (dwell and wheel-scroll) and up to max_links_per_site same-site links are followed. A link is clicked only after a hit test confirms the pointer is over that link; otherwise it is navigated to directly. Login, account, cart, checkout, consent and download links are never followed, nothing is typed and no form is submitted.

A failing site (DNS, timeout, script error) is logged by category and skipped; it never aborts the warm-up.

Parameters:

Name	Type	Description	Default
`page`	`Any`	A native `botonomus.cdp.Page` or a Playwright page.	required
`sites`	`Sequence[str]`	Start URLs.	`DEFAULT_SITES`
`duration`	`float`	Upper bound on the warm-up in seconds.	required
`human`	`Human \| None`	Input engine for `page`; a default one is created when omitted.	`None`
`rng_seed`	`int \| None`	Seed for the site order, dwell and link choices (and for the created `Human`).	`None`
`max_links_per_site`	`int`	Most links followed on one site.	`3`

Returns:

Type	Description
`WarmupReport`	A `WarmupReport`.

Raises:

Type	Description
`ValueError`	If `duration` is not positive or `max_links_per_site` is negative.

botonomus.profiles¶