API References

curl low levl APIs

Curl

class curl_cffi.Curl(cacert: str = '', debug: bool = False, handle=None)

Wrapper for curl_easy_* functions of libcurl.

__init__(cacert: str = '', debug: bool = False, handle=None) → None

Parameters:

• cacert – CA cert path to use, by default, certs from certifi are used.

• debug – whether to show curl debug messages.

• handle – a curl handle instance from curl_easy_init.

debug() → None

Set debug to True

setopt(option: CurlOpt, value: Any) → int

Wrapper for curl_easy_setopt.

Parameters:

• option – option to set, using constants from CurlOpt enum

• value – value to set, strings will be handled automatically

Returns:

0 if no error, see CurlECode.

getinfo(option: CurlInfo) → bytes | int | float | list

Wrapper for curl_easy_getinfo. Gets information in response after curl.perform.

Parameters:

option – option to get info of, using constants from CurlInfo enum

Returns:

value retrieved from last perform.

version() → bytes

Get the underlying libcurl version.

impersonate(target: str, default_headers: bool = True) → int

Set the browser type to impersonate.

Parameters:

• target – browser to impersonate.

• default_headers – whether to add default headers, like User-Agent.

Returns:

0 if no error.

perform(clear_headers: bool = True) → None

Wrapper for curl_easy_perform, performs a curl request.

Parameters:

clear_headers – clear header slist used in this perform

Raises:

CurlError – if the perform was not successful.

duphandle() → Curl

Wrapper for curl_easy_duphandle.

This is not a full copy of entire curl object in python. For example, headers handle is not copied, you have to set them again.

reset() → None

Reset all curl options, wrapper for curl_easy_reset.

parse_cookie_headers(headers: list[bytes]) → SimpleCookie

Extract cookies.SimpleCookie from header lines.

Parameters:

headers – list of headers in bytes.

Returns:

A parsed cookies.SimpleCookie instance.

static get_reason_phrase(status_line: bytes) → bytes

Extract reason phrase, like OK, Not Found from response status line.

static parse_status_line(status_line: bytes) → tuple[CurlHttpVersion, int, bytes]

Parse status line.

Returns:

http_version, status_code, and reason phrase

close() → None

Close and cleanup curl handle, wrapper for curl_easy_cleanup.

ws_recv(n: int = 1024) → tuple[bytes, CurlWsFrame]

Receive a frame from a websocket connection.

Parameters:

n – maximum data to receive.

Returns:

a tuple of frame content and curl frame meta struct.

Raises:

CurlError – if failed.

ws_send(payload: bytes, flags: CurlWsFlag = CurlWsFlag.BINARY) → int

Send data to a websocket connection.

Parameters:

• payload – content to send.

• flags – websocket flag to set for the frame, default: binary.

Returns:

0 if no error.

Raises:

CurlError – if failed.

ws_close(code: int = 1000, message: bytes = b'') → int

Close a websocket connection. Shorthand for ws_send() with close code and message. Note that to completely close the connection, you must close the curl handle after this call with close().

Parameters:

• code – close code.

• message – close message.

Returns:

0 if no error.

Raises:

CurlError – if failed.

AsyncCurl

class curl_cffi.AsyncCurl(cacert: str = '', loop=None)

Wrapper around curl_multi handle to provide asyncio support. It uses the libcurl socket_action APIs.

__init__(cacert: str = '', loop=None)

Parameters:

• cacert – CA cert path to use, by default, certs from certifi are used.

• loop – EventLoop to use.

add_handle(curl: Curl)

Add a curl handle to be managed by curl_multi. This is the equivalent of perform in the async world.

remove_handle(curl: Curl)

Cancel a future for given curl handle.

set_result(curl: Curl)

Mark a future as done for given curl handle.

set_exception(curl: Curl, exception)

Raise exception of a future for given curl handle.

setopt(option, value)

Wrapper around curl_multi_setopt.

socket_action(sockfd: int, ev_bitmask: int) → int

Call libcurl socket_action function

process_data(sockfd: int, ev_bitmask: int)

Call curl_multi_info_read to read data for given socket.

async close()

Close and cleanup running timers, readers, writers and handles.

CurlMime

class curl_cffi.CurlMime(curl: Curl | None = None)

Wrapper for the curl_mime_ API.

__init__(curl: Curl | None = None)

Parameters:

curl – Curl instance to use.

addpart(name: str, *, content_type: str | None = None, filename: str | None = None, local_path: str | bytes | Path | None = None, data: bytes | None = None) → None

Add a mime part for a mutlipart html form.

Note: You can only use either local_path or data, not both.

Parameters:

• name – name of the field.

• content_type – content_type for the field. for example: image/png.

• filename – filename for the server.

• local_path – file to upload on local disk.

• data – file content to upload.

classmethod from_list(files: list[dict])

Create a multipart instance from a list of dict, for keys, see addpart

attach(curl: Curl | None = None) → None

Attach the mime instance to a curl instance.

close() → None

Close the mime instance and underlying files. This method must be called after perform or request.

Constants

Enum values used by setopt and getinfo can be accessed from CurlOpt and CurlInfo.

class curl_cffi.CurlOpt(value)

CULROPT_ constancs extracted from libcurl, see: https://curl.se/libcurl/c/curl_easy_setopt.html

class curl_cffi.CurlInfo(value)

CURLINFO_ constancs extracted from libcurl, see: https://curl.se/libcurl/c/curl_easy_getinfo.html

class curl_cffi.CurlMOpt(value)

CURLMOPT_ constancs extracted from libcurl, see: https://curl.se/libcurl/c/curl_multi_setopt.html

class curl_cffi.CurlECode(value)

CURLECODE_ constancs extracted from libcurl, see: https://curl.se/libcurl/c/libcurl-errors.html

class curl_cffi.CurlHttpVersion(value)

CURL_HTTP_VERSION constants from libcurl, see comments for details.

class curl_cffi.CurlWsFlag(value)

CURL_WS_FLAG constants from libcurl, see comments for details.

class curl_cffi.CurlSslVersion(value)

CURL_SSLVERSION constants from libcurl, see comments for details.

requests-like API

request method

requests.get, requests.post, etc are just aliases of .request(METHOD, ...)

curl_cffi.requests.request(method: Literal['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS', 'HEAD', 'TRACE', 'PATCH', 'QUERY'], url: str, thread: Literal['eventlet', 'gevent'] | None = None, curl_options: dict | None = None, debug: bool | None = None, **kwargs: None) → Response

Send an http request.

Parameters:

• method – http method for the request: GET/POST/PUT/DELETE etc.

• url – url for the requests.

• params – query string for the requests.

• data – form values(dict/list/tuple) or binary data to use in body, Content-Type: application/x-www-form-urlencoded will be added if a dict is given.

• json – json values to use in body, Content-Type: application/json will be added automatically.

• headers – headers to send.

• cookies – cookies to use.

• files – not supported, use multipart instead.

• auth – HTTP basic auth, a tuple of (username, password), only basic auth is supported.

• timeout – how many seconds to wait before giving up.

• allow_redirects – whether to allow redirection.

• max_redirects – max redirect counts, default 30, use -1 for unlimited.

• proxies – dict of proxies to use, prefer to use proxy if they are the same. format: {"http": proxy_url, "https": proxy_url}.

• proxy – proxy to use, format: “http://user@pass:proxy_url”. Can’t be used with proxies parameter.

• proxy_auth – HTTP basic auth for proxy, a tuple of (username, password).

• verify – whether to verify https certs.

• referer – shortcut for setting referer header.

• accept_encoding – shortcut for setting accept-encoding header.

• content_callback – a callback function to receive response body. def callback(chunk: bytes) -> None:

• impersonate – which browser version to impersonate.

• ja3 – ja3 string to impersonate.

• akamai – akamai string to impersonate.

• extra_fp – extra fingerprints options, in complement to ja3 and akamai strings.

• thread – thread engine to use for working with other thread implementations. choices: eventlet, gevent.

• default_headers – whether to set default browser headers when impersonating.

• default_encoding – encoding for decoding response content if charset is not found in headers. Defaults to “utf-8”. Can be set to a callable for automatic detection.

• quote – Set characters to be quoted, i.e. percent-encoded. Default safe string is !#$%&'()*+,/:;=?@[]~. If set to a sting, the character will be removed from the safe string, thus quoted. If set to False, the url will be kept as is, without any automatic percent-encoding, you must encode the URL yourself.

• curl_options – extra curl options to use.

• http_version – limiting http version, defaults to http2.

• debug – print extra curl debug info.

• interface – which interface to use.

• cert – a tuple of (cert, key) filenames for client cert.

• stream – streaming the response, default False.

• max_recv_speed – maximum receive speed, bytes per second.

• multipart – upload files using the multipart format, see examples for details.

• discard_cookies – discard cookies from server. Default to False.

Returns:

A Response object.

Sessions

class curl_cffi.requests.Session(curl: Curl | None = None, thread: ThreadType | None = None, use_thread_local_curl: bool = True, **kwargs: Unpack[BaseSessionParams[R]])

A request session, cookies and connections will be reused. This object is thread-safe, but it’s recommended to use a separate session for each thread.

__init__(curl: Curl | None = None, thread: ThreadType | None = None, use_thread_local_curl: bool = True, **kwargs: Unpack[BaseSessionParams[R]])

Parameters set in the __init__ method will be overriden by the same parameter in request method.

Parameters:

• curl – curl object to use in the session. If not provided, a new one will be created. Also, a fresh curl object will always be created when accessed from another thread.

• thread – thread engine to use for working with other thread implementations. choices: eventlet, gevent.

• headers – headers to use in the session.

• cookies – cookies to add in the session.

• auth – HTTP basic auth, a tuple of (username, password), only basic auth is supported.

• proxies – dict of proxies to use, prefer to use proxy if they are the same. format: {"http": proxy_url, "https": proxy_url}.

• proxy – proxy to use, format: “http://proxy_url”. Cannot be used with the above parameter.

• proxy_auth – HTTP basic auth for proxy, a tuple of (username, password).

• base_url – absolute url to use as base for relative urls.

• params – query string for the session.

• verify – whether to verify https certs.

• timeout – how many seconds to wait before giving up.

• trust_env – use http_proxy/https_proxy and other environments, default True.

• allow_redirects – whether to allow redirection.

• max_redirects – max redirect counts, default 30, use -1 for unlimited.

• impersonate – which browser version to impersonate in the session.

• ja3 – ja3 string to impersonate in the session.

• akamai – akamai string to impersonate in the session.

• extra_fp – extra fingerprints options, in complement to ja3 and akamai str.

• interface – which interface use.

• default_encoding – encoding for decoding response content if charset is not found in headers. Defaults to “utf-8”. Can be set to a callable for automatic detection.

• cert – a tuple of (cert, key) filenames for client cert.

• response_class – A customized subtype of Response to use.

Notes

This class can be used as a context manager.

from curl_cffi.requests import Session

with Session() as s:
    r = s.get("https://example.com")

request(method: ~typing.Literal['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS', 'HEAD', 'TRACE', 'PATCH', 'QUERY'], url: str, params: dict | list | tuple | None = None, data: dict[str, str] | list[tuple] | str | ~io.BytesIO | bytes | None = None, json: dict | list | None = None, headers: ~curl_cffi.requests.headers.Headers | ~collections.abc.Mapping[str, str | None] | ~collections.abc.Mapping[bytes, bytes | None] | ~collections.abc.Sequence[tuple[str, str]] | ~collections.abc.Sequence[tuple[bytes, bytes]] | ~collections.abc.Sequence[str | bytes] | None = None, cookies: ~curl_cffi.requests.cookies.Cookies | ~http.cookiejar.CookieJar | dict[str, str] | list[tuple[str, str]] | None = None, files: dict | None = None, auth: tuple[str, str] | None = None, timeout: float | tuple[float, float] | object | None = <object object>, allow_redirects: bool | None = None, max_redirects: int | None = None, proxies: dict[str, str] | None = None, proxy: str | None = None, proxy_auth: tuple[str, str] | None = None, verify: bool | None = None, referer: str | None = None, accept_encoding: str | None = 'gzip, deflate, br', content_callback: ~typing.Callable | None = None, impersonate: ~typing.Literal['edge99', 'edge101', 'chrome99', 'chrome100', 'chrome101', 'chrome104', 'chrome107', 'chrome110', 'chrome116', 'chrome119', 'chrome120', 'chrome123', 'chrome124', 'chrome131', 'chrome133a', 'chrome136', 'chrome99_android', 'chrome131_android', 'safari153', 'safari155', 'safari170', 'safari172_ios', 'safari180', 'safari180_ios', 'safari184', 'safari184_ios', 'firefox133', 'firefox135', 'tor145', 'chrome', 'edge', 'safari', 'safari_ios', 'chrome_android', 'firefox', 'safari15_3', 'safari15_5', 'safari17_0', 'safari17_2_ios', 'safari18_0', 'safari18_0_ios', 'safari18_4', 'safari18_4_ios'] | None = None, ja3: str | None = None, akamai: str | None = None, extra_fp: ~curl_cffi.requests.impersonate.ExtraFingerprints | ~curl_cffi.requests.impersonate.ExtraFpDict | None = None, default_headers: bool | None = None, default_encoding: str | ~typing.Callable[[bytes], str] = 'utf-8', quote: str | ~typing.Literal[False] = '', http_version: ~curl_cffi.const.CurlHttpVersion | ~typing.Literal['v1', 'v2', 'v2tls', 'v2_prior_knowledge', 'v3', 'v3only'] | None = None, interface: str | None = None, cert: str | tuple[str, str] | None = None, stream: bool | None = None, max_recv_speed: int = 0, multipart: ~curl_cffi.curl.CurlMime | None = None, discard_cookies: bool = False)

Send the request, see requests.request for details on parameters.

stream(method: Literal['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS', 'HEAD', 'TRACE', 'PATCH', 'QUERY'], url: str, **kwargs: None)

Equivalent to with request(..., stream=True) as r:

ws_connect(url, on_message=None, on_error=None, on_open=None, on_close=None, **kwargs) → WebSocket

Connects to a websocket url.

Note: This method is deprecated, use WebSocket instead.

Parameters:

• url – the ws url to connect.

• on_message – message callback, def on_message(ws, str)

• on_error – error callback, def on_error(ws, error)

• on_open – open callback, def on_open(ws)

• on_close – close callback, def on_close(ws)

Other parameters are the same as .request

Returns:

a WebSocket instance to communicate with the server.

class curl_cffi.requests.AsyncSession(*, loop=None, async_curl: AsyncCurl | None = None, max_clients: int = 10, **kwargs: Unpack[BaseSessionParams[R]])

An async request session, cookies and connections will be reused.

__init__(*, loop=None, async_curl: AsyncCurl | None = None, max_clients: int = 10, **kwargs: Unpack[BaseSessionParams[R]])

Parameters set in the __init__ method will be override by the same parameter in request method.

Parameters:

• loop – loop to use, if not provided, the running loop will be used.

• async_curl – [AsyncCurl](/api/curl_cffi#curl_cffi.AsyncCurl) object to use.

• max_clients – maxmium curl handle to use in the session, this will affect the concurrency ratio.

• headers – headers to use in the session.

• cookies – cookies to add in the session.

• auth – HTTP basic auth, a tuple of (username, password), only basic auth is supported.

• proxies – dict of proxies to use, prefer to use proxy if they are the same. format: {"http": proxy_url, "https": proxy_url}.

• proxy – proxy to use, format: “http://proxy_url”. Cannot be used with the above parameter.

• proxy_auth – HTTP basic auth for proxy, a tuple of (username, password).

• base_url – absolute url to use for relative urls.

• params – query string for the session.

• verify – whether to verify https certs.

• timeout – how many seconds to wait before giving up.

• trust_env – use http_proxy/https_proxy and other environments, default True.

• allow_redirects – whether to allow redirection.

• max_redirects – max redirect counts, default 30, use -1 for unlimited.

• impersonate – which browser version to impersonate in the session.

• ja3 – ja3 string to impersonate in the session.

• akamai – akamai string to impersonate in the session.

• extra_fp – extra fingerprints options, in complement to ja3 and akamai str.

• default_encoding – encoding for decoding response content if charset is not found in headers. Defaults to “utf-8”. Can be set to a callable for automatic detection.

• cert – a tuple of (cert, key) filenames for client cert.

• response_class – A customized subtype of Response to use.

Notes

This class can be used as a context manager, and it’s recommended to use via async with. However, unlike aiohttp, it is not required to use with.

from curl_cffi.requests import AsyncSession

# recommended.
async with AsyncSession() as s:
    r = await s.get("https://example.com")

s = AsyncSession()  # it also works.

async request(method: ~typing.Literal['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS', 'HEAD', 'TRACE', 'PATCH', 'QUERY'], url: str, params: dict | list | tuple | None = None, data: dict[str, str] | list[tuple] | str | ~io.BytesIO | bytes | None = None, json: dict | list | None = None, headers: ~curl_cffi.requests.headers.Headers | ~collections.abc.Mapping[str, str | None] | ~collections.abc.Mapping[bytes, bytes | None] | ~collections.abc.Sequence[tuple[str, str]] | ~collections.abc.Sequence[tuple[bytes, bytes]] | ~collections.abc.Sequence[str | bytes] | None = None, cookies: ~curl_cffi.requests.cookies.Cookies | ~http.cookiejar.CookieJar | dict[str, str] | list[tuple[str, str]] | None = None, files: dict | None = None, auth: tuple[str, str] | None = None, timeout: float | tuple[float, float] | object | None = <object object>, allow_redirects: bool | None = None, max_redirects: int | None = None, proxies: dict[str, str] | None = None, proxy: str | None = None, proxy_auth: tuple[str, str] | None = None, verify: bool | None = None, referer: str | None = None, accept_encoding: str | None = 'gzip, deflate, br', content_callback: ~typing.Callable | None = None, impersonate: ~typing.Literal['edge99', 'edge101', 'chrome99', 'chrome100', 'chrome101', 'chrome104', 'chrome107', 'chrome110', 'chrome116', 'chrome119', 'chrome120', 'chrome123', 'chrome124', 'chrome131', 'chrome133a', 'chrome136', 'chrome99_android', 'chrome131_android', 'safari153', 'safari155', 'safari170', 'safari172_ios', 'safari180', 'safari180_ios', 'safari184', 'safari184_ios', 'firefox133', 'firefox135', 'tor145', 'chrome', 'edge', 'safari', 'safari_ios', 'chrome_android', 'firefox', 'safari15_3', 'safari15_5', 'safari17_0', 'safari17_2_ios', 'safari18_0', 'safari18_0_ios', 'safari18_4', 'safari18_4_ios'] | None = None, ja3: str | None = None, akamai: str | None = None, extra_fp: ~curl_cffi.requests.impersonate.ExtraFingerprints | ~curl_cffi.requests.impersonate.ExtraFpDict | None = None, default_headers: bool | None = None, default_encoding: str | ~typing.Callable[[bytes], str] = 'utf-8', quote: str | ~typing.Literal[False] = '', http_version: ~curl_cffi.const.CurlHttpVersion | ~typing.Literal['v1', 'v2', 'v2tls', 'v2_prior_knowledge', 'v3', 'v3only'] | None = None, interface: str | None = None, cert: str | tuple[str, str] | None = None, stream: bool | None = None, max_recv_speed: int = 0, multipart: ~curl_cffi.curl.CurlMime | None = None, discard_cookies: bool = False)

Send the request, see curl_cffi.requests.request for details on args.

stream(method: Literal['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS', 'HEAD', 'TRACE', 'PATCH', 'QUERY'], url: str, **kwargs: None)

Equivalent to async with request(..., stream=True) as r:

async close() → None

Close the session.

async ws_connect(url: str, autoclose: bool = True, params: dict | list | tuple | None = None, headers: ~curl_cffi.requests.headers.Headers | ~collections.abc.Mapping[str, str | None] | ~collections.abc.Mapping[bytes, bytes | None] | ~collections.abc.Sequence[tuple[str, str]] | ~collections.abc.Sequence[tuple[bytes, bytes]] | ~collections.abc.Sequence[str | bytes] | None = None, cookies: ~curl_cffi.requests.cookies.Cookies | ~http.cookiejar.CookieJar | dict[str, str] | list[tuple[str, str]] | None = None, auth: tuple[str, str] | None = None, timeout: float | tuple[float, float] | object | None = <object object>, allow_redirects: bool | None = None, max_redirects: int | None = None, proxies: dict[str, str] | None = None, proxy: str | None = None, proxy_auth: tuple[str, str] | None = None, verify: bool | None = None, referer: str | None = None, accept_encoding: str | None = 'gzip, deflate, br', impersonate: ~typing.Literal['edge99', 'edge101', 'chrome99', 'chrome100', 'chrome101', 'chrome104', 'chrome107', 'chrome110', 'chrome116', 'chrome119', 'chrome120', 'chrome123', 'chrome124', 'chrome131', 'chrome133a', 'chrome136', 'chrome99_android', 'chrome131_android', 'safari153', 'safari155', 'safari170', 'safari172_ios', 'safari180', 'safari180_ios', 'safari184', 'safari184_ios', 'firefox133', 'firefox135', 'tor145', 'chrome', 'edge', 'safari', 'safari_ios', 'chrome_android', 'firefox', 'safari15_3', 'safari15_5', 'safari17_0', 'safari17_2_ios', 'safari18_0', 'safari18_0_ios', 'safari18_4', 'safari18_4_ios'] | None = None, ja3: str | None = None, akamai: str | None = None, extra_fp: ~curl_cffi.requests.impersonate.ExtraFingerprints | ~curl_cffi.requests.impersonate.ExtraFpDict | None = None, default_headers: bool | None = None, quote: str | ~typing.Literal[False] = '', http_version: ~curl_cffi.const.CurlHttpVersion | ~typing.Literal['v1', 'v2', 'v2tls', 'v2_prior_knowledge', 'v3', 'v3only'] | None = None, interface: str | None = None, cert: str | tuple[str, str] | None = None, max_recv_speed: int = 0) → AsyncWebSocket

Connects to a WebSocket.

Parameters:

• url – url for the requests.

• autoclose – whether to close the WebSocket after receiving a close frame.

• params – query string for the requests.

• headers – headers to send.

• cookies – cookies to use.

• auth – HTTP basic auth, a tuple of (username, password), only basic auth is supported.

• timeout – how many seconds to wait before giving up.

• allow_redirects – whether to allow redirection.

• max_redirects – max redirect counts, default 30, use -1 for unlimited.

• proxies – dict of proxies to use, prefer to use proxy if they are the same. format: {"http": proxy_url, "https": proxy_url}.

• proxy – proxy to use, format: “http://user@pass:proxy_url”. Can’t be used with proxies parameter.

• proxy_auth – HTTP basic auth for proxy, a tuple of (username, password).

• verify – whether to verify https certs.

• referer – shortcut for setting referer header.

• accept_encoding – shortcut for setting accept-encoding header.

• impersonate – which browser version to impersonate.

• ja3 – ja3 string to impersonate.

• akamai – akamai string to impersonate.

• extra_fp – extra fingerprints options, in complement to ja3 and akamai str.

• default_headers – whether to set default browser headers.

• quote – Set characters to be quoted, i.e. percent-encoded. Default safe string is !#$%&'()*+,/:;=?@[]~. If set to a sting, the character will be removed from the safe string, thus quoted. If set to False, the url will be kept as is, without any automatic percent-encoding, you must encode the URL yourself.

• curl_options – extra curl options to use.

• http_version – limiting http version, defaults to http2.

• interface – which interface to use.

• cert – a tuple of (cert, key) filenames for client cert.

• max_recv_speed – maximum receive speed, bytes per second.

Headers

class curl_cffi.requests.Headers(headers: Headers | Mapping[str, str | None] | Mapping[bytes, bytes | None] | Sequence[tuple[str, str]] | Sequence[tuple[bytes, bytes]] | Sequence[str | bytes] | None = None, encoding: str | None = None)

HTTP headers, as a case-insensitive multi-dict.

property encoding: str

Header encoding is mandated as ascii, but we allow fallbacks to utf-8 or iso-8859-1.

raw()

Returns a list of the raw header items, as byte pairs.

multi_items() → list[tuple[str, str | None]]

Return a list of (key, value) pairs of headers. Allow multiple occurrences of the same key without concatenating into a single comma separated value.

get(key: str, default: Any = None) → Any

Return a header value. If multiple occurrences of the header occur then concatenate them together with commas.

get_list(key: str, split_commas: bool = False) → list[str | None]

Return a list of all header values for a given key. If split_commas=True is passed, then any comma separated header values are split into multiple return strings.

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

__getitem__(key: str) → str | None

Return a single header value. If there are multiple headers with the same key, then we concatenate them with commas. See: https://tools.ietf.org/html/rfc7230#section-3.2.2

__setitem__(key: str, value: str | None) → None

Set the header key to value, removing any duplicate entries. Retains insertion order.

__delitem__(key: str) → None

Remove the header key.

Cookies

class curl_cffi.requests.Cookies(cookies: Cookies | CookieJar | dict[str, str] | list[tuple[str, str]] | None = None)

HTTP Cookies, as a mutable mapping.

set(name: str, value: str, domain: str = '', path: str = '/', secure=False) → None

Set a cookie value by name. May optionally include domain and path.

get(name: str, default: str | None = None, domain: str | None = None, path: str | None = None) → str | None

Get a cookie by name. May optionally include domain and path in order to specify exactly which cookie to retrieve.

delete(name: str, domain: str | None = None, path: str | None = None) → None

Delete a cookie by name. May optionally include domain and path in order to specify exactly which cookie to delete.

clear(domain: str | None = None, path: str | None = None) → None

Delete all cookies. Optionally include a domain and path in order to only delete a subset of all the cookies.

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

__getitem__(name: str) → str

__setitem__(name: str, value: str) → None

__delitem__(name: str) → None

Request, Response

class curl_cffi.requests.Request(url: str, headers: Headers, method: str)

Representing a sent request.

class curl_cffi.requests.Response(curl: Curl | None = None, request: Request | None = None)

Contains information the server sends.

url

url used in the request.

content

response body in bytes.

text

response body in str.

status_code

http status code.

reason

http response reason, such as OK, Not Found.

ok

is status_code in [200, 400)?

headers

response headers.

cookies

response cookies.

elapsed

how many seconds the request cost.

encoding

http body encoding.

charset

alias for encoding.

primary_ip

primary ip of the server.

primary_port

primary port of the server.

local_ip

local ip used in this connection.

local_port

local port used in this connection.

charset_encoding

encoding specified by the Content-Type header.

default_encoding

encoding for decoding response content if charset is not found in headers. Defaults to “utf-8”. Can be set to a callable for automatic detection.

redirect_count

how many redirects happened.

redirect_url

the final redirected url.

http_version

http version used.

history

history redirections, only headers are available.

raise_for_status()

Raise an error if status code is not in [200, 400)

iter_lines(chunk_size=None, decode_unicode=False, delimiter=None)

iterate streaming content line by line, separated by \n.

Copied from: https://requests.readthedocs.io/en/latest/_modules/requests/models/ which is under the License: Apache 2.0

iter_content(chunk_size=None, decode_unicode=False)

iterate streaming content chunk by chunk in bytes.

json(**kw)

return a parsed json object of the content.

close()

Close the streaming connection, only valid in stream mode.

async aiter_lines(chunk_size=None, decode_unicode=False, delimiter=None)

iterate streaming content line by line, separated by \n.

Copied from: https://requests.readthedocs.io/en/latest/_modules/requests/models/ which is under the License: Apache 2.0

async aiter_content(chunk_size=None, decode_unicode=False)

iterate streaming content chunk by chunk in bytes.

async atext() → str

Return a decoded string.

async acontent() → bytes

wait and read the streaming content in one bytes object.

async aclose()

Close the streaming connection, only valid in stream mode.

Asyncio

WebSocket

class curl_cffi.requests.WebSocket(curl: Union[Curl, Any] = <object object>, *, autoclose: bool = True, skip_utf8_validation: bool = False, debug: bool = False, on_open: Optional[ON_OPEN_T] = None, on_close: Optional[ON_CLOSE_T] = None, on_data: Optional[ON_DATA_T] = None, on_message: Optional[ON_MESSAGE_T] = None, on_error: Optional[ON_ERROR_T] = None)

A WebSocket implementation using libcurl.

__init__(curl: Union[Curl, Any] = <object object>, *, autoclose: bool = True, skip_utf8_validation: bool = False, debug: bool = False, on_open: Optional[ON_OPEN_T] = None, on_close: Optional[ON_CLOSE_T] = None, on_data: Optional[ON_DATA_T] = None, on_message: Optional[ON_MESSAGE_T] = None, on_error: Optional[ON_ERROR_T] = None)

Parameters:

• autoclose – whether to close the WebSocket after receiving a close frame.

• skip_utf8_validation – whether to skip UTF-8 validation for text frames in run_forever().

• debug – print extra curl debug info.

• on_open – open callback, def on_open(ws)

• on_close – close callback, def on_close(ws, code, reason)

• on_data – raw data receive callback, def on_data(ws, data, frame)

• on_message – message receive callback, def on_message(ws, message)

• on_error – error callback, def on_error(ws, exception)

connect(url: str, params: Optional[Union[dict, list, tuple]] = None, headers: Optional[HeaderTypes] = None, cookies: Optional[CookieTypes] = None, auth: Optional[tuple[str, str]] = None, timeout: Optional[Union[float, tuple[float, float], object]] = <object object>, allow_redirects: bool = True, max_redirects: int = 30, proxies: Optional[ProxySpec] = None, proxy: Optional[str] = None, proxy_auth: Optional[tuple[str, str]] = None, verify: Optional[bool] = None, referer: Optional[str] = None, accept_encoding: Optional[str] = 'gzip, deflate, br', impersonate: Optional[BrowserTypeLiteral] = None, ja3: Optional[str] = None, akamai: Optional[str] = None, extra_fp: Optional[Union[ExtraFingerprints, ExtraFpDict]] = None, default_headers: bool = True, quote: Union[str, Literal[False]] = '', http_version: Optional[CurlHttpVersion] = None, interface: Optional[str] = None, cert: Optional[Union[str, tuple[str, str]]] = None, max_recv_speed: int = 0, curl_options: Optional[dict[CurlOpt, str]] = None)

Connect to the WebSocket.

libcurl automatically handles pings and pongs. ref: https://curl.se/libcurl/c/libcurl-ws.html

Parameters:

• url – url for the requests.

• params – query string for the requests.

• headers – headers to send.

• cookies – cookies to use.

• auth – HTTP basic auth, a tuple of (username, password), only basic auth is supported.

• timeout – how many seconds to wait before giving up.

• allow_redirects – whether to allow redirection.

• max_redirects – max redirect counts, default 30, use -1 for unlimited.

• proxies – dict of proxies to use, prefer to use proxy if they are the same. format: {"http": proxy_url, "https": proxy_url}.

• proxy – proxy to use, format: “http://user@pass:proxy_url”. Can’t be used with proxies parameter.

• proxy_auth – HTTP basic auth for proxy, a tuple of (username, password).

• verify – whether to verify https certs.

• referer – shortcut for setting referer header.

• accept_encoding – shortcut for setting accept-encoding header.

• impersonate – which browser version to impersonate.

• ja3 – ja3 string to impersonate.

• akamai – akamai string to impersonate.

• extra_fp – extra fingerprints options, in complement to ja3 and akamai str.

• default_headers – whether to set default browser headers.

• default_encoding – encoding for decoding response content if charset is not found in headers. Defaults to “utf-8”. Can be set to a callable for automatic detection.

• quote – Set characters to be quoted, i.e. percent-encoded. Default safe string is !#$%&'()*+,/:;=?@[]~. If set to a sting, the character will be removed from the safe string, thus quoted. If set to False, the url will be kept as is, without any automatic percent-encoding, you must encode the URL yourself.

• curl_options – extra curl options to use.

• http_version – limiting http version, defaults to http2.

• interface – which interface to use.

• cert – a tuple of (cert, key) filenames for client cert.

• max_recv_speed – maximum receive speed, bytes per second.

• curl_options – extra curl options to use.

recv_fragment() → tuple[bytes, CurlWsFrame]

Receive a single frame as bytes.

recv() → tuple[bytes, int]

Receive a frame as bytes.

libcurl splits frames into fragments, so we have to collect all the chunks for a frame.

recv_str() → str

Receive a text frame.

recv_json(*, loads: Callable[[str], T] = <function loads>) → T

Receive a JSON frame.

Parameters:

loads – JSON decoder, default is json.loads.

send(payload: str | bytes, flags: CurlWsFlag = CurlWsFlag.BINARY)

Send a data frame.

Parameters:

• payload – data to send.

• flags – flags for the frame.

send_binary(payload: bytes)

Send a binary frame.

Parameters:

payload – binary data to send.

send_bytes(payload: bytes)

Send a binary frame. Same as send_binary().

Parameters:

payload – binary data to send.

send_str(payload: str)

Send a text frame.

Parameters:

payload – text data to send.

send_json(payload: ~typing.Any, *, dumps: ~typing.Callable[[~typing.Any], str] = functools.partial(<function dumps>, separators=(',', ':')))

Send a JSON frame.

Parameters:

• payload – data to send.

• dumps – JSON encoder, default is json.dumps.

ping(payload: str | bytes)

Send a ping frame.

Parameters:

payload – data to send.

run_forever(url: str, **kwargs)

Run the WebSocket forever. See connect() for details on parameters.

libcurl automatically handles pings and pongs. ref: https://curl.se/libcurl/c/libcurl-ws.html

close(code: int = WsCloseCode.OK, message: bytes = b'')

Close the connection.

Parameters:

• code – close code.

• message – close reason.

class curl_cffi.requests.AsyncWebSocket(session: AsyncSession, curl: Curl, *, autoclose: bool = True, debug: bool = False)

An async WebSocket implementation using libcurl.

__init__(session: AsyncSession, curl: Curl, *, autoclose: bool = True, debug: bool = False)

async recv_fragment(*, timeout: float | None = None) → tuple[bytes, CurlWsFrame]

Receive a single frame as bytes.

Parameters:

timeout – how many seconds to wait before giving up.

async recv(*, timeout: float | None = None) → tuple[bytes, int]

Receive a frame as bytes.

libcurl splits frames into fragments, so we have to collect all the chunks for a frame.

Parameters:

timeout – how many seconds to wait before giving up.

async recv_str(*, timeout: float | None = None) → str

Receive a text frame.

Parameters:

timeout – how many seconds to wait before giving up.

async recv_json(*, loads: Callable[[str], T] = <function loads>, timeout: Optional[float] = None) → T

Receive a JSON frame.

Parameters:

• loads – JSON decoder, default is json.loads.

• timeout – how many seconds to wait before giving up.

async send(payload: str | bytes, flags: CurlWsFlag = CurlWsFlag.BINARY)

Send a data frame.

Parameters:

• payload – data to send.

• flags – flags for the frame.

async send_binary(payload: bytes)

Send a binary frame.

Parameters:

payload – binary data to send.

async send_bytes(payload: bytes)

Send a binary frame. Same as send_binary().

Parameters:

payload – binary data to send.

async send_str(payload: str)

Send a text frame.

Parameters:

payload – text data to send.

async send_json(payload: ~typing.Any, *, dumps: ~typing.Callable[[~typing.Any], str] = functools.partial(<function dumps>, separators=(',', ':')))

Send a JSON frame.

Parameters:

• payload – data to send.

• dumps – JSON encoder, default is json.dumps.

async ping(payload: str | bytes)

Send a ping frame.

Parameters:

payload – data to send.

async close(code: int = WsCloseCode.OK, message: bytes = b'')

Close the connection.

Parameters:

• code – close code.

• message – close reason.

Exceptions and Warnings

Exceptions

We try to follow the requests exception hirearchy, however, some are missing, while some are added.

If an exception is marked as “not used”, please catch the base exception.

class curl_cffi.requests.exceptions.RequestException(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

Base exception for curl_cffi.requests package

class curl_cffi.requests.exceptions.CookieConflict(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

Same cookie exists for different domains.

class curl_cffi.requests.exceptions.SessionClosed(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

The session has already been closed.

class curl_cffi.requests.exceptions.ImpersonateError(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

The impersonate config was wrong or impersonate failed.

class curl_cffi.requests.exceptions.InvalidJSONError(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

A JSON error occurred. not used

class curl_cffi.requests.exceptions.HTTPError(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

An HTTP error occurred.

class curl_cffi.requests.exceptions.IncompleteRead(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

Incomplete read of content

class curl_cffi.requests.exceptions.ConnectionError(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

A Connection error occurred.

class curl_cffi.requests.exceptions.DNSError(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

Could not resolve

class curl_cffi.requests.exceptions.ProxyError(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

A proxy error occurred.

class curl_cffi.requests.exceptions.SSLError(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

An SSL error occurred.

class curl_cffi.requests.exceptions.CertificateVerifyError(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

Raised when certificate validated has failed

class curl_cffi.requests.exceptions.Timeout(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

The request timed out.

class curl_cffi.requests.exceptions.ConnectTimeout(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

The request timed out while trying to connect to the remote server.

Requests that produced this error are safe to retry.

not used

class curl_cffi.requests.exceptions.ReadTimeout(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

The server did not send any data in the allotted amount of time. not used

class curl_cffi.requests.exceptions.URLRequired(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

A valid URL is required to make a request. not used

class curl_cffi.requests.exceptions.TooManyRedirects(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

Too many redirects.

class curl_cffi.requests.exceptions.MissingSchema(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

The URL scheme (e.g. http or https) is missing. not used

class curl_cffi.requests.exceptions.InvalidSchema(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

The URL scheme provided is either invalid or unsupported. not used

class curl_cffi.requests.exceptions.InvalidURL(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

The URL provided was somehow invalid.

class curl_cffi.requests.exceptions.InvalidHeader(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

The header value provided was somehow invalid. not used

class curl_cffi.requests.exceptions.InvalidProxyURL(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

The proxy URL provided is invalid. not used

class curl_cffi.requests.exceptions.ChunkedEncodingError(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

The server declared chunked encoding but sent an invalid chunk. not used

class curl_cffi.requests.exceptions.ContentDecodingError(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

Failed to decode response content. not used

class curl_cffi.requests.exceptions.StreamConsumedError(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

The content for this response was already consumed. not used

class curl_cffi.requests.exceptions.RetryError(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

Custom retries logic failed. not used

class curl_cffi.requests.exceptions.UnrewindableBodyError(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

Requests encountered an error when trying to rewind a body. not used

class curl_cffi.requests.exceptions.InterfaceError(msg, code: CurlECode | Literal[0] = 0, response=None, *args, **kwargs)

A specified outgoing interface could not be used.

Warnings

class curl_cffi.requests.exceptions.RequestsWarning

Base warning for Requests. not used

class curl_cffi.requests.exceptions.FileModeWarning

A file was opened in text mode, but Requests determined its binary length. not used

class curl_cffi.requests.exceptions.RequestsDependencyWarning

An imported dependency doesn’t match the expected version range.