Skip to content

API Reference

pyqwest.Client

An asynchronous HTTP client.

A client is a lightweight wrapper around a Transport, providing convenience methods for common HTTP operations with buffering.

Parameters:

Name Type Description Default
transport Transport | None

The transport to use for requests. If None, the shared default transport will be used.

None

get async

Executes a GET HTTP request.

Parameters:

Name Type Description Default
url str

The unencoded request URL.

required
headers Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None

The request headers.

None
timeout float | None

The timeout for the request in seconds.

None

Raises:

Type Description
ConnectionError

If the connection fails.

TimeoutError

If the request times out.

post async

Executes a POST HTTP request.

Parameters:

Name Type Description Default
url str

The unencoded request URL.

required
headers Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None

The request headers.

None
content bytes | AsyncIterator[bytes] | None

The request content.

None
timeout float | None

The timeout for the request in seconds.

None

Raises:

Type Description
ConnectionError

If the connection fails.

TimeoutError

If the request times out.

delete async

Executes a DELETE HTTP request.

Parameters:

Name Type Description Default
url str

The unencoded request URL.

required
headers Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None

The request headers.

None
timeout float | None

The timeout for the request in seconds.

None

Raises:

Type Description
ConnectionError

If the connection fails.

TimeoutError

If the request times out.

head async

Executes a HEAD HTTP request.

Parameters:

Name Type Description Default
url str

The unencoded request URL.

required
headers Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None

The request headers.

None
timeout float | None

The timeout for the request in seconds.

None

Raises:

Type Description
ConnectionError

If the connection fails.

TimeoutError

If the request times out.

options async

Executes a OPTIONS HTTP request.

Parameters:

Name Type Description Default
url str

The unencoded request URL.

required
headers Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None

The request headers.

None
timeout float | None

The timeout for the request in seconds.

None

Raises:

Type Description
ConnectionError

If the connection fails.

TimeoutError

If the request times out.

patch async

Executes a PATCH HTTP request.

Parameters:

Name Type Description Default
url str

The unencoded request URL.

required
headers Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None

The request headers.

None
content bytes | AsyncIterator[bytes] | None

The request content.

None
timeout float | None

The timeout for the request in seconds.

None

Raises:

Type Description
ConnectionError

If the connection fails.

TimeoutError

If the request times out.

put async

Executes a PUT HTTP request.

Parameters:

Name Type Description Default
url str

The unencoded request URL.

required
headers Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None

The request headers.

None
content bytes | AsyncIterator[bytes] | None

The request content.

None
timeout float | None

The timeout for the request in seconds.

None

Raises:

Type Description
ConnectionError

If the connection fails.

TimeoutError

If the request times out.

execute async

Executes an HTTP request, returning the full buffered response.

Parameters:

Name Type Description Default
method str

The HTTP method.

required
url str

The unencoded request URL.

required
headers Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None

The request headers.

None
content bytes | AsyncIterator[bytes] | None

The request content.

None
timeout float | None

The timeout for the request in seconds.

None

Raises:

Type Description
ConnectionError

If the connection fails.

TimeoutError

If the request times out.

stream async

Executes an HTTP request, allowing the response content to be streamed.

Parameters:

Name Type Description Default
method str

The HTTP method.

required
url str

The unencoded request URL.

required
headers Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None

The request headers.

None
content bytes | AsyncIterator[bytes] | None

The request content.

None
timeout float | None

The timeout for the request in seconds.

None

Raises:

Type Description
ConnectionError

If the connection fails.

TimeoutError

If the request times out.

pyqwest.HTTPTransport

An HTTP transport implementation using reqwest.

Without any arguments, the transport behaves like a raw, low-level HTTP transport, with no timeouts or other higher level behavior. When creating a transport, take care to set options to meet your needs. Also consider using get_default_transport instead which is preconfigured with reasonable defaults, though does not support custom TLS certificates.

Parameters:

Name Type Description Default
tls_ca_cert bytes | None

The CA certificate to use to verify the server for TLS connections.

None
tls_key bytes | None

The client private key to identify the client for mTLS connections. tls_cert must also be set.

None
tls_cert bytes | None

The client certificate to identify the client for mTLS connections. tls_key must also be set.

None
http_version HTTPVersion | None

The HTTP version to use for requests. If unset, HTTP/1 is used for plaintext and ALPN negotiates the version for TLS connections which typically means HTTP/2 if the server supports it.

None
timeout float | None

Default timeout for requests in seconds. This is the timeout from the start of the request to the end of the response.

None
connect_timeout float | None

Timeout for connection establishment in seconds.

None
read_timeout float | None

Timeout for each read operation of a request in seconds.

None
pool_idle_timeout float | None

Timeout for idle connections in the connection pool in seconds.

None
pool_max_idle_per_host int | None

Maximum number of idle connections to keep in the pool per host. Defaults to 2.

None
tcp_keepalive_interval float | None

Interval for TCP keepalive probes in seconds.

None
enable_gzip bool

Whether to enable gzip decompression for responses.

False
enable_brotli bool

Whether to enable brotli decompression for responses.

False
enable_zstd bool

Whether to enable zstd decompression for responses.

False
use_system_dns bool

Whether to use the system DNS resolver. By default, pyqwest uses an asynchronous DNS resolver implemented in Rust, but it can have different behavior from system DNS in certain environments. Try enabling this option if you have any DNS resolution issues.

False

__aenter__

Enters the context manager for the transport to automatically close it when leaving.

__aexit__

Exits the context manager for the transport, closing it.

execute

Executes the given request, returning the response.

Parameters:

Name Type Description Default
request Request

The request to execute.

required

Raises:

Type Description
ConnectionError

If the connection fails.

TimeoutError

If the request times out.

ReadError

If an error occurs reading the response.

WriteError

If an error occurs writing the request.

aclose

Closes the transport, releasing any underlying resources.

pyqwest.get_default_transport builtin

Returns the singleton default HTTP transport instance used by clients that do not specify a transport.

The default transport is constructed as follows:

HTTPTransport(
    connect_timeout=30.0,
    pool_idle_timeout=90.0,
    pool_max_idle_per_host=2,
    tcp_keepalive_interval=30.0,
    enable_gzip: bool = True,
    enable_brotli: bool = True,
    enable_zstd: bool = True,
)

pyqwest.Request

An HTTP request.

Parameters:

Name Type Description Default
method str

The HTTP method.

required
url str

The unencoded request URL.

required
headers Headers | None

The request headers.

None
content bytes | AsyncIterator[bytes] | None

The request content.

None

method property

Returns the HTTP method of the request.

url property

Returns the unencoded request URL.

headers property

Returns the request headers.

content property

Returns an async iterator over the request content.

pyqwest.Response

An HTTP response.

Care must be taken if your service uses trailers and you override content. Trailers will not be received without fully consuming the original response content. Patterns that wrap the original response content should not have any issue but if you replace it completely and need trailers, make sure to still read and discard the original content.

Parameters:

Name Type Description Default
status int

The HTTP status code of the response.

required
http_version HTTPVersion | None

The HTTP version of the response.

None
headers Headers | None

The response headers.

None
content bytes | AsyncIterator[Buffer] | None

The response content.

None
trailers Headers | None

The response trailers.

None

status property

Returns the HTTP status code of the response.

http_version property

Returns the HTTP version of the response.

headers property

Returns the response headers.

content property

Returns an asynchronous iterator over the response content.

trailers property

Returns the response trailers.

Because trailers complete the response, this will only be filled after fully consuming the content iterator.

__aenter__

Enters the context manager for the response to automatically close it when leaving.

Note that if your code is guaranteed to fully consume the response content, it is not necessary to explicitly close the response.

__aexit__

Exits the context manager for the response, closing it.

aclose

Closes the response, releasing any underlying resources.

Note that if your code is guaranteed to fully consume the response content, it is not necessary to explicitly close the response.

pyqwest.SyncClient

A synchronous HTTP client.

A client is a lightweight wrapper around a SyncTransport, providing convenience methods for common HTTP operations with buffering.

Parameters:

Name Type Description Default
transport SyncTransport | None

The transport to use for requests. If None, the shared default transport will be used.

None

get

Executes a GET HTTP request.

Parameters:

Name Type Description Default
url str

The unencoded request URL.

required
headers Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None

The request headers.

None
timeout float | None

The timeout for the request in seconds.

None

Raises:

Type Description
ConnectionError

If the connection fails.

TimeoutError

If the request times out.

ReadError

If an error occurs reading the response.

WriteError

If an error occurs writing the request.

post

Executes a POST HTTP request.

Parameters:

Name Type Description Default
url str

The unencoded request URL.

required
headers Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None

The request headers.

None
content bytes | Iterable[bytes] | None

The request content.

None
timeout float | None

The timeout for the request in seconds.

None

Raises:

Type Description
ConnectionError

If the connection fails.

TimeoutError

If the request times out.

ReadError

If an error occurs reading the response.

WriteError

If an error occurs writing the request.

delete

Executes a DELETE HTTP request.

Parameters:

Name Type Description Default
url str

The unencoded request URL.

required
headers Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None

The request headers.

None
timeout float | None

The timeout for the request in seconds.

None

Raises:

Type Description
ConnectionError

If the connection fails.

TimeoutError

If the request times out.

ReadError

If an error occurs reading the response.

WriteError

If an error occurs writing the request.

head

Executes a HEAD HTTP request.

Parameters:

Name Type Description Default
url str

The unencoded request URL.

required
headers Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None

The request headers.

None
timeout float | None

The timeout for the request in seconds.

None

Raises:

Type Description
ConnectionError

If the connection fails.

TimeoutError

If the request times out.

ReadError

If an error occurs reading the response.

WriteError

If an error occurs writing the request.

options

Executes a OPTIONS HTTP request.

Parameters:

Name Type Description Default
url str

The unencoded request URL.

required
headers Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None

The request headers.

None
timeout float | None

The timeout for the request in seconds.

None

Raises:

Type Description
ConnectionError

If the connection fails.

TimeoutError

If the request times out.

ReadError

If an error occurs reading the response.

WriteError

If an error occurs writing the request.

patch

Executes a PATCH HTTP request.

Parameters:

Name Type Description Default
url str

The unencoded request URL.

required
headers Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None

The request headers.

None
content bytes | Iterable[bytes] | None

The request content.

None
timeout float | None

The timeout for the request in seconds.

None

Raises:

Type Description
ConnectionError

If the connection fails.

TimeoutError

If the request times out.

ReadError

If an error occurs reading the response.

WriteError

If an error occurs writing the request.

put

Executes a PUT HTTP request.

Parameters:

Name Type Description Default
url str

The unencoded request URL.

required
headers Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None

The request headers.

None
content bytes | Iterable[bytes] | None

The request content.

None
timeout float | None

The timeout for the request in seconds.

None

Raises:

Type Description
ConnectionError

If the connection fails.

TimeoutError

If the request times out.

ReadError

If an error occurs reading the response.

WriteError

If an error occurs writing the request.

execute

Executes an HTTP request, returning the full buffered response.

Parameters:

Name Type Description Default
method str

The HTTP method.

required
url str

The unencoded request URL.

required
headers Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None

The request headers.

None
content bytes | Iterable[bytes] | None

The request content.

None
timeout float | None

The timeout for the request in seconds.

None

Raises:

Type Description
ConnectionError

If the connection fails.

TimeoutError

If the request times out.

ReadError

If an error occurs reading the response.

WriteError

If an error occurs writing the request.

stream

Executes an HTTP request, allowing the response content to be streamed.

Parameters:

Name Type Description Default
method str

The HTTP method.

required
url str

The unencoded request URL.

required
headers Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None

The request headers.

None
content bytes | Iterable[bytes] | None

The request content.

None
timeout float | None

The timeout for the request in seconds.

None

Raises:

Type Description
ConnectionError

If the connection fails.

TimeoutError

If the request times out.

ReadError

If an error occurs reading the response.

WriteError

If an error occurs writing the request.

pyqwest.SyncHTTPTransport

An HTTP transport implementation using reqwest.

Without any arguments, the transport behaves like a raw, low-level HTTP transport, with no timeouts or other higher level behavior. When creating a transport, take care to set options to meet your needs. Also consider using get_default_transport instead which is preconfigured with reasonable defaults, though does not support custom TLS certificates.

Parameters:

Name Type Description Default
tls_ca_cert bytes | None

The CA certificate to use to verify the server for TLS connections.

None
tls_key bytes | None

The client private key to identify the client for mTLS connections. tls_cert must also be set.

None
tls_cert bytes | None

The client certificate to identify the client for mTLS connections. tls_key must also be set.

None
http_version HTTPVersion | None

The HTTP version to use for requests. If unset, HTTP/1 is used for plaintext and ALPN negotiates the version for TLS connections which typically means HTTP/2 if the server supports it.

None
timeout float | None

Default timeout for requests in seconds. This is the timeout from the start of the request to the end of the response.

None
connect_timeout float | None

Timeout for connection establishment in seconds.

None
read_timeout float | None

Timeout for each read operation of a request in seconds.

None
pool_idle_timeout float | None

Timeout for idle connections in the connection pool in seconds.

None
pool_max_idle_per_host int | None

Maximum number of idle connections to keep in the pool per host. Defaults to 2.

None
tcp_keepalive_interval float | None

Interval for TCP keepalive probes in seconds.

None
enable_gzip bool

Whether to enable gzip decompression for responses.

False
enable_brotli bool

Whether to enable brotli decompression for responses.

False
enable_zstd bool

Whether to enable zstd decompression for responses.

False
use_system_dns bool

Whether to use the system DNS resolver. By default, pyqwest uses an asynchronous DNS resolver implemented in Rust, but it can have different behavior from system DNS in certain environments. Try enabling this option if you have any DNS resolution issues.

False

__enter__

Enters the context manager for the transport to automatically close it when leaving.

__exit__

Exits the context manager for the transport, closing it.

execute_sync

Executes the given request, returning the response.

Parameters:

Name Type Description Default
request SyncRequest

The request to execute.

required

close

Closes the transport, releasing any underlying resources.

pyqwest.get_default_sync_transport builtin

Returns the singleton default HTTP transport instance used by synchronous clients that do not specify a transport.ult HTTP transport instance used by clients that do not specify a transport.

The default transport is constructed as follows:

SyncHTTPTransport(
    connect_timeout=30.0,
    pool_idle_timeout=90.0,
    pool_max_idle_per_host=2,
    tcp_keepalive_interval=30.0,
    enable_gzip: bool = True,
    enable_brotli: bool = True,
    enable_zstd: bool = True,
)

pyqwest.SyncRequest

An HTTP request.

Parameters:

Name Type Description Default
method str

The HTTP method.

required
url str

The unencoded request URL.

required
headers Headers | None

The request headers.

None
content bytes | Iterable[bytes] | None

The request content.

None
timeout

The timeout for the request in seconds.

required

method property

Returns the HTTP method of the request.

url property

Returns the unencoded request URL.

headers property

Returns the request headers.

content property

Returns an iterator over the request content.

pyqwest.SyncResponse

An HTTP response.

Care must be taken if your service uses trailers and you override content. Trailers will not be received without fully consuming the original response content. Patterns that wrap the original response content should not have any issue but if you replace it completely and need trailers, make sure to still read and discard the original content.

Parameters:

Name Type Description Default
status int

The HTTP status code of the response.

required
http_version HTTPVersion | None

The HTTP version of the response.

None
headers Headers | None

The response headers.

None
content bytes | Iterable[Buffer] | None

The response content.

None
trailers Headers | None

The response trailers.

None

status property

Returns the HTTP status code of the response.

http_version property

Returns the HTTP version of the response.

headers property

Returns the response headers.

content property

Returns an iterator over the response content.

trailers property

Returns the response trailers.

Because trailers complete the response, this will only be filled after fully consuming the content iterator.

__enter__

Enters the context manager for the response to automatically close it when leaving.

Note that if your code is guaranteed to fully consume the response content, it is not necessary to explicitly close the response.

__exit__

Exits the context manager for the response, closing it.

close

Closes the response, releasing any underlying resources.

Note that if your code is guaranteed to fully consume the response content, it is not necessary to explicitly close the response.

pyqwest.Headers

Container of HTTP headers.

This class behaves like a dictionary with case-insensitive keys and string values. Standard dictionary access will act as if keys can only have a single value. The add method can be used to It additionally can be used to store multiple values for the same key by using the add method. Iterating over values or items will return all values, including duplicates.

Parameters:

Name Type Description Default
items Mapping[str, str] | Iterable[tuple[str, str]] | None

Initial headers to add.

None

__getitem__

Return the header value for the key.

If multiple values are present for the key, returns the first value.

Parameters:

Name Type Description Default
key str

The header name.

required

Raises:

Type Description
KeyError

If the key is not present.

__setitem__

Sets the header value for the key, replacing any existing values.

Parameters:

Name Type Description Default
key str

The header name.

required
value str

The header value.

required

__delitem__

Deletes all values for the key.

Parameters:

Name Type Description Default
key str

The header name.

required

Raises:

Type Description
KeyError

If the key is not present.

__iter__

Returns an iterator over the header names.

__len__

Returns the number of unique header names.

__eq__

Compares the headers for equality with another Headers object, mapping, or iterable of key-value pairs.

Parameters:

Name Type Description Default
other object

The object to compare against.

required

get

Returns the header value for the key, or default if not present.

Parameters:

Name Type Description Default
key str

The header name.

required
default str | None

The default value to return if the key is not present.

None

popitem

Removes and returns an arbitrary (name, value) pair. Will return the same name multiple times if it has multiple values.

Raises:

Type Description
KeyError

If the headers are empty.

setdefault

If the key is not present, sets it to the default value. Returns the value for the key.

Parameters:

Name Type Description Default
key str

The header name.

required
default str | None

The default value to set and return if the key is not present.

None

add

Adds a header value for the key. Existing values are preserved.

Parameters:

Name Type Description Default
key str

The header name.

required
value str

The header value.

required

clear

Removes all headers.

getall

Returns all header values for the key.

Parameters:

Name Type Description Default
key str

The header name.

required

items

Returns a new view of all header name-value pairs, including duplicates.

keys

Returns a new view of all unique header names.

values

Returns a new view of all header values, including duplicates.

__contains__

Returns True if the header name is present.

Parameters:

Name Type Description Default
key object

The header name.

required

pyqwest.FullResponse

A fully buffered HTTP response.

Parameters:

Name Type Description Default
status int

The HTTP status code of the response.

required
headers Headers

The response headers.

required
content bytes

The response content.

required
trailers Headers

The response trailers.

required

status property

Returns the HTTP status code of the response.

headers property

Returns the response headers.

content property

Returns the response content.

trailers property

Returns the response trailers.

text

Returns the response content decoded as text.

The encoding for decoding is determined from the content-type header if present, defaulting to UTF-8 otherwise.

json

Parses and returns the response content as JSON.

The content-type header is not checked when using this method.