Sync Client

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

`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`
`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.
`RemoteProtocolError`	If the peer violates the HTTP protocol.
`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`	`_SyncRequestContent \| None`	The request content. A Python dictionary will be converted to JSON and a SyncMultipart will be sent as a multipart form.	`None`
`timeout`	`float \| None`	The timeout for the request in seconds.	`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.
`RemoteProtocolError`	If the peer violates the HTTP protocol.
`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`
`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.
`RemoteProtocolError`	If the peer violates the HTTP protocol.
`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`
`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.
`RemoteProtocolError`	If the peer violates the HTTP protocol.
`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`
`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.
`RemoteProtocolError`	If the peer violates the HTTP protocol.
`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`	`_SyncRequestContent \| None`	The request content. A Python dictionary will be converted to JSON and a SyncMultipart will be sent as a multipart form.	`None`
`timeout`	`float \| None`	The timeout for the request in seconds.	`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.
`RemoteProtocolError`	If the peer violates the HTTP protocol.
`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`	`_SyncRequestContent \| None`	The request content. A Python dictionary will be converted to JSON and a SyncMultipart will be sent as a multipart form.	`None`
`timeout`	`float \| None`	The timeout for the request in seconds.	`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.
`RemoteProtocolError`	If the peer violates the HTTP protocol.
`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`	`_SyncRequestContent \| None`	The request content. A Python dictionary will be converted to JSON and a SyncMultipart will be sent as a multipart form.	`None`
`timeout`	`float \| None`	The timeout for the request in seconds.	`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.
`RemoteProtocolError`	If the peer violates the HTTP protocol.
`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`	`_SyncRequestContent \| None`	The request content. A Python dictionary will be converted to JSON and a SyncMultipart will be sent as a multipart form.	`None`
`timeout`	`float \| None`	The timeout for the request in seconds.	`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.
`RemoteProtocolError`	If the peer violates the HTTP protocol.
`ReadError`	If an error occurs reading the response.
`WriteError`	If an error occurs writing the request.

`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`	`_SyncRequestContent \| None`	The request content. A Python dictionary will be converted to JSON and a SyncMultipart will be sent as a multipart form.	`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 iterator over the request content.

`pyqwest.SyncMultipart`

Multipart form request content for synchronous requests. For asynchronous requests, use Multipart.

Passing a SyncMultipart object as request content encodes it into the request content as a multipart/form-data request. The multipart boundary is generated when constructing the request, and the request uses a copy of the provided headers with the content-type header set to match the boundary. The provided headers must not have a content-type other than multipart/form-data.

Parameters:

Name	Type	Description	Default
`parts`	`Mapping[str, SyncPart \| bytes \| str] \| Iterable[tuple[str, SyncPart \| bytes \| str]]`	The named parts of the form. bytes or str values are converted to parts without a filename or headers.	required

`parts` `property`

Returns the named parts of the form.

`pyqwest.SyncPart`

A single part of a multipart form, for use with SyncMultipart.

Parameters:

Name	Type	Description	Default
`content`	`bytes \| str \| Iterable[bytes]`	The content of the part. A str will be encoded as UTF-8. An iterable of bytes will be streamed.	required
`filename`	`str \| None`	The filename to send in the part's content-disposition header.	`None`
`headers`	`_PartHeaders \| None`	Additional headers to send with the part, for example content-type.	`None`

Raises:

Type	Description
`ValueError`	If a header name or value is invalid.

`content` `property`

Returns the content of the part.

`filename` `property`

Returns the filename of the part.

`headers` `property`

Returns the headers of the part.

`pyqwest.SyncTransport`

Bases: Protocol

Protocol for synchronous HTTP transport implementations.

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

Mock requests for testing.
Add middleware wrapping transports

`execute_sync`

Executes a request.

`pyqwest.SyncHTTPTransport`

An HTTP transport implementation using reqwest.

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

Parameters:

Name	Type	Description	Default
`tls_ca_cert`	`bytes \| None`	The PEM-encoded CA certificate(s) to use to verify the server for TLS connections.	`None`
`tls_include_system_certs`	`bool`	Whether to include the system CA certificates to verify TLS connections. If this is unset and tls_ca_cert is not provided, TLS will not function.	`False`
`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`
`proxy`	`str \| Proxy \| Sequence[str \| Proxy] \| None`	A proxy to send requests through. A URL string such as "http://localhost:8030" proxies all requests, equivalent to Proxy(url). Pass a Proxy object to configure authentication, extra headers, or routing rules, or a sequence of them to apply multiple proxy rules, where the first matching proxy is used for each request. An empty sequence, like None, configures no explicit proxy, in which case proxy environment variables such as HTTP_PROXY still apply.	`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`
`follow_redirects`	`bool`	Whether to automatically follow redirect responses. When disabled, which is the default, redirect responses are returned as-is. Leave this disabled when the transport is used through pyqwest.httpx, because httpx clients apply their own follow_redirects setting and track redirects in response.history.	`True`
`max_redirects`	`int`	Maximum number of redirects to follow when follow_redirects is enabled. A request exceeding it fails with TooManyRedirects.	`10`

`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`

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

Sync Client

pyqwest.SyncClient

get

post

delete

head

options

patch

put

execute

stream

pyqwest.SyncRequest

method property

url property

headers property

content property

pyqwest.SyncMultipart

parts property

pyqwest.SyncPart

content property

filename property

headers property

pyqwest.SyncTransport

execute_sync

pyqwest.SyncHTTPTransport

__enter__

__exit__

execute_sync

close

pyqwest.get_default_sync_transport

`pyqwest.SyncClient`

`get`

`post`

`delete`

`head`

`options`

`patch`

`put`

`execute`

`stream`

`pyqwest.SyncRequest`

`method` `property`

`url` `property`

`headers` `property`

`content` `property`

`pyqwest.SyncMultipart`

`parts` `property`

`pyqwest.SyncPart`

`content` `property`

`filename` `property`

`headers` `property`

`pyqwest.SyncTransport`

`execute_sync`

`pyqwest.SyncHTTPTransport`

`enter`

`exit`

`execute_sync`

`close`

`pyqwest.get_default_sync_transport`