botonomus.config

Validated, immutable configuration: BrowserConfig, proxy parsing and argument validation.

botonomus.config

Validated, immutable configuration objects.

OWNED_FLAGS module-attribute

OWNED_FLAGS: Final = ('--user-data-dir', '--remote-debugging-port', '--remote-debugging-address', '--remote-debugging-pipe', '--headless', '--enable-automation', '--proxy-server', '--lang', '--accept-lang', '--user-agent')

Flags Botonomus sets itself.

Overriding them would break process ownership or profile isolation, or would make automation observable: --enable-automation, --remote-debugging-pipe and --headless set navigator.webdriver; --user-agent reduces User-Agent Client Hints to their low-entropy values.

BrowserConfig dataclass

BrowserConfig(profile_root: Path = Path('.botonomus/profiles'), executable_path: Path | None = None, headless: bool = False, launch_timeout: float = 30.0, close_timeout: float = 10.0, locale: str | None = None, proxy: str | None = None, extra_args: tuple[str, ...] = (), driver: DriverName = 'native', render_when_occluded: bool = True, browser: BrowserChoice = 'auto', persona: PersonaSpec = 'auto', geoip: bool = False, timezone: str | None = None, allow_timezone_mismatch: bool = False, humanize: bool | HumanConfig = False, virtual_display: bool | None = None, persona_switches: tuple[str, ...] = ())

Settings shared by every session a manager opens.

Attributes:

Name	Type	Description
profile_root	Path	Directory holding one subdirectory per named profile. Never point this at an everyday Chrome profile.
executable_path	Path | None	Browser executable. None discovers installed Chrome.
headless	bool	Run without a window. Visible windows are the validated default.
launch_timeout	float	Seconds allowed for the process to start and accept CDP.
close_timeout	float	Seconds allowed for a graceful close before termination.
locale	str | None	BCP 47 tag applied with --lang and --accept-lang.
proxy	str | None	Upstream proxy URL (http, https or socks5). Credentials are supported through a loopback forwarder and never reach the command line.
extra_args	tuple[str, ...]	Additional --flag[=value] arguments for every session.
driver	DriverName	native (Botonomus' CDP driver, never sends Runtime.enable), patchright or playwright.
render_when_occluded	bool	Keep rendering windows that other windows cover. Chrome on Windows otherwise marks them hidden and stalls requestAnimationFrame, which hangs input when many sessions overlap.
browser	BrowserChoice	Which browser to launch when executable_path is unset: "botonomus" requires an installed Botonomus Chromium build, "chrome" uses Google Chrome, "auto" prefers an installed Botonomus build and falls back to Chrome.
persona	PersonaSpec	Fingerprint identity: "auto" derives a stable persona from the profile name on Botonomus Chromium and does nothing on Chrome; "off" disables it; an int seed or a Persona is used as given and requires Botonomus Chromium.
geoip	bool	Look up the proxy's exit before each launch and align locale and time zone with it. Requires proxy.
timezone	str | None	IANA time zone to present. Overrides the exit's zone. Applied by Botonomus Chromium; with Chrome it must match the host's zone.
allow_timezone_mismatch	bool	Launch Chrome even when the presented time zone cannot match the exit's. Off by default because the mismatch is a well-known detection signal.
humanize	bool | HumanConfig	Route session.page actions through human-like input. True uses the default preset; a HumanConfig customizes it. session.page.raw stays available for direct actions.
virtual_display	bool | None	Run headed browsers on an Xvfb virtual screen (Linux only). None (default) does so on Linux when no DISPLAY or WAYLAND_DISPLAY is set; True always; False never.
persona_switches	tuple[str, ...]	Resolved persona switches for one launch. Filled in by the session manager from persona, geoip and timezone; leave empty.

Raises:

Type	Description
ConfigurationError	On construction, if any value is invalid.

proxy_spec property

proxy_spec: ProxySpec | None

The parsed proxy, or None when no proxy is configured.

human_config property

human_config: HumanConfig | None

The humanize settings in effect, or None when humanize is off.

ProxySpec dataclass

ProxySpec(scheme: str, host: str, port: int, username: str | None = None, password: str | None = None)

A parsed upstream proxy.

Attributes:

Name	Type	Description
scheme	str	http, https (TLS to the proxy) or socks5.
host	str	Proxy hostname or IP literal, without brackets.
port	int	Proxy TCP port.
username	str | None	Optional username; excluded from repr.
password	str | None	Optional password; excluded from repr.

has_credentials property

has_credentials: bool

Whether the proxy requires authentication.

server property

server: str

The credential-free form accepted by Chrome's --proxy-server.

address property

address: str

host:port for logs and reports; never contains credentials.

validate_args

validate_args(args: object) -> tuple[str, ...]

Validate extra browser arguments.

Parameters:

Name	Type	Description	Default
args	object	A list or tuple of --flag or --flag=value strings.	required

Returns:

Type	Description
tuple[str, ...]	The arguments as a tuple.

Raises:

Type	Description
ConfigurationError	If args is not a sequence of well-formed flags, or names a flag listed in OWNED_FLAGS or a persona switch.

parse_proxy

parse_proxy(value: str) -> ProxySpec

Parse and validate a proxy URL.

Parameters:

Name	Type	Description	Default
value	str	A URL such as http://user:pass@host:8080 or socks5://host:1080. Percent-encoded credentials are decoded.	required

Returns:

Type	Description
ProxySpec	The parsed proxy.

Raises:

Type	Description
ConfigurationError	If the URL is malformed, uses an unsupported scheme, has a path, query or fragment, or has a password without a username. The message never echoes the input, which may contain credentials.