botonomus.browser

Executable discovery, the Chrome backend, launch arguments and the Botonomus Chromium installer.

botonomus.browser

Browser executables, processes, installed builds and the Chrome backend.

BUILD_MARKER module-attribute

BUILD_MARKER: Final = 'botonomus-build.json'

File placed next to the executable of every Botonomus Chromium build.

Backend

Bases: Protocol

Starts browsers and guarantees their shutdown.

start async

start() -> None

Prepare shared resources such as a driver runtime. Idempotent.

launch async

launch(profile_path: Path, config: BrowserConfig) -> BrowserHandle

Launch a browser for profile_path and attach to it.

Raises:

Type	Description
BrowserUnavailableError	If no executable is available.
BrowserStartupError	If the process or attachment fails; anything started has been cleaned up.
BrowserCleanupError	If a failed launch left processes that could not be confirmed stopped.

close async

close() -> None

Stop every browser this backend owns and release shared resources.

Raises:

Type	Description
BrowserCleanupError	If any owned browser could not be confirmed stopped; ownership is retained.

BrowserHandle

Bases: Protocol

One running browser attached to a dedicated profile.

context property

context: Any

The browser context (native Context or a Playwright BrowserContext).

page property

page: Any

The initial page (native Page or a Playwright Page).

close async

close() -> None

Stop the browser.

Returns only after every owned process is confirmed stopped.

Raises:

Type	Description
BrowserCleanupError	If that cannot be confirmed.

ChromeBackend

ChromeBackend(driver: DriverName | Driver = 'native')

Launches Chrome (or a named Chromium build) and attaches a driver.

Parameters:

Name	Type	Description	Default
driver	DriverName | Driver	A driver name, or a Driver instance.	'native'

start async

start() -> None

Start the driver runtime. Idempotent.

Raises:

Type	Description
BrowserStartupError	If the driver cannot start.

launch async

launch(profile_path: Path, config: BrowserConfig) -> ChromeHandle

Launch a browser for profile_path and attach the driver.

Raises:

Type	Description
BrowserUnavailableError	If no executable is found.
ConfigurationError	If virtual_display=True is requested off Linux.
BrowserStartupError	If launch, attachment or the virtual display fails or times out.
BrowserCleanupError	If a failed launch could not be cleaned up.

close async

close() -> None

Stop every owned browser, then the virtual display and the driver runtime.

Raises:

Type	Description
BrowserCleanupError	If any owned browser could not be stopped; the driver is left running and ownership retained. The virtual display is stopped regardless, so no Xvfb server outlives the manager.

ChromeHandle

ChromeHandle(process: Process, timeout: float)

One launched browser process, its attachment and its proxy forwarder.

Parameters:

Name	Type	Description	Default
process	Process	The browser's root process.	required
timeout	float	Seconds for the whole close sequence (graceful, then forced).	required

context property

context: Any

The driver's browser context.

Raises:

Type	Description
BrowserStartupError	If the driver has not attached yet.

page property

page: Any

The driver's initial page.

Raises:

Type	Description
BrowserStartupError	If the driver has not attached yet.

close async

close() -> None

Close gracefully, then terminate owned processes. Idempotent and shielded.

Raises:

Type	Description
BrowserCleanupError	If owned processes could not be confirmed stopped.

VirtualDisplay

VirtualDisplay(*, width: int = 1920, height: int = 1080, depth: int = 24, executable: str = 'Xvfb', start_timeout: float = 10.0)

An Xvfb server shared by the browsers of one manager.

Xvfb picks a free display number itself (-displayfd), so concurrent managers and processes never race for the same display.

Parameters:

Name	Type	Description	Default
width	int	Screen width in pixels.	1920
height	int	Screen height in pixels.	1080
depth	int	Colour depth.	24
executable	str	The Xvfb program.	'Xvfb'
start_timeout	float	Seconds to wait for the server to report its display.	10.0

Attributes:

Name	Type	Description
display	str | None	":N" while running, else None.
width		Screen width.
height		Screen height.

start async

start() -> None

Start the server. Idempotent.

Raises:

Type	Description
BrowserStartupError	If Xvfb is missing, fails or does not report a display in time. The server is stopped on any failure, including cancellation.

stop async

stop() -> None

Stop the server. Idempotent.

InstalledBinary dataclass

InstalledBinary(version: str, chromium_version: str, channel: str, platform: str, sha256: str, installed_at: datetime, directory: Path, executable: Path)

A complete, verified Botonomus Chromium install on disk.

Attributes:

Name	Type	Description
version	str	Botonomus build version, e.g. "155.0.8059.26-bn1".
chromium_version	str	Upstream Chromium version.
channel	str	Release channel the build came from.
platform	str	Platform tag of the build, e.g. "win-x64".
sha256	str	SHA-256 of the archive the install was unpacked from.
installed_at	datetime	When the install completed (UTC).
directory	Path	The install directory <home>/chromium/<version>.
executable	Path	The browser executable inside directory.

launch_arguments

launch_arguments(executable: Path, profile_path: Path, port: int, config: BrowserConfig, *, proxy_server: str | None = None, platform_args: Sequence[str] = ()) -> list[str]

Build the full browser command line.

Parameters:

Name	Type	Description	Default
executable	Path	Browser executable.	required
profile_path	Path	Dedicated --user-data-dir.	required
port	int	Explicit, nonzero loopback debugging port.	required
config	BrowserConfig	Session configuration.	required
proxy_server	str | None	Credential-free --proxy-server value, if a proxy is used. Credentials are handled by the loopback forwarder and never appear here.	None
platform_args	Sequence[str]	Flags the platform needs (container flags, virtual-display window geometry), placed before the user's extra_args.	()

Returns:

Type	Description
list[str]	Arguments in launch order, ending with the initial about:blank page.

find_botonomus_chromium

find_botonomus_chromium(version: str | None = None, *, cache_dir: Path | None = None) -> Path | None

Return the executable of an installed Botonomus Chromium build, if any.

Not consulted by find_chrome; callers decide the precedence between an installed Botonomus build and Google Chrome.

Parameters:

Name	Type	Description	Default
version	str | None	A specific build version, or None for the newest installed.	None
cache_dir	Path | None	Botonomus data directory; None uses the default location.	None

Returns:

Type	Description
Path | None	The executable path, or None if no matching build is installed.

Raises:

Type	Description
ConfigurationError	If version is malformed.

find_chrome

find_chrome(explicit: Path | None = None) -> Path

Return the browser executable to launch.

Parameters:

Name	Type	Description	Default
explicit	Path | None	A caller-supplied executable. When given, it is the only candidate.	None

Returns:

Type	Description
Path	The resolved path of an existing executable.

Raises:

Type	Description
BrowserUnavailableError	If explicit does not exist, or no installed Google Chrome is found in the standard locations or on PATH.

is_botonomus_build

is_botonomus_build(executable: Path) -> bool

Whether executable is a Botonomus Chromium build.

True when the build marker sits next to the executable, or the executable lives inside a verified install made by botonomus.browser.install. Blocking.

is_testing_build

is_testing_build(executable: Path) -> bool

Whether executable looks like Chrome for Testing or a Playwright download.

Those builds show a permanent "only for automated testing" infobar, which also shrinks the viewport, and are not what ordinary users run.

container_flags

container_flags(platform: str, shm_bytes: int | None, euid: int | None) -> tuple[str, ...]

Flags Chrome needs in containers. None of them is visible to pages.

Parameters:

Name	Type	Description	Default
platform	str	sys.platform value.	required
shm_bytes	int | None	Size of /dev/shm, or None if unknown.	required
euid	int | None	Effective user id, or None off POSIX.	required

Returns:

Type	Description
str	--disable-dev-shm-usage when /dev/shm is under 512 MB (Docker's
...	default is 64 MB, which crashes renderers), and --no-sandbox when running
tuple[str, ...]	as root, where Chrome refuses to start otherwise.

needs_virtual_display

needs_virtual_display(config: BrowserConfig, platform: str = platform, environ: Mapping[str, str] = environ) -> bool

Whether a launch under config should run on a virtual display.

Headless sessions never need one. virtual_display=None (the default) means: on Linux, when neither DISPLAY nor WAYLAND_DISPLAY is set.

Parameters:

Name	Type	Description	Default
config	BrowserConfig	Session configuration.	required
platform	str	sys.platform value.	platform
environ	Mapping[str, str]	Process environment.	environ

Raises:

Type	Description
ConfigurationError	If virtual_display=True is requested off Linux.

find_installed

find_installed(version: str | None = None, *, cache_dir: Path | None = None) -> Path | None

Return the executable of the newest (or the given) install for this platform.

Parameters:

Name	Type	Description	Default
version	str | None	A specific build version, or None for the newest.	None
cache_dir	Path | None	Botonomus data directory; None uses botonomus_home.	None

Returns:

Type	Description
Path | None	The executable path, or None if no matching install exists.

Raises:

Type	Description
ConfigurationError	If version is malformed.

install async

install(*, version: str | None = None, manifest_url: str | None = None, cache_dir: Path | None = None, progress: ProgressCallback | None = None, public_key: bytes = RELEASE_PUBLIC_KEY, allow_insecure_loopback: bool = False, timeout: float = 60.0) -> InstalledBinary

Download, verify and install Botonomus Chromium for this platform.

Returns immediately, without network access, when version is given and already installed. Otherwise the manifest is fetched and verified first; if its release is already installed that install is returned. Concurrent installs into the same cache_dir, from any process, are serialised by a file lock.

Parameters:

Name	Type	Description	Default
version	str | None	A specific build version; None installs the channel's newest.	None
manifest_url	str | None	Channel manifest URL. None uses BOTONOMUS_MANIFEST_URL if set, else DEFAULT_MANIFEST_URL.	None
cache_dir	Path | None	Botonomus data directory; None uses botonomus_home.	None
progress	ProgressCallback | None	Called on the event loop thread as progress(received, total) while the archive downloads, starting with (0, total).	None
public_key	bytes	Release verification key. Only tests should change this.	RELEASE_PUBLIC_KEY
allow_insecure_loopback	bool	Accept http:// URLs on loopback hosts. For tests against a local server only; never enable it for real downloads.	False
timeout	float	Socket timeout in seconds for each network operation.	60.0

Returns:

Type	Description
InstalledBinary	The installed binary.

Raises:

Type	Description
ConfigurationError	If version is malformed.
BinaryDownloadError	If the manifest, signature or archive cannot be fetched.
BinaryVerificationError	If the signature, manifest, archive size or hash, or an archive entry fails verification.
BinaryNotInstalledError	If the release has no build for this platform.
OSError	On local filesystem failures such as a full disk.

installed_binaries

installed_binaries(cache_dir: Path | None = None) -> list[InstalledBinary]

List complete installs, newest version first.

Directories without a valid installed.json record or whose executable is missing are ignored.

Parameters:

Name	Type	Description	Default
cache_dir	Path | None	Botonomus data directory; None uses botonomus_home.	None

Returns:

Type	Description
list[InstalledBinary]	Installed binaries for every platform found, sorted by version descending.

uninstall

uninstall(version: str, *, cache_dir: Path | None = None) -> bool

Remove an install.

The directory is first renamed out of place, so a partially deleted install is never mistaken for a valid one; leftovers are cleaned by the next install.

Parameters:

Name	Type	Description	Default
version	str	The build version to remove.	required
cache_dir	Path | None	Botonomus data directory; None uses botonomus_home.	None

Returns:

Type	Description
bool	True if an install directory was removed, False if none existed.

Raises:

Type	Description
ConfigurationError	If version is malformed.
OSError	If the files are in use (for example by a running browser).

executable_sha256

executable_sha256(executable: Path) -> str | None

SHA-256 of the executable's bytes, or None if it cannot be read. Blocking.

Parameters:

Name	Type	Description	Default
executable	Path	The browser executable.	required

executable_version

executable_version(executable: Path) -> str | None

Return the browser version for executable, or None if unknown.

Chrome installs on Windows keep a sibling directory named after the version (Application/141.0.7390.55); the highest such name is used. Otherwise, on Windows, the executable's VS_FIXEDFILEINFO version resource is read.

Parameters:

Name	Type	Description	Default
executable	Path	The browser executable.	required

Returns:

Type	Description
str | None	A dotted version such as 141.0.7390.55, or None.