botonomus.core

The session manager (Botonomus) and session handles (Session).

botonomus.core

Session manager, session handles and launch identity resolution.

Botonomus

Botonomus(max_instances: int = 1, *, config: BrowserConfig | None = None, backend: Backend | None = None, identity: IdentityResolver | None = None)

Opens browser sessions with dedicated profiles under a concurrency limit.

Use as an async context manager. A manager can be entered once and belongs to the event loop that entered it.

Parameters:

Name	Type	Description	Default
max_instances	int	Maximum simultaneous sessions. Requests above the limit wait; cancelling a waiting request does not consume capacity.	1
config	BrowserConfig | None	Settings for every session. Defaults to BrowserConfig().	None
backend	Backend | None	Browser backend. Defaults to ChromeBackend with config.driver.	None
identity	IdentityResolver | None	Resolves executable, persona, locale and time zone per launch. Defaults to an IdentityResolver when backend is the default, and to none (the configuration is passed through unchanged) when a custom backend is supplied.	None

Raises:

Type	Description
ConfigurationError	If max_instances is not a positive integer.

Example

async with Botonomus(max_instances=10) as bot: # doctest: +SKIP ... async with bot.open(profile="acct-01") as session: ... await session.page.goto("https://example.com")

active_count property

active_count: int

Reserved slots, including launches and unconfirmed cleanup.

open async

open(*, profile: str, args: Sequence[str] = ()) -> AsyncIterator[Session]

Open a browser for a dedicated profile and yield its session.

The browser closes when the context exits, including on error or cancellation.

Parameters:

Name	Type	Description	Default
profile	str	1-64 ASCII letters, digits, _ or -, starting with a letter or digit. Normalized to lowercase.	required
args	Sequence[str]	Extra --flag[=value] arguments for this launch only.	()

Yields:

Type	Description
AsyncIterator[Session]	The open Session.

Raises:

Type	Description
ConfigurationError	For an invalid profile name or argument.
ProfileInUseError	If another session, in any process, holds the profile.
ManagerClosedError	If the manager is not open or closes during launch.
BrowserUnavailableError	If no browser executable is found.
PersonaUnsupportedError	If a persona is requested for stock Chrome.
GeoLookupError	If geoip=True and the proxy exit cannot be determined.
GeoMismatchError	If Chrome cannot present the exit's time zone.
BrowserStartupError	If the browser fails to start or attach.
BrowserCleanupError	If the session could not be confirmed closed.

close async

close() -> None

Reject new requests, wake waiters and close every owned session.

Idempotent and shielded from cancellation.

Raises:

Type	Description
BrowserCleanupError	If the backend cannot confirm shutdown; affected profiles stay locked.

Session

Session(profile: str, handle: BrowserHandle, close: Callable[[], Awaitable[None]], *, identity: LaunchIdentity | None = None, human: HumanConfig | None = None)

One open browser with its dedicated profile.

Obtained from Botonomus.open; do not construct directly.

Attributes:

Name	Type	Description
profile		The normalized profile name.

page property

page: Any

The initial page.

A botonomus.cdp.Page or a Playwright Page. With humanize enabled it is wrapped in HumanPage, whose raw attribute returns the unwrapped page.

context property

context: Any

The profile-backed browser context.

persona property

persona: Persona | None

The fingerprint persona applied at launch, if any.

exit property

exit: ExitInfo | None

The proxy exit used to align locale and time zone, if geoip was on.

executable property

executable: Path | None

The browser executable, when resolved by the manager.

close async

close() -> None

Close the browser early. The manager's context exit then does nothing.

resolve_executable

resolve_executable(config: BrowserConfig) -> Path

Return the browser executable a launch with config would use.

The same rule every session launch follows: an explicit executable_path or browser="chrome" selects Google Chrome (or the given file); otherwise the newest installed Botonomus Chromium build for this platform is preferred, and browser="auto" falls back to Chrome when none is installed. Blocking: it touches the filesystem, so call it through asyncio.to_thread from async code.

Parameters:

Name	Type	Description	Default
config	BrowserConfig	The session configuration. Only executable_path and browser are consulted.	required

Returns:

Type	Description
Path	The path of an existing executable.

Raises:

Type	Description
BrowserUnavailableError	If the configured executable does not exist, or no Chrome is found when Chrome is required or is the fallback.
BinaryNotInstalledError	If browser="botonomus" and no build is installed.