botonomus.client

The httpx-like Client, Identity, Response and the module-level request functions.

botonomus.client

A lightweight, httpx-like layer over a shared real browser.

import botonomus

response = await botonomus.get("https://example.com")

async with botonomus.Client(max_tabs="auto") as client:
    response = await client.get("https://example.com")
    async with client.identity("acct-01") as me:
        await me.post("https://example.com/login", data={"user": "..."})

The module-level functions open a Client for one request, like httpx.get; keep a Client open to reuse the browser, cookies and the HTTP fast path.

Client

Client(*, config: BrowserConfig | None = None, proxy: str | None = None, mode: Mode = 'auto', max_tabs: int | Literal['auto'] = 'auto', block: Sequence[str] = (), fresh_context: bool = False, timeout: float = 30.0, wait: Wait = 'load', identity_root: str | Path | None = None)

Bases: _Verbs

A lightweight, httpx-like client backed by one shared, real Chrome.

An additional layer: Botonomus and its profile-backed sessions are unchanged. The browser starts on the first request and closes with the client.

Parameters:

Name	Type	Description	Default
config	BrowserConfig | None	Browser settings (executable, persona, proxy, headless, humanize...). driver must be native. Defaults to BrowserConfig().	None
proxy	str | None	Proxy for this client's contexts (credentials allowed); None uses config.proxy.	None
mode	Mode	"auto" (a tab first, then the HTTP fast path per host when botonomus[http] is installed) or "browser" (always a tab).	'auto'
max_tabs	int | Literal['auto']	Concurrent tabs, or "auto" to size from free memory and CPUs.	'auto'
block	Sequence[str]	Resource types to skip loading: image, font, media, stylesheet. Saves bandwidth and CPU; some sites notice.	()
fresh_context	bool	A new, empty context for every request instead of one shared context (cookies persist across requests by default).	False
timeout	float	Default seconds per request.	30.0
wait	Wait	Default page state to wait for: load or domcontentloaded.	'load'
identity_root	str | Path | None	Where identity keeps state files. Defaults to an identities directory next to config.profile_root.	None

Raises:

Type	Description
ConfigurationError	For an invalid option.

Example

async with Client() as client: # doctest: +SKIP ... response = await client.get("https://example.com") ... print(response.status, response.via)

max_tabs property

max_tabs: int

Concurrent tabs this client allows.

close async

close() -> None

Close every context and the browser. Idempotent.

request async

request(method: str, url: str, *, params: Mapping[str, Any] | None = None, headers: Mapping[str, str] | None = None, data: Mapping[str, Any] | str | bytes | None = None, json: Any = None, timeout: float | None = None, wait: Wait | None = None, settle: float = 0.0) -> Response

Send a request and return its Response.

Parameters:

Name	Type	Description	Default
method	str	HTTP method.	required
url	str	http:// or https:// URL.	required
params	Mapping[str, Any] | None	Query parameters appended to url.	None
headers	Mapping[str, str] | None	Extra request headers.	None
data	Mapping[str, Any] | str | bytes | None	Form fields (mapping), or a raw str/bytes body.	None
json	Any	A JSON body (sets Content-Type: application/json).	None
timeout	float | None	Seconds; defaults to the client's.	None
wait	Wait | None	Page state to wait for in a tab; defaults to the client's.	None
settle	float	Extra seconds to let scripts run in a tab before reading it.	0.0

Raises:

Type	Description
ConfigurationError	For invalid arguments.
ManagerClosedError	If the client is closed.
NavigationError	If the browser cannot load the URL.
TimeoutError_	If the page does not reach wait in time.

page async

page(url: str | None = None, *, wait: Wait | None = None, timeout: float | None = None) -> AsyncIterator[Any]

A tab in the client's context for full interaction (click, type, scroll).

Yields a native Page, or a HumanPage when config.humanize is on. The tab closes on exit; cookies and localStorage stay in the context.

identity async

identity(name: str, *, proxy: str | None = None, backend: Backend = 'context') -> AsyncIterator[Identity]

A persistent identity: cookies, localStorage and proxy kept between uses.

Parameters:

Name	Type	Description	Default
name	str	Identity name (profile-name rules). One live use at a time, across processes.	required
proxy	str | None	Proxy for this identity, saved with it; None reuses the saved proxy, else the client's.	None
backend	Backend	"context" keeps state in a small file and restores it into an in-memory context. "profile" opens the full Chrome profile name under config.profile_root (the one Botonomus.open uses) in its own browser, for sites that keep login state in IndexedDB, Cache Storage or service workers.	'context'

Raises:

Type	Description
ConfigurationError	For an invalid name, proxy or backend.
ProfileInUseError	If the identity is in use elsewhere.

Identity

Identity(client: Client, holder: _Holder, name: str)

Bases: _Verbs

A named, persistent identity of a Client. Obtained from Client.identity.

Attributes:

Name	Type	Description
name		The normalized identity name.

proxy property

proxy: str | None

The identity's proxy URL, or None for the client's.

request async

request(method: str, url: str, *, params: Mapping[str, Any] | None = None, headers: Mapping[str, str] | None = None, data: Mapping[str, Any] | str | bytes | None = None, json: Any = None, timeout: float | None = None, wait: Wait | None = None, settle: float = 0.0) -> Response

Send a request as this identity. See Client.request.

page async

page(url: str | None = None, *, wait: Wait | None = None, timeout: float | None = None) -> AsyncIterator[Any]

A tab as this identity. See Client.page.

cookies async

cookies() -> list[dict[str, Any]]

This identity's cookies.

Headers

Headers(items: Mapping[str, str] | None = None)

Bases: Mapping[str, str]

Read-only, case-insensitive response headers; keys are stored in lowercase.

Response dataclass

Response(url: str, status: int, headers: Headers, content: bytes, via: Via, elapsed: float, method: str = 'GET', html: str | None = None, cookies: dict[str, str] = dict())

One completed request.

Attributes:

Name	Type	Description
url	str	Final URL after redirects.
status	int	HTTP status code.
headers	Headers	Response headers.
content	bytes	The raw response body.
via	Via	"browser" (a real tab loaded it) or "http" (the fast path).
elapsed	float	Seconds from sending to having the body.
method	str	Request method.
html	str | None	For browser responses, the rendered DOM after scripts ran; else None.
cookies	dict[str, str]	Cookie names and values the context holds for this URL afterwards.

encoding property

encoding: str

The charset from Content-Type, or utf-8.

text property

text: str

The body decoded with encoding; undecodable bytes become U+FFFD.

ok property

ok: bool

Whether the status is below 400.

json

json() -> Any

The body parsed as JSON.

raise_for_status

raise_for_status() -> None

Raise HTTPStatusError for a 4xx or 5xx status.

request async

request(method: str, url: str, *, config: BrowserConfig | None = None, proxy: str | None = None, **kwargs: Any) -> Response

Send one request with a temporary Client. See Client.request.

get async

get(url: str, **kwargs: Any) -> Response

request("GET", url, ...) with a temporary Client.

post async

post(url: str, **kwargs: Any) -> Response

request("POST", url, ...) with a temporary Client.

put async

put(url: str, **kwargs: Any) -> Response

request("PUT", url, ...) with a temporary Client.

patch async

patch(url: str, **kwargs: Any) -> Response

request("PATCH", url, ...) with a temporary Client.

delete async

delete(url: str, **kwargs: Any) -> Response

request("DELETE", url, ...) with a temporary Client.

head async

head(url: str, **kwargs: Any) -> Response

request("HEAD", url, ...) with a temporary Client.