human_requests

Submodules

• human_requests.browsers
• human_requests.impersonation
• human_requests.session

Classes

URL	A dataclass containing the parsed URL components.
HttpMethod	Represents an HTTP method.
ImpersonationConfig	Spoofing settings for curl_cffi and browser header generation.
Policy	Policy for selecting a profile in ImpersonationConfig
Session	curl_cffi.AsyncSession + BrowserMaster + CookieManager.

Package Contents

class URL

A dataclass containing the parsed URL components.

full_url: str

The full URL.

base_url: str = ''

The base URL, without query parameters.

secure: bool = False

Whether the URL is secure (https/wss).

protocol: str = ''

The protocol of the URL.

path: str = ''

The path of the URL.

domain_with_port: str = ''

The domain of the URL with port.

domain: str = ''

The domain of the URL.

port: int | None = None

The port of the URL.

params: dict[str, list[str]]

A dictionary of query parameters.

__post_init__() → None

class HttpMethod(*args, **kwds)

Represents an HTTP method.

GET = 'GET'

Retrieves data from a server. It only reads data and does not modify it.

POST = 'POST'

Submits data to a server to create a new resource. It can also be used to update existing resources.

PUT = 'PUT'

Updates a existing resource on a server. It can also be used to create a new resource.

PATCH = 'PATCH'

Updates a existing resource on a server. It only updates the fields that are provided in the request body.

DELETE = 'DELETE'

Deletes a resource from a server.

HEAD = 'HEAD'

Retrieves metadata from a server. It only reads the headers and does not return the response body.

OPTIONS = 'OPTIONS'

Provides information about the HTTP methods supported by a server. It can be used for Cross-Origin Resource Sharing (CORS) request.

class ImpersonationConfig

Spoofing settings for curl_cffi and browser header generation.

Example:

cfg = ImpersonationConfig(
    policy=Policy.RANDOM_EACH_REQUEST,
    browser_family=["chrome", "edge"],
    min_version=120,
    geo_country="DE",
    sync_with_engine=True,
)

policy: Policy

Policy for when a profile is selected

browser_family: str | Sequence[str] | None = None

Browser family (chrome, edge, opera, firefox, safari)

min_version: int | None = None

Minimum browser version

custom_filter: Callable[[str], bool]

Custom script for filtering impersonation profiles. Must return a bool

geo_country: str = 'en-US'

Language tag in BCP 47 format (en-US, ru-RU, etc.)

sync_with_engine: bool = True

Restrict to the current Playwright engine family (chromium, firefox, webkit), or camoufox=firefox

rotate_headers: bool = True

Whether to generate browser-like headers (user-agent, accept-language, etc.)

choose(engine: str) → str

Returns the impersonation profile name for the current request.

forge_headers(profile: str) → dict[str, str]

Generates a set of real-browser headers for the same profile, using browserforge.HeaderGenerator.

class Policy(*args, **kwds)

Policy for selecting a profile in ImpersonationConfig

INIT_RANDOM

Profile is selected at session creation and then does not change

RANDOM_EACH_REQUEST

Profile is selected for every request

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