API References

curl low levl APIs

Curl

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

Wrapper for curl_easy_* functions of libcurl.

__init__(cacert: str = '', debug: bool = False, handle=None) → None[source]
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[source]

Set debug to True

setopt(option: CurlOpt, value: Any) → int[source]

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[str | int][source]

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[source]

Get the underlying libcurl version.

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

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, clear_resolve: bool = True) → None[source]

Wrapper for curl_easy_perform, performs a curl request.

Parameters:
  • clear_headers – clear header slist used in this perform

  • clear_resolve – clear resolve slist used in this perform

Raises:

CurlError – if the perform was not successful.

duphandle() → Curl[source]

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[source]

Reset all curl options, wrapper for curl_easy_reset.

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[source]

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

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

Parse status line.

Returns:

http_version, status_code, and reason phrase

close() → None[source]

Close and cleanup curl handle, wrapper for curl_easy_cleanup.

ws_recv() → tuple[bytes, CurlWsFrame][source]

Receive a frame from a websocket connection.

Returns:

a tuple of frame content and curl frame meta struct. Content is decompressed when permessage-deflate is negotiated. bytesleft may be -1 while the decoded size is unknown; 0 marks the end of the frame.

Raises:

CurlError – if failed.

ws_send(payload: bytes | bytearray | memoryview, flags: CurlWsFlag | int = CurlWsFlag.BINARY) → int[source]

Send data to a websocket connection.

Parameters:
  • payload – content to send.

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

Returns:

The number of bytes sent.

Raises:

CurlError – if failed.

Notes

Memoryview payloads must be byte-format for len() to work correctly.

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

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)[source]

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

__init__(cacert: str = '', loop=None)[source]
Parameters:
  • cacert – CA cert path to use, by default, certs from certifi are used.

  • loop – EventLoop to use.

add_handle(curl: Curl)[source]

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

remove_handle(curl: Curl)[source]

Cancel a future for given curl handle.

set_result(curl: Curl)[source]

Mark a future as done for given curl handle.

set_exception(curl: Curl, exception)[source]

Raise exception of a future for given curl handle.

setopt(option, value)[source]

Wrapper around curl_multi_setopt.

socket_action(sockfd: int, ev_bitmask: int) → int[source]

wrapper for curl_multi_socket_action, returns the number of running curl handles.

process_data(sockfd: int, ev_bitmask: int)[source]

Call curl_multi_info_read to read data for given socket.

async close()[source]

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

CurlMime

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

Wrapper for the curl_mime_ API.

__init__(curl: Curl | None = None)[source]
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[source]

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])[source]

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

attach(curl: Curl | None = None) → None[source]

Attach the mime instance to a curl instance.

close() → None[source]

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

CurlShare

class curl_cffi.CurlShare(connect: bool = False, dns: bool = True, ssl_session: bool = True)[source]

Wrapper for the curl_share_* API.

__init__(connect: bool = False, dns: bool = True, ssl_session: bool = True) → None[source]
Parameters:
  • connect – share the connection cache. Only safe for serialized, single-threaded use; libcurl does not support sharing connections between concurrent threads.

  • dns – share the DNS cache.

  • ssl_session – share the TLS session cache.

share(data: CurlLockData) → None[source]

Start sharing the given CurlLockData across attached handles.

unshare(data: CurlLockData) → None[source]

Stop sharing the given CurlLockData.

close() → None[source]

Cleanup the share handle, wrapper for curl_share_cleanup.

Only call this once every attached easy handle has been closed, otherwise raises CurlError with CurlShareCode.IN_USE and keeps the share open so cleanup can be retried after closing those handles.

Constants

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

class curl_cffi.CurlOpt(value)[source]

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

class curl_cffi.CurlInfo(value)[source]

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

class curl_cffi.CurlMOpt(value)[source]

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

class curl_cffi.CurlECode(value)[source]

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

class curl_cffi.CurlHttpVersion(value)[source]

CURL_HTTP_VERSION constants from libcurl, see comments for details.

class curl_cffi.CurlProxyType(value)[source]

CURLPROXY constants from libcurl.

class curl_cffi.CurlWsFlag(value)[source]

CURL_WS_FLAG constants from libcurl, see comments for details.

class curl_cffi.CurlSslVersion(value)[source]

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[source]

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.

  • content – raw request body as str, bytes, a byte iterable, or a binary file. AsyncSession also accepts an async byte iterable.

  • 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 or fingerprint 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 – interface name or local IP to bind to (bare IP = source address).

  • dns – DNS server IP address or list of addresses. Requires c-ares.

  • 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, curl_share: CurlShare | None = None, **kwargs: Unpack[BaseSessionParams[R]])[source]

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, curl_share: CurlShare | None = None, **kwargs: Unpack[BaseSessionParams[R]]) → None[source]

Parameters set in the __init__ method will be overridden 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.

  • curl_share – a CurlShare attached to every (thread-local) handle, to share the DNS and TLS session caches across threads. See the note in the docs on connection reuse across threads.

  • 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. Can be a bool, a CurlFollow value, or the string "safe". Use CurlFollow.SAFE or "safe" to reject redirects to internal/private IP addresses (SSRF protection).

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

  • retry – number of retries or RetryStrategy for failed requests.

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

  • ja3 – ja3 string to impersonate in the session.

  • akamai – akamai string to impersonate in the session.

  • perk – perk string to impersonate in the session.

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

  • interface – interface name or local IP to bind to (bare IP = source address).

  • dns – DNS server IP address or list of addresses. Requires c-ares.

  • doh_url – DNS-over-HTTPS server url, e.g. https://1.1.1.1/dns-query.

  • 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.

  • raise_for_status – automatically raise an HTTPError for 4xx and 5xx status codes.

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: HttpMethod, url: str, params: dict | list | tuple | None = None, data: RequestData | None = None, content: SyncRequestContent | None = None, json: dict | list | None = None, headers: HeaderTypes | None = None, cookies: CookieTypes | None = None, files: dict | None = None, auth: tuple[str, str] | None = None, timeout: float | tuple[float, float] | object | None = NOT_SET, allow_redirects: bool | CurlFollow | str | None = None, max_redirects: int | None = None, proxies: ProxySpec | 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: Callable | None = None, impersonate: BrowserTypeLiteral | Fingerprint | None = None, ja3: str | None = None, akamai: str | None = None, perk: str | None = None, extra_fp: ExtraFingerprints | ExtraFpDict | None = None, default_headers: bool | None = None, default_encoding: str | Callable[[bytes], str] = 'utf-8', quote: str | Literal[False] = '', http_version: CurlHttpVersion | HttpVersionLiteral | None = None, interface: str | None = None, dns: str | list[str] | None = None, doh_url: str | None = None, cert: str | tuple[str, str] | None = None, stream: bool | None = None, max_recv_speed: int = 0, multipart: CurlMime | None = None, discard_cookies: bool = False) → R[source]

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) → Generator[R, None, None][source]

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

ws_connect(url: str, on_message: Callable[[WebSocket, bytes | str], None] | None = None, on_error: Callable[[WebSocket, Exception], None] | None = None, on_open: Callable[[WebSocket], None] | None = None, on_close: Callable[[WebSocket, int, str], None] | None = None, on_data: Callable[[WebSocket, bytes, CurlWsFrame], None] | None = None, *, autoclose: bool = True, skip_utf8_validation: bool = False, ws_retry: WebSocketRetryStrategy | None = None, max_message_size: int = 4194304, params: dict[str, object] | list[object] | tuple[str, int | list[str] | dict[str, str | int]] | None = None, headers: HeaderTypes | None = None, cookies: CookieTypes | None = None, auth: tuple[str, str] | None = None, timeout: float | tuple[float, float] | NotSetType | None = NOT_SET, allow_redirects: bool | CurlFollow | str | None = None, max_redirects: int | None = None, proxies: ProxySpec | None = None, proxy: str | None = None, proxy_auth: tuple[str, str] | None = None, verify: bool | str | None = None, referer: str | None = None, accept_encoding: str | None = 'gzip, deflate, br', impersonate: BrowserTypeLiteral | str | Fingerprint | None = None, ja3: str | None = None, akamai: str | None = None, perk: str | None = None, extra_fp: ExtraFingerprints | ExtraFpDict | None = None, default_headers: bool | None = None, quote: str | Literal[False] = '', http_version: CurlHttpVersion | HttpVersionLiteral | None = None, interface: str | None = None, dns: str | list[str] | None = None, doh_url: str | None = None, cert: str | tuple[str, str] | None = None, max_recv_speed: int = 0, curl_options: dict[CurlOpt, Any] | None = None) → WebSocket[source]

Connects to a WebSocket URL using the session’s configuration.

libcurl automatically handles pings and pongs under the hood. Ref: https://curl.se/libcurl/c/libcurl-ws.html

Parameters:
  • url – The WebSocket URL to connect to.

  • on_message – Message received callback: def on_message(ws, msg).

  • 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, code, reason).

  • on_data – Raw data frame callback: def on_data(ws, bytes, frame).

  • autoclose – Whether to automatically close on CLOSE frame.

  • skip_utf8_validation – Skips UTF-8 validation of text frames in run_forever(), recv_str(), and recv_json(). When set, raise but don’t close connection per RFC 6455 §8.1.

  • ws_retry – Custom retry strategy for failed network receives.

  • max_message_size – Maximum allowed message size in bytes (default 4 MiB).

  • params – Query string parameters to attach to the handshake URL.

  • headers – Handshake request headers (merges with session defaults).

  • cookies – Handshake request cookies (merges with session defaults).

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

  • timeout – Handshake connection phase timeout in seconds. None is clamped to MAX_HANDSHAKE_SECS (30s) because the handshake cannot be interrupted once started.

  • allow_redirects – Allow redirects. Can be a bool, CurlFollow, or “safe”. Defaults to session’s value (True).

  • max_redirects – Max redirect counts. Defaults to the session’s configured value (30 by default).

  • proxies – Dictionary of proxies, e.g. {"http": proxy_url}.

  • proxy – Proxy URL. Cannot be used concurrently with proxies.

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

  • verify – Whether to verify SSL/TLS certificates.

  • referer – Shortcut for setting the HTTP Referer header.

  • accept_encoding – Shortcut for setting the Accept-Encoding header.

  • impersonate – Which browser version or fingerprint to impersonate.

  • ja3 – JA3 TLS client fingerprint string to impersonate.

  • akamai – Akamai HTTP/2 fingerprint string to impersonate.

  • perk – Perk fingerprint option to impersonate.

  • extra_fp – Extra fingerprint options complementing ja3 and akamai.

  • default_headers – Whether to set default browser headers. Defaults to session’s value (True).

  • quote – Quote (percent-encode) characters. Default safe string is !#$%&'()*+,/:;=?@[]~. Set to a string to quote more, or False to bypass automatic encoding.

  • http_version – WebSockets are always bootstrapped over HTTP/1.1 (RFC 6455), so this option has no effect.

  • interface – Interface name or local IP to bind to.

  • dns – DNS server IP address or list of addresses. Requires c-ares.

  • doh_url – DNS-over-HTTPS server url, e.g. https://1.1.1.1/dns-query.

  • cert – Tuple of (cert, key) filenames for client certificate auth.

  • max_recv_speed – Maximum receive speed in bytes per second.

  • curl_options – Dictionary of extra low-level curl options to apply.

Returns:

A fully-connected synchronous WebSocket instance.

Return type:

WebSocket

Note

The WebSocket is NOT thread-safe, add your own locking or use AsyncWebSocket for concurrent sending and receiving.

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

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

__init__(*, loop: asyncio.AbstractEventLoop | None = None, async_curl: AsyncCurl | None = None, max_clients: int = 10, curl_share: CurlShare | None = None, **kwargs: Unpack[BaseSessionParams[R]]) → None[source]

Parameters set in the __init__ method are overridden 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 – maximum curl handles to use in the session, this will affect the concurrency ratio. WebSockets count against this limit for their connection lifetime.

  • curl_share – a CurlShare attached to every pooled handle, to share the DNS and TLS session caches across the handles in the pool.

  • 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. Can be a bool, a CurlFollow value, or the string "safe". Use CurlFollow.SAFE or "safe" to reject redirects to internal/private IP addresses (SSRF protection).

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

  • retry – number of retries or RetryStrategy for failed requests.

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

  • ja3 – ja3 string to impersonate in the session.

  • akamai – akamai string to impersonate in the session.

  • perk – perk 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.

  • raise_for_status – automatically raise an HTTPError for 4xx and 5xx status codes.

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: HttpMethod, url: str, params: dict[str, str] | list[tuple[str, str]] | tuple[tuple[str, str], ...] | None = None, data: RequestData | None = None, content: RequestContent | None = None, json: dict[str, Any] | list[Any] | None = None, headers: HeaderTypes | None = None, cookies: CookieTypes | None = None, files: dict[str, Any] | None = None, auth: tuple[str, str] | None = None, timeout: float | tuple[float, float] | object | None = NOT_SET, allow_redirects: bool | CurlFollow | str | None = None, max_redirects: int | None = None, proxies: ProxySpec | 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: Callable[..., Any] | None = None, impersonate: BrowserTypeLiteral | Fingerprint | None = None, ja3: str | None = None, akamai: str | None = None, perk: str | None = None, extra_fp: ExtraFingerprints | ExtraFpDict | None = None, default_headers: bool | None = None, default_encoding: str | Callable[[bytes], str] = 'utf-8', quote: str | Literal[False] = '', http_version: CurlHttpVersion | HttpVersionLiteral | None = None, interface: str | None = None, dns: str | list[str] | None = None, doh_url: str | None = None, cert: str | tuple[str, str] | None = None, stream: bool | None = None, max_recv_speed: int = 0, multipart: CurlMime | None = None, discard_cookies: bool = False) → R[source]

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) → AsyncGenerator[R, None][source]

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

async close() → None[source]

Close the session.

ws_connect(url: str, autoclose: bool = True, params: dict[str, object] | list[object] | tuple[object, ...] | None = None, headers: HeaderTypes | None = None, cookies: CookieTypes | None = None, auth: tuple[str, str] | None = None, timeout: float | tuple[float, float] | NotSetType | None = NOT_SET, allow_redirects: bool | CurlFollow | str | None = None, max_redirects: int | None = None, proxies: ProxySpec | None = None, proxy: str | None = None, proxy_auth: tuple[str, str] | None = None, verify: bool | str | None = None, referer: str | None = None, accept_encoding: str | None = 'gzip, deflate, br', impersonate: BrowserTypeLiteral | str | Fingerprint | None = None, ja3: str | None = None, akamai: str | None = None, perk: str | None = None, extra_fp: ExtraFingerprints | ExtraFpDict | None = None, default_headers: bool | None = None, quote: str | Literal[False] = '', http_version: CurlHttpVersion | HttpVersionLiteral | None = None, interface: str | None = None, dns: str | list[str] | None = None, doh_url: str | None = None, cert: str | tuple[str, str] | None = None, max_recv_speed: int = 0, recv_queue_size: int = 64, send_queue_size: int = 32, max_send_batch_size: int = 64, coalesce_frames: bool = False, ws_retry: WebSocketRetryStrategy | None = None, recv_time_slice: float = 0.01, send_time_slice: float = 0.01, max_message_size: int = 4194304, drain_on_error: bool = False, block_on_recv_queue_full: bool = True, curl_options: dict[CurlOpt, Any] | None = None, *, skip_utf8_validation: bool = False) → AsyncWebSocketContext[source]

Connects to a WebSocket.

Parameters:
  • url – The WebSocket URL to connect to (e.g. wss://echo.websocket.org).

  • autoclose – Whether to automatically close on CLOSE frame.

  • skip_utf8_validation – Skips UTF-8 validation of text frames in recv_str(), and recv_json(). When set, raise an error but don’t close the connection as per RFC 6455 §8.1.

  • params – Query string parameters to attach to the handshake URL.

  • headers – Handshake request headers (merges with session defaults).

  • cookies – Handshake request cookies (merges with session defaults).

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

  • timeout – Handshake connection phase timeout in seconds. None is clamped to MAX_HANDSHAKE_SECS (30s) because the handshake cannot be interrupted once started.

  • allow_redirects – Whether to allow redirection. Can be a bool, a CurlFollow value, or the string "safe". Use CurlFollow.SAFE or "safe" to reject redirects to internal/private IP addresses (SSRF protection).

  • 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 SSL/TLS certificates.

  • referer – Shortcut for setting the HTTP Referer header.

  • accept_encoding – Shortcut for setting the Accept-Encoding header.

  • impersonate – Which browser version or fingerprint to impersonate.

  • ja3 – JA3 string to impersonate.

  • akamai – Akamai HTTP/2 fingerprint string to impersonate.

  • perk – Perk fingerprint option to impersonate.

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

  • default_headers – Whether to set default browser headers.

  • quote – Quote (percent-encode) characters. Default safe string is !#$%&'()*+,/:;=?@[]~. Set to a string to quote more, or False to bypass automatic encoding.

  • http_version – WebSockets are always bootstrapped over HTTP/1.1 (RFC 6455), so this option has no effect.

  • interface – Interface name or local IP to bind to (bare IP = source address).

  • dns – DNS server IP address or list of addresses. Requires c-ares.

  • doh_url – DNS-over-HTTPS server url, e.g. https://1.1.1.1/dns-query.

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

  • max_recv_speed – Maximum receive speed, bytes per second.

  • recv_queue_size – The maximum number of incoming WebSocket messages to buffer internally. This queue stores messages received by the Curl socket that are waiting to be consumed on calling recv().

  • send_queue_size – The maximum number of outgoing WebSocket messages to buffer before applying network backpressure. When you call send() the message is placed in this queue and transmitted when the Curl socket is next available for sending.

  • coalesce_frames – When enabled, multiple outgoing messages in the send queue can be merged into a single message for improved throughput. Defaults to False. This is an optional power-user optimization, which breaks frame boundaries and merges multiple frame payloads together. It should only be used when the application protocol is designed to handle concatenated data streams. See online docs before use.

  • max_send_batch_size – The max batch size when coalesce_frames is used.

  • ws_retry (WebSocketRetryStrategy) – Retry policy for WebSocket messages.

  • recv_time_slice – The maximum duration (in seconds) to process incoming messages before yielding to the event loop. Defaults to 0.01 (10ms).

  • send_time_slice – The maximum duration (in seconds) to process outgoing messages before yielding to the event loop. Defaults to 0.01 (10ms).

  • max_message_size – Maximum allowed message size in bytes (default 4 MiB).

  • drain_on_error – When a connection error occurs, attempt to consume all the buffered received messages first, before raising the error. Otherwise, raise it immediately, discarding the buffered messages (the default).

  • block_on_recv_queue_full – When the receive queue is full, receiving is paused for backpressure. When this option is disabled, the connection is immediately failed instead. The message that caused the overflow is not delivered; any messages already buffered can still be drained if drain_on_error is also set.

  • curl_options – Dictionary of extra low-level curl options to apply.

Documentation:

https://curl-cffi.readthedocs.io/en/latest/websockets.html

Cache

class curl_cffi.requests.CacheBackend(*, expires: timedelta, methods: Sequence[str] | None = None, ignored: Sequence[str] | None = None)[source]
__init__(*, expires: timedelta, methods: Sequence[str] | None = None, ignored: Sequence[str] | None = None) → None[source]
should_cache_request(request: Request, *, stream: bool = False, content_callback: Any = None) → bool[source]

XXX: streamed content is not cached.

should_store_response(response: Response) → bool[source]
get(request: Request, response_class: type[Response] = <class 'curl_cffi.requests.models.Response'>) → Response | None[source]
set(request: Request, response: Response) → None[source]
delete(request: Request) → None[source]
abstractmethod _read_payload(key: str) → dict[str, Any] | None[source]
abstractmethod _write_payload(key: str, payload: dict[str, Any]) → None[source]
abstractmethod _delete_payload(key: str) → None[source]
abstractmethod clear() → None[source]
class curl_cffi.requests.FileCacheBackend(*, expires: timedelta, path: str | PathLike[str] | None = None, methods: Sequence[str] | None = None, ignored: Sequence[str] | None = None)[source]
__init__(*, expires: timedelta, path: str | PathLike[str] | None = None, methods: Sequence[str] | None = None, ignored: Sequence[str] | None = None) → None[source]
clear() → None[source]

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)[source]

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]][source]

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[source]

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][source]

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.[source]

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[source]

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[source]

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

__delitem__(key: str) → None[source]

Remove the header key.

Cookies

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

HTTP Cookies, as a mutable mapping.

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

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[source]

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[source]

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[source]

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.[source]

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[source]
__setitem__(name: str, value: str) → None[source]
__delitem__(name: str) → None[source]

Request, Response

class curl_cffi.requests.Request(url: str, headers: Headers, method: str, body: bytes | None = None)[source]

Representing a sent request.

url

request url.

headers

request headers.

method

request http method.

body

request body as bytes, or None if not provided.

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

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

timedelta of the request duration.

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

redirect responses, in request order. Response bodies are not available.

download_size

total downloaded bytes (body).

upload_size

total uploaded bytes (body).

header_size

total header size.

request_size

request size.

response_size

download_size + header_size

raise_for_status()[source]

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

iter_lines(chunk_size=None, decode_unicode=False, delimiter=None)[source]

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)[source]

iterate streaming content chunk by chunk in bytes.

json(*, path: str | None = None, default: Any = None, **kw: Any) → Any[source]

Parse JSON, optionally returning the first JSONPath match.

Path selection requires curl_cffi[extra]. Return default (None if omitted) only when no matches exist; decoding and path errors raise. Additional keyword arguments are passed to the JSON decoder.

close()[source]

Close the streaming connection, only valid in stream mode.

async aiter_lines(chunk_size=None, decode_unicode=False, delimiter=None)[source]

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)[source]

iterate streaming content chunk by chunk in bytes.

async atext() → str[source]

Return a decoded string.

async acontent() → bytes[source]

wait and read the streaming content in one bytes object.

async aclose()[source]

Close the streaming connection, only valid in stream mode.

Asyncio

WebSocket

final class curl_cffi.requests.WebSocket(curl: Curl | NotSetType = NOT_SET, *, autoclose: bool = True, skip_utf8_validation: bool = False, debug: bool = False, on_open: OnOpenType | None = None, on_close: OnCloseType | None = None, on_data: OnDataType | None = None, on_message: OnMessageType | None = None, on_error: OnErrorType | None = None, ws_retry: WebSocketRetryStrategy | None = None, max_message_size: int = 4194304)[source]

A high-performance synchronous WebSocket implementation using libcurl.

__init__(curl: Curl | NotSetType = NOT_SET, *, autoclose: bool = True, skip_utf8_validation: bool = False, debug: bool = False, on_open: OnOpenType | None = None, on_close: OnCloseType | None = None, on_data: OnDataType | None = None, on_message: OnMessageType | None = None, on_error: OnErrorType | None = None, ws_retry: WebSocketRetryStrategy | None = None, max_message_size: int = 4194304) → None[source]
Parameters:
  • curl (Curl | NotSetType, optional) – Curl handle.

  • autoclose (bool, optional) – Whether to close the WebSocket after receiving a close frame.

  • skip_utf8_validation (bool, optional) – Skips UTF-8 validation of text frames in run_forever(), recv_str(), and recv_json(). When set, raise error but don’t close connection as per RFC 6455 §8.1.

  • debug (bool, optional) – Print extra curl debug info.

  • on_open (OnOpenType | None, optional) – Open callback.

  • on_close (OnCloseType | None, optional) – Close callback.

  • on_data (OnDataType | None, optional) – Data received callback. The frame attribute is a view into libcurl’s internal state and is only valid for the duration of the callback. Read what you need from it; do not retain it — the next received frame overwrites the same memory.

  • on_message (OnMessageType | None, optional) – Message received callback.

  • on_error (OnErrorType | None, optional) – Error callback.

  • ws_retry (WebSocketRetryStrategy | None, optional) – Retry policy.

  • max_message_size (int, optional) – Message size limit.

connect(url: str, params: dict[str, object] | list[object] | tuple[str, int | list[str] | dict[str, str | int]] | None = None, headers: HeaderTypes | None = None, cookies: CookieTypes | None = None, auth: tuple[str, str] | None = None, timeout: float | tuple[float, float] | NotSetType | None = NOT_SET, allow_redirects: bool | CurlFollow | str = True, max_redirects: int = 30, proxies: ProxySpec | None = None, proxy: str | None = None, proxy_auth: tuple[str, str] | None = None, verify: bool | str | None = None, referer: str | None = None, accept_encoding: str | None = 'gzip, deflate, br', impersonate: BrowserTypeLiteral | str | Fingerprint | None = None, ja3: str | None = None, akamai: str | None = None, perk: str | None = None, extra_fp: ExtraFingerprints | ExtraFpDict | None = None, default_headers: bool = True, quote: str | Literal[False] = '', http_version: CurlHttpVersion | HttpVersionLiteral | None = None, interface: str | None = None, cert: str | tuple[str, str] | None = None, max_recv_speed: int = 0, curl_options: dict[CurlOpt, Any] | None = None, *, base_url: str | None = None, base_params: dict[str, object] | list[object] | tuple[str, int | list[str] | dict[str, str | int]] | None = None, base_proxies: ProxySpec | None = None, base_verify: bool | str | None = True, dns: str | list[str] | None = None, doh_url: str | None = None) → WebSocket[source]

Connect to the WebSocket.

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

Parameters:
  • url – WebSocket connection URL.

  • base_url – Base URL to use for relative paths.

  • base_params – Session-level params applied before the request-level params.

  • base_proxies – Session-level proxies, used when the request sets none.

  • base_verify – Session-level verification settings to inherit.

  • 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. None waits indefinitely; prefer Session.ws_connect(), which clamps it.

  • allow_redirects – whether to allow redirection. Can be a bool, a CurlFollow value, or the string "safe".

  • 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 or fingerprint to impersonate.

  • ja3 – ja3 string to impersonate.

  • akamai – akamai string to impersonate.

  • perk – perk 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 (percent-encoded). Default safe string is !#$%&'()*+,/:;=?@[]~. If set to a string, the characters will be removed from the safe string. If set to False, the URL is used as-is (you must encode it yourself).

  • http_version – WebSockets are bootstrapped over HTTP/1.1, this has no effect.

  • interface – interface name or local IP to bind to (bare IP = source address).

  • dns – DNS server IP address or list of addresses. Requires c-ares.

  • doh_url – DNS-over-HTTPS server url, e.g. https://1.1.1.1/dns-query.

  • 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.

Note

The WebSocket is NOT thread-safe, add your own locking or use AsyncWebSocket for concurrent sending and receiving.

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

Receive a WebSocket message.

This method waits for and returns the next complete WebSocket message. Attempts to read immediately and only polls the socket if it returns EAGAIN.

Parameters:

timeout – How many seconds to wait for a message if socket is blocked.

Returns:

A tuple with the received payload and flags.

Return type:

tuple[bytes, int]

Raises:
  • WebSocketTimeout – If the timeout expires.

  • WebSocketClosed – If the connection is closed.

  • WebSocketError – WebSocket connection specific error.

  • CurlError – If a network-level transport error occurs.

Note

This method is NOT thread-safe.

Message fragmentation and reassembly are handled automatically by the implementation, so callers always receive complete messages.

recv_str(*, timeout: float | None = None) → str[source]

Receive a text frame.

Parameters:

timeout – How many seconds to wait before raising a timeout.

Raises:
  • WebSocketClosed – A close frame was received.

  • WebSocketError – The payload contains invalid UTF-8.

  • WebSocketError – The received frame is not a text frame.

Returns:

The text frame payload string.

Return type:

str

Note

This method checks if the message payload is valid UTF-8, unless skip_utf8_validation is set at connection time.

recv_json(*, loads: ~collections.abc.Callable[[str], ~curl_cffi.requests.websockets.T] = <function loads>, timeout: float | None = None) → T[source]

Receive a JSON frame.

Parameters:
  • loads – JSON decoder. Defaults to json.loads().

  • timeout – How many seconds to wait before raising a timeout.

Raises:

JSONDecodeError – The default decoder could not decode the message. Exceptions from a custom decoder propagate unchanged.

Returns:

Deserialized JSON object.

Return type:

T

Note

This method checks if the message payload is valid UTF-8, unless skip_utf8_validation is set at connection time.

This method inherits the same exceptions from recv_str().

send(payload: str | bytes | bytearray | memoryview, flags: CurlWsFlag | int = CurlWsFlag.BINARY, *, timeout: float | None = None) → int[source]

Send a WebSocket message.

Parameters:
  • payload – Data to send (str/bytes/bytearray/memoryview).

  • flags – Frame type flags (e.g. CurlWsFlag.TEXT / CurlWsFlag.BINARY).

  • timeout – Max seconds to wait if the socket is blocked.

Returns:

The number of bytes successfully written to the socket.

Return type:

int

Raises:
  • CurlError – Network related exception occured.

  • WebSocketClosed – The WebSocket has been closed.

  • WebSocketTimeout – The send operation timed out.

  • WebSocketError – The socket stalled while sending.

Note

This method is NOT thread-safe.

There are no limits on the size of the message that can be sent. Large outbound messages are seamlessly broken down into optimal fragments using the CURLWS_CONT flag, arriving as a single logical message to the server.

Non-contiguous (i.e. strided) memoryviews are copied as they cannot be cast into a contiguous format required by ffi.from_buffer().

send_binary(payload: bytes | bytearray | memoryview, *, timeout: float | None = None) → int[source]

Send a binary frame.

For more info, see the docstring for send().

send_bytes(payload: bytes | bytearray | memoryview, *, timeout: float | None = None) → int[source]

Send a binary frame, alias of send_binary().

For more info, see the docstring for send().

send_str(payload: str, *, timeout: float | None = None) → int[source]

Send a text frame.

For more info, see the docstring for send().

send_json(payload: object, *, dumps: ~collections.abc.Callable[[...], str | bytes] = <function dumps>, timeout: float | None = None) → int[source]

Send a JSON frame.

Parameters:
  • payload – data to send.

  • dumps – JSON encoder, default is json.dumps. The encoder may return str or bytes; bytes must be UTF-8, since the payload is sent as a text frame.

  • timeout – Max seconds to wait if the socket is blocked.

For more info, see the docstring for send().

ping(payload: str | bytes = b'', *, timeout: float | None = None) → int[source]

Send a ping frame.

Parameters:
  • payload (str | bytes, optional) – Ping frame payload. Defaults to b"".

  • timeout (float | None, optional) – Max seconds to wait if socket is blocked.

Raises:

WebSocketError – The payload length is outside specification (>125 bytes).

Returns:

The number of bytes successfully written to the socket.

Return type:

int

run_forever(url: str = '', **kwargs: Any) → None[source]

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

The connection is always terminated when this method returns, including when it exits by exception.

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

Raises:
  • WebSocketError – The selectors were not initialized by connect().

  • WebSocketClosed – The server dropped the connection without a close frame (EOF).

  • CurlError – An unrecoverable transport error, after any configured retries are exhausted.

close(code: int | WsCloseCode = WsCloseCode.OK, message: str | bytes = b'', timeout: float = 3.0) → None[source]

Close the WebSocket connection.

Sends a close frame to the peer and shuts down the connection.

Parameters:
  • code (int | WsCloseCode, optional) – Close code.

  • message (str | bytes, optional) – Close reason. Defaults to b"".

  • timeout (float, optional) – How long (in seconds) to wait for the connection to close gracefully before force-terminating.

Raises:

WebSocketError – The close reason is invalid UTF-8.

Note

WebSocket control frames are limited to 125-bytes. The close code requires 2 bytes, therefore 123-bytes of UTF-8 are available for the close reason. If the close reason is longer than this, it is implicitly truncated.

final class curl_cffi.requests.AsyncWebSocket(session: AsyncSession, curl: Curl, *, autoclose: bool = True, skip_utf8_validation: bool = False, debug: bool = False, recv_queue_size: int = 64, send_queue_size: int = 32, max_send_batch_size: int = 64, coalesce_frames: bool = False, ws_retry: WebSocketRetryStrategy | None = None, recv_time_slice: float = 0.01, send_time_slice: float = 0.01, max_message_size: int = 4194304, drain_on_error: bool = False, block_on_recv_queue_full: bool = True)[source]

A high-performance asynchronous WebSocket implementation using libcurl.

__init__(session: AsyncSession, curl: Curl, *, autoclose: bool = True, skip_utf8_validation: bool = False, debug: bool = False, recv_queue_size: int = 64, send_queue_size: int = 32, max_send_batch_size: int = 64, coalesce_frames: bool = False, ws_retry: WebSocketRetryStrategy | None = None, recv_time_slice: float = 0.01, send_time_slice: float = 0.01, max_message_size: int = 4194304, drain_on_error: bool = False, block_on_recv_queue_full: bool = True) → None[source]

Initializes an Async WebSocket session.

Do not instantiate this class directly. Use AsyncSession.ws_connect.

This class implements an async context manager, closing the connection automatically on exit:

async with AsyncSession() as session:
    async with session.ws_connect("wss://api.example.com") as ws:
        await ws.send("Hello")
        msg = await ws.recv()
Parameters:
  • session (AsyncSession) – The parent session object.

  • curl (Curl) – The underlying Curl handle.

  • autoclose (bool) – Automatically close on receiving a close frame.

  • skip_utf8_validation – Skips UTF-8 validation of text frames in recv_str(), and recv_json(). When set, raise an error but don’t close the connection as per RFC 6455 §8.1.

  • debug (bool) – Enable verbose debug logging.

  • recv_queue_size (int) – Max number of incoming messages to buffer.

  • send_queue_size (int) – Max number of outgoing messages to buffer.

  • max_send_batch_size (int) – Max frames to coalesce per transmission.

  • coalesce_frames (bool) – Combine small frame payloads to improve throughput.

  • ws_retry (WebSocketRetryStrategy) – Retry configuration for failed receives.

  • recv_time_slice (float) – Max seconds to read messages before yielding.

  • send_time_slice (float) – Max seconds to write messages before yielding.

  • max_message_size (int) – Max size (bytes) of a single received message.

  • drain_on_error (bool) – Yield buffered messages before raising errors.

  • block_on_recv_queue_full (bool) – Behavior when the receive queue is full. If True (default), the reader blocks (may cause timeouts). If False, the connection fails immediately to prevent data loss.

Note

Architecture: This uses a background I/O model. Network operations run in background tasks. Network errors are raised in calls to send() or recv().

Performance: Time slices default to 10ms. Increase these values to allocate more CPU time to I/O operations at the cost of event loop latency.

Increasing queue sizes reduces backpressure and buffers more messages in memory, increasing throughput - but increases latency and bufferbloat.

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

Receive a WebSocket message.

This method waits for and returns the next complete WebSocket message.

Parameters:

timeout – How many seconds to wait for a message before raising a timeout.

Returns:

A tuple with the received payload and flags.

Return type:

tuple[bytes, int]

Raises:
  • WebSocketTimeout – If the timeout expires.

  • WebSocketClosed – If the connection is closed.

  • WebSocketError – WebSocket connection specific error.

  • CurlError – If a network-level transport error occurs.

Note

Message fragmentation and reassembly are handled automatically by the implementation, so callers always receive complete messages.

WebSocketError exceptions may have originated from prior send() or recv() operations, since all operations share the same transport state once a failure occurs.

This method does not wait for additional messages after a transport error is detected. If drain_on_error=True, subsequent calls to recv() will return any messages that were buffered in the receive queue at the time the reader failed, before the connection error is raised.

Concurrent calls to recv() are supported and safe; each caller awaits the next available message and will receive distinct messages in FIFO order.

If this coroutine is cancelled while a message is being received, that message may be dropped. Cancellation is treated as abandoning the receive operation.

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

Receive a text frame.

Parameters:

timeout – How many seconds to wait before raising a timeout.

Raises:
  • WebSocketClosed – A close frame was received.

  • WebSocketError – The payload contains invalid UTF-8.

  • WebSocketError – The received frame is not a text frame.

Returns:

The text frame payload string.

Return type:

str

Note

This method checks if the message payload is valid UTF-8, unless skip_utf8_validation is set at connection time.

async recv_json(*, loads: ~collections.abc.Callable[[str], ~curl_cffi.requests.websockets.T] = <function loads>, timeout: float | None = None) → T[source]

Receive a JSON frame.

Parameters:
  • loads – JSON decoder. Defaults to json.loads().

  • timeout – How many seconds to wait before raising a timeout.

Raises:
  • WebSocketError – The JSON data was empty.

  • WebSocketError – The JSON was invalid.

Returns:

Deserialized JSON object.

Return type:

T

Note

This method checks if the message payload is valid UTF-8, unless skip_utf8_validation is set at connection time.

This method inherits the same exceptions from recv_str().

async send(payload: str | bytes | bytearray | memoryview, flags: CurlWsFlag | int = CurlWsFlag.BINARY, timeout: float | None = None) → None[source]

Send a WebSocket message.

Parameters:
  • payload – Data to send (str/bytes/bytearray/memoryview).

  • flags – Frame type flags (e.g., CurlWsFlag.TEXT / CurlWsFlag.BINARY).

  • timeout – Max seconds to wait if the send queue is full.

Raises:
  • CurlError – Network related exception occured.

  • WebSocketClosed – The WebSocket has been closed.

  • WebSocketTimeout – The send operation timed out.

  • WebSocketError – Writer stalled or socket closed while sending.

Note

There are no limits on the size of the message that can be sent. Large outbound messages are seamlessly broken down into optimal fragments using the CURLWS_CONT flag, arriving as a single logical message to the server.

Non-contiguous (i.e. strided) memoryviews are copied as they cannot be cast into a contiguous format required by ffi.from_buffer().

Warning

This method is non-blocking. It queues the message for immediate transmission. Call await ws.flush() after sending if you need to guarantee that the data has actually reached the socket.

async send_binary(payload: bytes | bytearray | memoryview, *, timeout: float | None = None) → None[source]

Send a binary frame.

Parameters:
  • payload – Binary data to send.

  • timeout – Max seconds to wait if the send queue is full.

For more info, see the docstring for send().

async send_bytes(payload: bytes | bytearray | memoryview, *, timeout: float | None = None) → None[source]

Send a binary frame, alias of send_binary().

Parameters:
  • payload – Binary data to send.

  • timeout – Max seconds to wait if the send queue is full.

For more info, see the docstring for send().

async send_str(payload: str, *, timeout: float | None = None) → None[source]

Send a text frame.

Parameters:
  • payload – Text data to send.

  • timeout – Max seconds to wait if the send queue is full.

For more info, see the docstring for send().

async send_json(payload: object, *, dumps: ~collections.abc.Callable[[...], str | bytes] = <function dumps>, timeout: float | None = None) → None[source]

Send a JSON frame.

Parameters:
  • payload – Data to send.

  • dumps – JSON encoder, default is json.dumps(). The encoder may return str or bytes; bytes must be UTF-8, since the payload is sent as a text frame.

  • timeout – Max seconds to wait if the send queue is full.

For more info, see the docstring for send().

async ping(payload: str | bytes = b'', *, timeout: float | None = None) → None[source]

Send a ping frame.

Parameters:
  • payload – Ping payload to send. Defaults to b"".

  • timeout – Max seconds to wait if the send queue is full.

Raises:

WebSocketError – The payload length is outside specification (>125 bytes).

For more info, see the docstring for send().

async close(code: int | WsCloseCode = WsCloseCode.OK, message: str | bytes = b'', timeout: float = 3.0) → None[source]

Close the WebSocket connection.

Sends a close frame to the peer, waits for queued outgoing messages to be sent, and then shuts down the connection.

Parameters:
  • code (int | WsCloseCode, optional) – Close code.

  • message (str | bytes, optional) – Close reason. Defaults to b"".

  • timeout (float, optional) – How long (in seconds) to wait for the connection to close gracefully before force-terminating.

Raises:

WebSocketError – The close reason is invalid UTF-8.

Note

WebSocket control frames are limited to 125-bytes. The close code requires 2 bytes, therefore 123-bytes of UTF-8 are available for the close reason. If the close reason is longer than this, it is implicitly truncated.

Transport errors during the closing handshake are suppressed. The connection tears down regardless. The teardown also runs if the calling task is cancelled.

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: Any, **kwargs: Any)[source]

Base exception for curl_cffi.requests package

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

Same cookie exists for different domains.

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

The session has already been closed.

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

The impersonate config was wrong or impersonate failed.

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

A JSON error occurred. not used

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

An HTTP error occurred.

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

Incomplete read of content

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

A Connection error occurred.

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

Could not resolve

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

A proxy error occurred.

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

An SSL error occurred.

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

Raised when certificate validated has failed

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

The request timed out.

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

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: Any, **kwargs: Any)[source]

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: Any, **kwargs: Any)[source]

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: Any, **kwargs: Any)[source]

Too many redirects.

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

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: Any, **kwargs: Any)[source]

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: Any, **kwargs: Any)[source]

The URL provided was somehow invalid.

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

The header value provided was somehow invalid. not used

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

The proxy URL provided is invalid. not used

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

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: Any, **kwargs: Any)[source]

Failed to decode response content. not used

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

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: Any, **kwargs: Any)[source]

Custom retries logic failed. not used

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

The request body could not be rewound for a redirect or retry.

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

A specified outgoing interface could not be used.

Warnings

class curl_cffi.requests.exceptions.RequestsWarning[source]

Base warning for Requests. not used

class curl_cffi.requests.exceptions.FileModeWarning[source]

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

class curl_cffi.requests.exceptions.RequestsDependencyWarning[source]

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