Async Client

These APIs should be used in asyncio based apps. For synchronous applications, use synchronous APIs.

`pyqwest.Client`

An asynchronous HTTP client.

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

The asynchronous client does not expose per-request timeouts on its methods. Use asyncio.wait_for or similar to enforce timeouts per-requests or initialize HTTPTransport with a default timeout.

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`
`params`	`_QueryParams \| None`	Query parameters to append to the URL. None values will be treated as key-only.	`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` `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`	`_RequestContent \| None`	The request content. A Python dictionary will be converted to JSON.	`None`
`params`	`_QueryParams \| None`	Query parameters to append to the URL. None values will be treated as key-only.	`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` `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`
`params`	`_QueryParams \| None`	Query parameters to append to the URL. None values will be treated as key-only.	`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` `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`
`params`	`_QueryParams \| None`	Query parameters to append to the URL. None values will be treated as key-only.	`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` `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`
`params`	`_QueryParams \| None`	Query parameters to append to the URL. None values will be treated as key-only.	`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` `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`	`_RequestContent \| None`	The request content. A Python dictionary will be converted to JSON.	`None`
`params`	`_QueryParams \| None`	Query parameters to append to the URL. None values will be treated as key-only.	`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` `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`	`_RequestContent \| None`	The request content. A Python dictionary will be converted to JSON.	`None`
`params`	`_QueryParams \| None`	Query parameters to append to the URL. None values will be treated as key-only.	`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` `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`	`_RequestContent \| None`	The request content. A Python dictionary will be converted to JSON.	`None`
`params`	`_QueryParams \| None`	Query parameters to append to the URL. None values will be treated as key-only.	`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` `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`	`_RequestContent \| None`	The request content. A Python dictionary will be converted to JSON.	`None`
`params`	`_QueryParams \| None`	Query parameters to append to the URL. None values will be treated as key-only.	`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.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`	`_RequestContent \| None`	The request content. A Python dictionary will be converted to JSON.	`None`
`params`	`_QueryParams \| None`	Query parameters to append to the URL. None values will be treated as key-only.	`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.Transport`

Bases: Protocol

Protocol for asynchronous HTTP transport implementations.

The default implementation of Transport is HTTPTransport which issues requests. Custom implementations may be useful to:

Mock requests for testing.
Add middleware wrapping transports

`execute`

Executes a request.

`pyqwest.HTTPTransport`

An HTTP transport implementation using reqwest.

Without any arguments, the transport behaves like the default transport. When creating a transport, take care to set options to meet your needs.

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.	`30.0`
`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.	`90.0`
`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.	`30.0`
`enable_gzip`	`bool`	Whether to enable gzip decompression for responses.	`True`
`enable_brotli`	`bool`	Whether to enable brotli decompression for responses.	`True`
`enable_zstd`	`bool`	Whether to enable zstd decompression for responses.	`True`
`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`
`enable_cookie_store`	`bool`	Whether to enable automatic cookie storage and sending. When enabled, the transport will automatically store cookies from responses and send them with subsequent requests.	`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`

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,
    tcp_keepalive_interval=30.0,
    enable_gzip: bool = True,
    enable_brotli: bool = True,
    enable_zstd: bool = True,
)

Async Client

pyqwest.Client

get async

post async

delete async

head async

options async

patch async

put async

execute async

stream async

pyqwest.Request

method property

url property

headers property

content property

pyqwest.Transport

execute

pyqwest.HTTPTransport

__aenter__

__aexit__

execute

aclose

pyqwest.get_default_transport

`pyqwest.Client`

`get` `async`

`post` `async`

`delete` `async`

`head` `async`

`options` `async`

`patch` `async`

`put` `async`

`execute` `async`

`stream` `async`

`pyqwest.Request`

`method` `property`

`url` `property`

`headers` `property`

`content` `property`

`pyqwest.Transport`

`execute`

`pyqwest.HTTPTransport`

`aenter`

`aexit`

`execute`

`aclose`

`pyqwest.get_default_transport`