human_requests.session

core.session — unified stateful session for curl_cffi and Playwright-compatible engines.

Main Methods

• Session.request — low-level HTTP request (curl_cffi) with cookie jar.

• Session.goto_page — opens a URL in the browser, returns a Page inside a context manager; upon exit synchronizes cookies + localStorage.

• Response.render — offline render of a pre-fetched Response.

Optional Dependencies

• playwright-stealth: enabled via playwright_stealth=True. If the package is not installed and the flag is set — raises RuntimeError with installation instructions.

• camoufox: selected with browser=’camoufox’.

• patchright: selected with browser=’patchright’.

• Incompatibility: camoufox/patchright + playwright_stealth cannot be used together. Raises RuntimeError.

Additional

• Browser launch arguments are assembled via make_browser_launch_opts() from: - browser_launch_opts (arbitrary dict) - headless (always overrides the key of the same name) - proxy (string URL or dict) → adapted for Playwright/Patchright/Camoufox

• Proxy is also applied to curl_cffi (if no custom proxy is passed in .request()).

Classes

Session

curl_cffi.AsyncSession + BrowserMaster + CookieManager.

Module Contents

class Session(

*,

timeout: float = 15.0,

headless: bool = True,

browser: human_requests.browsers.Engine = 'chromium',

spoof: ImpersonationConfig | None = None,

playwright_stealth: bool = True,

page_retry: int = 2,

direct_retry: int = 1,

browser_launch_opts: Mapping[str, Any] = {},

proxy: str | None = None,

)

curl_cffi.AsyncSession + BrowserMaster + CookieManager.

timeout: float = 15.0

Timeout for goto/direct requests.

headless: bool = True

Whether to run the browser in headless mode.

browser_name: human_requests.browsers.Engine = 'chromium'

Current browser (chromium/firefox/webkit/camoufox/patchright).

spoof: ImpersonationConfig

Impersonation settings (user-agent, TLS, client-hello).

playwright_stealth: bool = True

Hide certain automation signatures? Implemented via JS injection. Some sites may detect this.

page_retry: int = 2

If a timeout occurs after N seconds — retry with page.reload().

direct_retry: int = 1

If a timeout occurs after N seconds — retry the direct request.

browser_launch_opts: Mapping[str, Any]

Browser launch arguments (arbitrary keys).

proxy: str | dict[str, str] | None = None

Proxy server, one of:

1. URL string in the form: schema://user:pass@host:port

2. playwright-like dict

cookies: CookieManager

Storage of all active cookies.

local_storage: dict[str, dict[str, str]]

localStorage from the last browser context (goto run).

async request(

method: HttpMethod | str,

url: str,

*,

headers: Mapping[str, str] | None = None,

retry: int | None = None,

**kwargs: Any,

) → Response

Standard fast request via curl_cffi. You must provide either an HttpMethod or its string representation, as well as a URL.

Optionally, you can pass additional headers.

Extra parameters can be passed through **kwargs to curl_cffi.AsyncSession.request (see their documentation for details). Retries are performed ONLY on cffi Timeout: curl_cffi.requests.exceptions.Timeout.

async goto_page(

url: str,

*,

wait_until: Literal['commit', 'load', 'domcontentloaded', 'networkidle'] = 'commit',

retry: int | None = None,

) → AsyncGenerator[playwright.async_api.Page, None]

Opens a page in the browser using a one-time context. Retries perform a “soft reload” without recreating the context.

async close() → None

async __aenter__() → Session

async __aexit__(

exc_type: type[BaseException] | None,

exc: BaseException | None,

tb: TracebackType | None,

) → None