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
|
|
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
|
|
The unencoded request URL. |
required |
headers
|
|
The request headers. |
None
|
timeout
|
|
The timeout for the request in seconds. |
None
|
Raises:
| Type | Description |
|---|---|
|
If the connection fails. |
|
If the request times out. |
post
async
Executes a POST HTTP request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url
|
|
The unencoded request URL. |
required |
headers
|
|
The request headers. |
None
|
content
|
|
The request content. |
None
|
timeout
|
|
The timeout for the request in seconds. |
None
|
Raises:
| Type | Description |
|---|---|
|
If the connection fails. |
|
If the request times out. |
delete
async
Executes a DELETE HTTP request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url
|
|
The unencoded request URL. |
required |
headers
|
|
The request headers. |
None
|
timeout
|
|
The timeout for the request in seconds. |
None
|
Raises:
| Type | Description |
|---|---|
|
If the connection fails. |
|
If the request times out. |
head
async
Executes a HEAD HTTP request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url
|
|
The unencoded request URL. |
required |
headers
|
|
The request headers. |
None
|
timeout
|
|
The timeout for the request in seconds. |
None
|
Raises:
| Type | Description |
|---|---|
|
If the connection fails. |
|
If the request times out. |
options
async
Executes a OPTIONS HTTP request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url
|
|
The unencoded request URL. |
required |
headers
|
|
The request headers. |
None
|
timeout
|
|
The timeout for the request in seconds. |
None
|
Raises:
| Type | Description |
|---|---|
|
If the connection fails. |
|
If the request times out. |
patch
async
Executes a PATCH HTTP request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url
|
|
The unencoded request URL. |
required |
headers
|
|
The request headers. |
None
|
content
|
|
The request content. |
None
|
timeout
|
|
The timeout for the request in seconds. |
None
|
Raises:
| Type | Description |
|---|---|
|
If the connection fails. |
|
If the request times out. |
put
async
Executes a PUT HTTP request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url
|
|
The unencoded request URL. |
required |
headers
|
|
The request headers. |
None
|
content
|
|
The request content. |
None
|
timeout
|
|
The timeout for the request in seconds. |
None
|
Raises:
| Type | Description |
|---|---|
|
If the connection fails. |
|
If the request times out. |
execute
async
Executes an HTTP request, returning the full buffered response.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
method
|
|
The HTTP method. |
required |
url
|
|
The unencoded request URL. |
required |
headers
|
|
The request headers. |
None
|
content
|
|
The request content. |
None
|
timeout
|
|
The timeout for the request in seconds. |
None
|
Raises:
| Type | Description |
|---|---|
|
If the connection fails. |
|
If the request times out. |
stream
async
Executes an HTTP request, allowing the response content to be streamed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
method
|
|
The HTTP method. |
required |
url
|
|
The unencoded request URL. |
required |
headers
|
|
The request headers. |
None
|
content
|
|
The request content. |
None
|
timeout
|
|
The timeout for the request in seconds. |
None
|
Raises:
| Type | Description |
|---|---|
|
If the connection fails. |
|
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
|
|
The CA certificate to use to verify the server for TLS connections. |
None
|
tls_key
|
|
The client private key to identify the client for mTLS connections. tls_cert must also be set. |
None
|
tls_cert
|
|
The client certificate to identify the client for mTLS connections. tls_key must also be set. |
None
|
http_version
|
|
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
|
|
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
|
|
Timeout for connection establishment in seconds. |
None
|
read_timeout
|
|
Timeout for each read operation of a request in seconds. |
None
|
pool_idle_timeout
|
|
Timeout for idle connections in the connection pool in seconds. |
None
|
pool_max_idle_per_host
|
|
Maximum number of idle connections to keep in the pool per host. Defaults to 2. |
None
|
tcp_keepalive_interval
|
|
Interval for TCP keepalive probes in seconds. |
None
|
enable_gzip
|
|
Whether to enable gzip decompression for responses. |
False
|
enable_brotli
|
|
Whether to enable brotli decompression for responses. |
False
|
enable_zstd
|
|
Whether to enable zstd decompression for responses. |
False
|
use_system_dns
|
|
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
|
|
The request to execute. |
required |
Raises:
| Type | Description |
|---|---|
|
If the connection fails. |
|
If the request times out. |
|
If an error occurs reading the response. |
|
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:
pyqwest.Request
An HTTP request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
method
|
|
The HTTP method. |
required |
url
|
|
The unencoded request URL. |
required |
headers
|
|
The request headers. |
None
|
content
|
|
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
|
|
The HTTP status code of the response. |
required |
http_version
|
|
The HTTP version of the response. |
None
|
headers
|
|
The response headers. |
None
|
content
|
|
The response content. |
None
|
trailers
|
|
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
|
|
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
|
|
The unencoded request URL. |
required |
headers
|
|
The request headers. |
None
|
timeout
|
|
The timeout for the request in seconds. |
None
|
Raises:
| Type | Description |
|---|---|
|
If the connection fails. |
|
If the request times out. |
|
If an error occurs reading the response. |
|
If an error occurs writing the request. |
post
Executes a POST HTTP request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url
|
|
The unencoded request URL. |
required |
headers
|
|
The request headers. |
None
|
content
|
|
The request content. |
None
|
timeout
|
|
The timeout for the request in seconds. |
None
|
Raises:
| Type | Description |
|---|---|
|
If the connection fails. |
|
If the request times out. |
|
If an error occurs reading the response. |
|
If an error occurs writing the request. |
delete
Executes a DELETE HTTP request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url
|
|
The unencoded request URL. |
required |
headers
|
|
The request headers. |
None
|
timeout
|
|
The timeout for the request in seconds. |
None
|
Raises:
| Type | Description |
|---|---|
|
If the connection fails. |
|
If the request times out. |
|
If an error occurs reading the response. |
|
If an error occurs writing the request. |
head
Executes a HEAD HTTP request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url
|
|
The unencoded request URL. |
required |
headers
|
|
The request headers. |
None
|
timeout
|
|
The timeout for the request in seconds. |
None
|
Raises:
| Type | Description |
|---|---|
|
If the connection fails. |
|
If the request times out. |
|
If an error occurs reading the response. |
|
If an error occurs writing the request. |
options
Executes a OPTIONS HTTP request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url
|
|
The unencoded request URL. |
required |
headers
|
|
The request headers. |
None
|
timeout
|
|
The timeout for the request in seconds. |
None
|
Raises:
| Type | Description |
|---|---|
|
If the connection fails. |
|
If the request times out. |
|
If an error occurs reading the response. |
|
If an error occurs writing the request. |
patch
Executes a PATCH HTTP request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url
|
|
The unencoded request URL. |
required |
headers
|
|
The request headers. |
None
|
content
|
|
The request content. |
None
|
timeout
|
|
The timeout for the request in seconds. |
None
|
Raises:
| Type | Description |
|---|---|
|
If the connection fails. |
|
If the request times out. |
|
If an error occurs reading the response. |
|
If an error occurs writing the request. |
put
Executes a PUT HTTP request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url
|
|
The unencoded request URL. |
required |
headers
|
|
The request headers. |
None
|
content
|
|
The request content. |
None
|
timeout
|
|
The timeout for the request in seconds. |
None
|
Raises:
| Type | Description |
|---|---|
|
If the connection fails. |
|
If the request times out. |
|
If an error occurs reading the response. |
|
If an error occurs writing the request. |
execute
Executes an HTTP request, returning the full buffered response.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
method
|
|
The HTTP method. |
required |
url
|
|
The unencoded request URL. |
required |
headers
|
|
The request headers. |
None
|
content
|
|
The request content. |
None
|
timeout
|
|
The timeout for the request in seconds. |
None
|
Raises:
| Type | Description |
|---|---|
|
If the connection fails. |
|
If the request times out. |
|
If an error occurs reading the response. |
|
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
|
|
The HTTP method. |
required |
url
|
|
The unencoded request URL. |
required |
headers
|
|
The request headers. |
None
|
content
|
|
The request content. |
None
|
timeout
|
|
The timeout for the request in seconds. |
None
|
Raises:
| Type | Description |
|---|---|
|
If the connection fails. |
|
If the request times out. |
|
If an error occurs reading the response. |
|
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
|
|
The CA certificate to use to verify the server for TLS connections. |
None
|
tls_key
|
|
The client private key to identify the client for mTLS connections. tls_cert must also be set. |
None
|
tls_cert
|
|
The client certificate to identify the client for mTLS connections. tls_key must also be set. |
None
|
http_version
|
|
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
|
|
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
|
|
Timeout for connection establishment in seconds. |
None
|
read_timeout
|
|
Timeout for each read operation of a request in seconds. |
None
|
pool_idle_timeout
|
|
Timeout for idle connections in the connection pool in seconds. |
None
|
pool_max_idle_per_host
|
|
Maximum number of idle connections to keep in the pool per host. Defaults to 2. |
None
|
tcp_keepalive_interval
|
|
Interval for TCP keepalive probes in seconds. |
None
|
enable_gzip
|
|
Whether to enable gzip decompression for responses. |
False
|
enable_brotli
|
|
Whether to enable brotli decompression for responses. |
False
|
enable_zstd
|
|
Whether to enable zstd decompression for responses. |
False
|
use_system_dns
|
|
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
|
|
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:
pyqwest.SyncRequest
An HTTP request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
method
|
|
The HTTP method. |
required |
url
|
|
The unencoded request URL. |
required |
headers
|
|
The request headers. |
None
|
content
|
|
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
|
|
The HTTP status code of the response. |
required |
http_version
|
|
The HTTP version of the response. |
None
|
headers
|
|
The response headers. |
None
|
content
|
|
The response content. |
None
|
trailers
|
|
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
|
|
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
|
|
The header name. |
required |
Raises:
| Type | Description |
|---|---|
|
If the key is not present. |
__setitem__
Sets the header value for the key, replacing any existing values.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
|
The header name. |
required |
value
|
|
The header value. |
required |
__delitem__
Deletes all values for the key.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
|
The header name. |
required |
Raises:
| Type | Description |
|---|---|
|
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
|
|
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
|
|
The header name. |
required |
default
|
|
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 |
|---|---|
|
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
|
|
The header name. |
required |
default
|
|
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
|
|
The header name. |
required |
value
|
|
The header value. |
required |
clear
Removes all headers.
getall
Returns all header values for the key.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
|
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
|
|
The header name. |
required |
pyqwest.FullResponse
A fully buffered HTTP response.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
status
|
|
The HTTP status code of the response. |
required |
headers
|
|
The response headers. |
required |
content
|
|
The response content. |
required |
trailers
|
|
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.