hermes-chatto-plugin/vendor/platform/macos-arm64/pyqwest/_pyqwest.pyi

import datetime
from collections.abc import (
    AsyncIterator,
    Awaitable,
    ItemsView,
    Iterable,
    Iterator,
    KeysView,
    Mapping,
    Sequence,
    ValuesView,
)
from contextlib import AbstractContextManager
from types import TracebackType
from typing import (
    Literal,
    Protocol,
    TypeAlias,
    TypeVar,
    final,
    overload,
    runtime_checkable,
)

from opentelemetry.metrics import MeterProvider
from opentelemetry.trace import TracerProvider

from ._multipart import Multipart, SyncMultipart

_T = TypeVar("_T")
_JSON: TypeAlias = (
    Mapping[str, _JSON] | Sequence[_JSON] | str | int | float | bool | None
)
_RequestContent: TypeAlias = (
    bytes | AsyncIterator[bytes] | Mapping[str, _JSON] | Multipart
)
_SyncRequestContent: TypeAlias = (
    bytes | Iterable[bytes] | Mapping[str, _JSON] | SyncMultipart
)

_Buffer: TypeAlias = bytes | memoryview | bytearray
_QueryParams: TypeAlias = dict[str, str | None] | Iterable[tuple[str, str | None]]

@final
class 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.
    """

    def __init__(
        self,
        items: Mapping[str | HTTPHeaderName, str]
        | Iterable[tuple[str | HTTPHeaderName, str]]
        | None = None,
    ) -> None:
        """Creates a new Headers object.

        Args:
            items: Initial headers to add.
        """

    def __getitem__(self, key: str | HTTPHeaderName) -> str:
        """Return the header value for the key.

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

        Args:
            key: The header name.

        Raises:
            KeyError: If the key is not present.
        """

    def __setitem__(self, key: str | HTTPHeaderName, value: str) -> None:
        """Sets the header value for the key, replacing any existing values.

        Args:
            key: The header name.
            value: The header value.
        """

    def __delitem__(self, key: str | HTTPHeaderName) -> None:
        """Deletes all values for the key.

        Args:
            key: The header name.

        Raises:
            KeyError: If the key is not present.
        """

    def __iter__(self) -> Iterator[str]:
        """Returns an iterator over the header names."""

    def __len__(self) -> int:
        """Returns the number of unique header names."""

    def __eq__(self, other: object) -> bool:
        """Compares the headers for equality with another Headers object,
        mapping, or iterable of key-value pairs.

        Args:
            other: The object to compare against.
        """

    def get(self, key: str | HTTPHeaderName, default: _T | None = None) -> str | _T:
        """Returns the header value for the key, or default if not present.

        Args:
            key: The header name.
            default: The default value to return if the key is not present.
        """

    @overload
    def pop(self, key: str | HTTPHeaderName) -> str:
        """Removes and returns the header value for the key.

        Args:
            key: The header name.

        Raises:
            KeyError: If the key is not present.
        """

    @overload
    def pop(self, key: str | HTTPHeaderName, default: _T) -> str | _T:
        """Removes and returns the header value for the key, or default if not present.

        Args:
            key: The header name.
            default: The default value to return if the key is not present.
        """

    def popitem(self) -> tuple[str, str]:
        """Removes and returns an arbitrary (name, value) pair. Will return the same
        name multiple times if it has multiple values.

        Raises:
            KeyError: If the headers are empty.
        """

    def setdefault(self, key: str | HTTPHeaderName, default: str | None = None) -> str:
        """If the key is not present, sets it to the default value.
        Returns the value for the key.

        Args:
            key: The header name.
            default: The default value to set and return if the key is not present.
        """

    def add(self, key: str | HTTPHeaderName, value: str) -> None:
        """Adds a header value for the key. Existing values are preserved.

        Args:
            key: The header name.
            value: The header value.
        """

    @overload
    def update(self, **kwargs: str) -> None:
        """Updates headers from keyword arguments. Existing values are replaced.

        Args:
            **kwargs: Header names and values to set.
        """
    @overload
    def update(
        self,
        items: Mapping[str | HTTPHeaderName, str]
        | Iterable[tuple[str | HTTPHeaderName, str]],
        /,
        **kwargs: str,
    ) -> None:
        """Updates headers with the provided items. Existing values are replaced.

        Args:
            items: Header names and values to set.
            **kwargs: Additional header names and values to set after items. May overwrite items.
        """

    def clear(self) -> None:
        """Removes all headers."""

    def getall(self, key: str | HTTPHeaderName) -> Sequence[str]:
        """Returns all header values for the key.

        Args:
            key: The header name.
        """

    def items(self) -> ItemsView[str, str]:
        """Returns a new view of all header name-value pairs, including duplicates."""

    def keys(self) -> KeysView[str]:
        """Returns a new view of all unique header names."""

    def values(self) -> ValuesView[str]:
        """Returns a new view of all header values, including duplicates."""

    def __contains__(self, key: object) -> bool:
        """Returns True if the header name is present.

        Args:
            key: The header name.
        """

@final
class HTTPVersion:
    """An enumeration of HTTP versions."""

    HTTP1: HTTPVersion
    """HTTP/1.1"""

    HTTP2: HTTPVersion
    """HTTP/2"""

    HTTP3: HTTPVersion
    """HTTP/3"""

    def __eq__(self, other: object) -> bool: ...
    def __ne__(self, other: object) -> bool: ...
    def __lt__(self, other: object) -> bool: ...
    def __le__(self, other: object) -> bool: ...
    def __gt__(self, other: object) -> bool: ...
    def __ge__(self, other: object) -> bool: ...

@final
class Client:
    def __init__(self, transport: Transport | None = None) -> None:
        """Creates a new asynchronous HTTP client.

        The asynchronous client does not expose per-request timeouts on its methods.
        Use `asyncio.wait_for` or similar to enforce timeouts on requests.

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

    def get(
        self,
        url: str,
        headers: Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
        *,
        params: _QueryParams | None = None,
    ) -> Awaitable[FullResponse]:
        """Executes a GET HTTP request.

        Args:
            url: The unencoded request URL.
            headers: The request headers.
            params: Query parameters to append to the URL. None values will be treated as key-only.

        Raises:
            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.
        """

    def post(
        self,
        url: str,
        headers: Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
        content: _RequestContent | None = None,
        *,
        params: _QueryParams | None = None,
    ) -> Awaitable[FullResponse]:
        """Executes a POST HTTP request.

        Args:
            url: The unencoded request URL.
            headers: The request headers.
            content: The request content. A Python dictionary will be converted
                     to JSON and a Multipart will be sent as a multipart form.
            params: Query parameters to append to the URL. None values will be treated as key-only.

        Raises:
            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.
        """

    def delete(
        self,
        url: str,
        headers: Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
        *,
        params: _QueryParams | None = None,
    ) -> Awaitable[FullResponse]:
        """Executes a DELETE HTTP request.

        Args:
            url: The unencoded request URL.
            headers: The request headers.
            params: Query parameters to append to the URL. None values will be treated as key-only.
        Raises:
            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.
        """

    def head(
        self,
        url: str,
        headers: Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
        *,
        params: _QueryParams | None = None,
    ) -> Awaitable[FullResponse]:
        """Executes a HEAD HTTP request.

        Args:
            url: The unencoded request URL.
            headers: The request headers.
            params: Query parameters to append to the URL. None values will be treated as key-only.

        Raises:
            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.
        """

    def options(
        self,
        url: str,
        headers: Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
        *,
        params: _QueryParams | None = None,
    ) -> Awaitable[FullResponse]:
        """Executes a OPTIONS HTTP request.

        Args:
            url: The unencoded request URL.
            headers: The request headers.
            params: Query parameters to append to the URL. None values will be treated as key-only.

        Raises:
            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.
        """

    def patch(
        self,
        url: str,
        headers: Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
        content: _RequestContent | None = None,
        *,
        params: _QueryParams | None = None,
    ) -> Awaitable[FullResponse]:
        """Executes a PATCH HTTP request.

        Args:
            url: The unencoded request URL.
            headers: The request headers.
            content: The request content. A Python dictionary will be converted
                     to JSON and a Multipart will be sent as a multipart form.
            params: Query parameters to append to the URL. None values will be treated as key-only.

        Raises:
            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.
        """

    def put(
        self,
        url: str,
        headers: Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
        content: _RequestContent | None = None,
        *,
        params: _QueryParams | None = None,
    ) -> Awaitable[FullResponse]:
        """Executes a PUT HTTP request.

        Args:
            url: The unencoded request URL.
            headers: The request headers.
            content: The request content. A Python dictionary will be converted
                     to JSON and a Multipart will be sent as a multipart form.
            params: Query parameters to append to the URL. None values will be treated as key-only.

        Raises:
            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.
        """

    def execute(
        self,
        method: str,
        url: str,
        headers: Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
        content: _RequestContent | None = None,
        *,
        params: _QueryParams | None = None,
    ) -> Awaitable[FullResponse]:
        """Executes an HTTP request, returning the full buffered response.

        Args:
            method: The HTTP method.
            url: The unencoded request URL.
            headers: The request headers.
            content: The request content. A Python dictionary will be converted
                     to JSON and a Multipart will be sent as a multipart form.
            params: Query parameters to append to the URL. None values will be treated as key-only.

        Raises:
            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.
        """

    def stream(
        self,
        method: str,
        url: str,
        headers: Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
        content: _RequestContent | None = None,
        *,
        params: _QueryParams | None = None,
    ) -> Awaitable[Response]:
        """Executes an HTTP request, allowing the response content to be streamed.

        Args:
            method: The HTTP method.
            url: The unencoded request URL.
            headers: The request headers.
            content: The request content. A Python dictionary will be converted
                     to JSON and a Multipart will be sent as a multipart form.
            params: Query parameters to append to the URL. None values will be treated as key-only.

        Raises:
            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.
        """

class Proxy:
    """A proxy for transports to route requests through.

    In addition to authentication and extra headers to send to the proxy,
    it allows restricting the requests routed through the proxy by URL
    scheme or exclusion list.
    """

    def __init__(
        self,
        url: str,
        *,
        auth: tuple[str, str] | None = None,
        headers: Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
        no_proxy: str | None = None,
        scheme: Literal["http", "https"] | None = None,
    ) -> None:
        """Creates a new Proxy object.

        Args:
            url: The URL of the proxy, for example "http://localhost:8030".
                 The URL scheme may be http, https, socks5, or socks5h.
                 Credentials in the URL, for example
                 "http://user:pass@localhost:8030", will be used for proxy
                 authentication.
            auth: A (username, password) tuple to use for basic proxy
                  authentication, as an alternative to credentials in the URL.
            headers: Extra headers to send to the proxy.
            no_proxy: A comma-separated list of hosts that should not be proxied.
                      Entries may be IP addresses, optionally with a subnet mask
                      such as "192.168.1.0/24", or domain names which also match
                      all subdomains. The entry "*" matches all hosts.
            scheme: Which request URL scheme to route through the proxy. By default,
                    both http and https requests are proxied.
        """

@runtime_checkable
class Transport(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
    """

    def execute(self, request: Request) -> Awaitable[Response]:
        """Executes a request."""

@final
class HTTPTransport:
    """An HTTP transport implementation using reqwest."""

    def __init__(
        self,
        *,
        tls_ca_cert: bytes | None = None,
        tls_include_system_certs: bool = False,
        tls_key: bytes | None = None,
        tls_cert: bytes | None = None,
        http_version: HTTPVersion | None = None,
        proxy: str | Proxy | Sequence[str | Proxy] | None = None,
        timeout: float | None = None,
        connect_timeout: float | None = 30.0,
        read_timeout: float | None = None,
        pool_idle_timeout: float | None = 90.0,
        pool_max_idle_per_host: int | None = None,
        tcp_keepalive_interval: float | None = 30.0,
        enable_gzip: bool = True,
        enable_brotli: bool = True,
        enable_zstd: bool = True,
        use_system_dns: bool = False,
        enable_cookie_store: bool = False,
        follow_redirects: bool = True,
        max_redirects: int = 10,
        enable_otel: bool = True,
        meter_provider: MeterProvider | None = None,
        tracer_provider: TracerProvider | None = None,
    ) -> None:
        """Creates a new HTTPTransport object.

        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.

        Args:
            tls_ca_cert: The CA certificate to use to verify the server for TLS connections.
            tls_include_system_certs: 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.
            tls_key: The client private key to identify the client for mTLS connections.
                     tls_cert must also be set.
            tls_cert: The client certificate to identify the client for mTLS connections.
                      tls_key must also be set.
            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.
            proxy: 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.
            timeout: Default timeout for requests in seconds. This is the timeout from
                     the start of the request to the end of the response.
            connect_timeout: Timeout for connection establishment in seconds.
            read_timeout: Timeout for each read operation of a request in seconds.
            pool_idle_timeout: Timeout for idle connections in the connection pool in seconds.
            pool_max_idle_per_host: Maximum number of idle connections to keep in the pool per host.
                                    Defaults to 2.
            tcp_keepalive_interval: Interval for TCP keepalive probes in seconds.
            enable_gzip: Whether to enable gzip decompression for responses.
            enable_brotli: Whether to enable brotli decompression for responses.
            enable_zstd: Whether to enable zstd decompression for responses.
            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.
            enable_cookie_store: Whether to enable automatic cookie storage and sending. When enabled,
                          the transport will automatically store cookies from responses and send
                          them with subsequent requests.
            follow_redirects: 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.
            max_redirects: Maximum number of redirects to follow when follow_redirects is enabled.
                           A request exceeding it fails with TooManyRedirects.
        """

    def __aenter__(self) -> Awaitable[HTTPTransport]:
        """Enters the context manager for the transport to automatically close it when
        leaving.
        """

    def __aexit__(
        self,
        _exc_type: type[BaseException] | None,
        _exc_value: BaseException | None,
        _traceback: TracebackType | None,
    ) -> Awaitable[None]:
        """Exits the context manager for the transport, closing it."""

    def execute(self, request: Request) -> Awaitable[Response]:
        """Executes the given request, returning the response.

        Args:
            request: The request to execute.

        Raises:
            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.
        """

    def aclose(self) -> Awaitable[None]:
        """Closes the transport, releasing any underlying resources."""

def get_default_transport() -> HTTPTransport:
    """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,
    )
    ```
    """

@final
class Request:
    """An HTTP request."""

    def __init__(
        self,
        method: str,
        url: str,
        headers: Headers | None = None,
        content: _RequestContent | None = None,
        *,
        params: _QueryParams | None = None,
    ) -> None:
        """Creates a new Request object.

        Args:
            method: The HTTP method.
            url: The unencoded request URL.
            headers: The request headers.
            content: The request content. A Python dictionary will be converted
                     to JSON and a Multipart will be sent as a multipart form.
            params: Query parameters to append to the URL. None values will be treated as key-only.
        """

    @property
    def method(self) -> str:
        """Returns the HTTP method of the request."""

    @property
    def url(self) -> str:
        """Returns the unencoded request URL."""

    @property
    def headers(self) -> Headers:
        """Returns the request headers."""

    @property
    def content(self) -> bytes | AsyncIterator[bytes]:
        """Returns an async iterator over the request content."""

    @property
    def _json(self) -> bool: ...

@final
class Response:
    """An HTTP response."""

    def __init__(
        self,
        *,
        status: int,
        http_version: HTTPVersion | None = None,
        headers: Headers | None = None,
        content: bytes | AsyncIterator[_Buffer] | None = None,
        trailers: Headers | None = None,
    ) -> None:
        """Creates a new Response object.

        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.

        Args:
            status: The HTTP status code of the response.
            http_version: The HTTP version of the response.
            headers: The response headers.
            content: The response content.
            trailers: The response trailers.

        Raises:
            RemoteProtocolError: If the status is not a valid HTTP status code.
        """

    def __aenter__(self) -> Awaitable[Response]:
        """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.
        """

    def __aexit__(
        self,
        _exc_type: type[BaseException] | None,
        _exc_value: BaseException | None,
        _traceback: TracebackType | None,
    ) -> Awaitable[None]:
        """Exits the context manager for the response, closing it."""

    @property
    def status(self) -> int:
        """Returns the HTTP status code of the response."""

    @property
    def http_version(self) -> HTTPVersion:
        """Returns the HTTP version of the response."""

    @property
    def headers(self) -> Headers:
        """Returns the response headers."""

    @property
    def content(self) -> AsyncIterator[_Buffer]:
        """Returns an asynchronous iterator over the response content."""

    @property
    def trailers(self) -> Headers:
        """Returns the response trailers.

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

    def aclose(self) -> Awaitable[None]:
        """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.
        """

@final
class SyncClient:
    """A synchronous HTTP client.

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

    def __init__(self, transport: SyncTransport | None = None) -> None:
        """Creates a new synchronous HTTP client.

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

    def get(
        self,
        url: str,
        headers: Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
        *,
        timeout: float | None = None,
        params: _QueryParams | None = None,
    ) -> FullResponse:
        """Executes a GET HTTP request.

        Args:
            url: The unencoded request URL.
            headers: The request headers.
            timeout: The timeout for the request in seconds.
            params: Query parameters to append to the URL. None values will be treated as key-only.

        Raises:
            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.
        """

    def post(
        self,
        url: str,
        headers: Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
        content: _SyncRequestContent | None = None,
        *,
        timeout: float | None = None,
        params: _QueryParams | None = None,
    ) -> FullResponse:
        """Executes a POST HTTP request.

        Args:
            url: The unencoded request URL.
            headers: The request headers.
            content: The request content. A Python dictionary will be converted
                     to JSON and a SyncMultipart will be sent as a multipart form.
            timeout: The timeout for the request in seconds.
            params: Query parameters to append to the URL. None values will be treated as key-only.

        Raises:
            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.
        """

    def delete(
        self,
        url: str,
        headers: Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
        *,
        timeout: float | None = None,
        params: _QueryParams | None = None,
    ) -> FullResponse:
        """Executes a DELETE HTTP request.

        Args:
            url: The unencoded request URL.
            headers: The request headers.
            timeout: The timeout for the request in seconds.
            params: Query parameters to append to the URL. None values will be treated as key-only.

        Raises:
            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.
        """

    def head(
        self,
        url: str,
        headers: Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
        *,
        timeout: float | None = None,
        params: _QueryParams | None = None,
    ) -> FullResponse:
        """Executes a HEAD HTTP request.

        Args:
            url: The unencoded request URL.
            headers: The request headers.
            timeout: The timeout for the request in seconds.
            params: Query parameters to append to the URL. None values will be treated as key-only.

        Raises:
            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.
        """

    def options(
        self,
        url: str,
        headers: Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
        *,
        timeout: float | None = None,
        params: _QueryParams | None = None,
    ) -> FullResponse:
        """Executes a OPTIONS HTTP request.

        Args:
            url: The unencoded request URL.
            headers: The request headers.
            timeout: The timeout for the request in seconds.
            params: Query parameters to append to the URL. None values will be treated as key-only.

        Raises:
            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.
        """

    def patch(
        self,
        url: str,
        headers: Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
        content: _SyncRequestContent | None = None,
        *,
        timeout: float | None = None,
        params: _QueryParams | None = None,
    ) -> FullResponse:
        """Executes a PATCH HTTP request.

        Args:
            url: The unencoded request URL.
            headers: The request headers.
            content: The request content. A Python dictionary will be converted
                     to JSON and a SyncMultipart will be sent as a multipart form.
            timeout: The timeout for the request in seconds.
            params: Query parameters to append to the URL. None values will be treated as key-only.

        Raises:
            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.
        """

    def put(
        self,
        url: str,
        headers: Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
        content: _SyncRequestContent | None = None,
        *,
        timeout: float | None = None,
        params: _QueryParams | None = None,
    ) -> FullResponse:
        """Executes a PUT HTTP request.

        Args:
            url: The unencoded request URL.
            headers: The request headers.
            content: The request content. A Python dictionary will be converted
                     to JSON and a SyncMultipart will be sent as a multipart form.
            timeout: The timeout for the request in seconds.
            params: Query parameters to append to the URL. None values will be treated as key-only.

        Raises:
            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.
        """

    def execute(
        self,
        method: str,
        url: str,
        headers: Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
        content: _SyncRequestContent | None = None,
        *,
        timeout: float | None = None,
        params: _QueryParams | None = None,
    ) -> FullResponse:
        """Executes an HTTP request, returning the full buffered response.

        Args:
            method: The HTTP method.
            url: The unencoded request URL.
            headers: The request headers.
            content: The request content. A Python dictionary will be converted
                     to JSON and a SyncMultipart will be sent as a multipart form.
            timeout: The timeout for the request in seconds.
            params: Query parameters to append to the URL. None values will be treated as key-only.

        Raises:
            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.
        """

    def stream(
        self,
        method: str,
        url: str,
        headers: Headers | Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
        content: _SyncRequestContent | None = None,
        *,
        timeout: float | None = None,
        params: _QueryParams | None = None,
    ) -> AbstractContextManager[SyncResponse]:
        """Executes an HTTP request, allowing the response content to be streamed.

        Args:
            method: The HTTP method.
            url: The unencoded request URL.
            headers: The request headers.
            content: The request content. A Python dictionary will be converted
                     to JSON and a SyncMultipart will be sent as a multipart form.
            timeout: The timeout for the request in seconds.
            params: Query parameters to append to the URL. None values will be treated as key-only.

        Raises:
            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.
        """

@runtime_checkable
class SyncTransport(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
    """

    def execute_sync(self, request: SyncRequest) -> SyncResponse:
        """Executes a request."""

@final
class SyncHTTPTransport:
    """An HTTP transport implementation using reqwest."""

    def __init__(
        self,
        *,
        tls_ca_cert: bytes | None = None,
        tls_include_system_certs: bool = False,
        tls_key: bytes | None = None,
        tls_cert: bytes | None = None,
        http_version: HTTPVersion | None = None,
        proxy: str | Proxy | Sequence[str | Proxy] | None = None,
        timeout: float | None = None,
        connect_timeout: float | None = 30.0,
        read_timeout: float | None = None,
        pool_idle_timeout: float | None = 90.0,
        pool_max_idle_per_host: int | None = None,
        tcp_keepalive_interval: float | None = 30.0,
        enable_gzip: bool = True,
        enable_brotli: bool = True,
        enable_zstd: bool = True,
        use_system_dns: bool = False,
        enable_cookie_store: bool = False,
        follow_redirects: bool = True,
        max_redirects: int = 10,
        enable_otel: bool = True,
        meter_provider: MeterProvider | None = None,
        tracer_provider: TracerProvider | None = None,
    ) -> None:
        """Creates a new SyncHTTPTransport object.

        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.

        Args:
            tls_ca_cert: The CA certificate to use to verify the server for TLS connections.
            tls_include_system_certs: 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.
            tls_key: The client private key to identify the client for mTLS connections.
                     tls_cert must also be set.
            tls_cert: The client certificate to identify the client for mTLS connections.
                      tls_key must also be set.
            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.
            proxy: 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.
            timeout: Default timeout for requests in seconds. This is the timeout from
                     the start of the request to the end of the response.
            connect_timeout: Timeout for connection establishment in seconds.
            read_timeout: Timeout for each read operation of a request in seconds.
            pool_idle_timeout: Timeout for idle connections in the connection pool in seconds.
            pool_max_idle_per_host: Maximum number of idle connections to keep in the pool per host.
                                    Defaults to 2.
            tcp_keepalive_interval: Interval for TCP keepalive probes in seconds.
            enable_gzip: Whether to enable gzip decompression for responses.
            enable_brotli: Whether to enable brotli decompression for responses.
            enable_zstd: Whether to enable zstd decompression for responses.
            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.
            enable_cookie_store: Whether to enable automatic cookie storage and sending. When enabled,
                          the transport will automatically store cookies from responses and send
                          them with subsequent requests.
            follow_redirects: 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.
            max_redirects: Maximum number of redirects to follow when follow_redirects is enabled.
                           A request exceeding it fails with TooManyRedirects.
        """

    def __enter__(self) -> SyncHTTPTransport:
        """Enters the context manager for the transport to automatically
        close it when leaving.
        """

    def __exit__(
        self,
        _exc_type: type[BaseException] | None,
        _exc_value: BaseException | None,
        _traceback: TracebackType | None,
    ) -> None:
        """Exits the context manager for the transport, closing it."""

    def execute_sync(self, request: SyncRequest) -> SyncResponse:
        """Executes the given request, returning the response.

        Args:
            request: The request to execute.
        """

    def close(self) -> None:
        """Closes the transport, releasing any underlying resources."""

def get_default_sync_transport() -> SyncHTTPTransport:
    """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,
    )
    ```
    """

@final
class SyncRequest:
    """An HTTP request."""

    def __init__(
        self,
        method: str,
        url: str,
        headers: Headers | None = None,
        content: _SyncRequestContent | None = None,
        *,
        params: _QueryParams | None = None,
    ) -> None:
        """Creates a new SyncRequest object.

        Args:
            method: The HTTP method.
            url: The unencoded request URL.
            headers: The request headers.
            content: The request content. A Python dictionary will be converted
                     to JSON and a SyncMultipart will be sent as a multipart form.
            params: Query parameters to append to the URL. None values will be treated as key-only.
        """

    @property
    def method(self) -> str:
        """Returns the HTTP method of the request."""

    @property
    def url(self) -> str:
        """Returns the unencoded request URL."""

    @property
    def headers(self) -> Headers:
        """Returns the request headers."""

    @property
    def content(self) -> bytes | Iterator[bytes]:
        """Returns an iterator over the request content."""

    @property
    def _json(self) -> bool: ...

@final
class SyncResponse:
    """An HTTP response."""

    def __init__(
        self,
        *,
        status: int,
        http_version: HTTPVersion | None = None,
        headers: Headers | None = None,
        content: bytes | Iterable[_Buffer] | None = None,
        trailers: Headers | None = None,
    ) -> None:
        """Creates a new SyncResponse object.

        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.

        Args:
            status: The HTTP status code of the response.
            http_version: The HTTP version of the response.
            headers: The response headers.
            content: The response content.
            trailers: The response trailers.

        Raises:
            RemoteProtocolError: If the status is not a valid HTTP status code.
        """

    def __enter__(self) -> SyncResponse:
        """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.
        """

    def __exit__(
        self,
        _exc_type: type[BaseException] | None,
        _exc_value: BaseException | None,
        _traceback: TracebackType | None,
    ) -> None:
        """Exits the context manager for the response, closing it."""

    @property
    def status(self) -> int:
        """Returns the HTTP status code of the response."""

    @property
    def http_version(self) -> HTTPVersion:
        """Returns the HTTP version of the response."""

    @property
    def headers(self) -> Headers:
        """Returns the response headers."""

    @property
    def content(self) -> Iterator[_Buffer]:
        """Returns an iterator over the response content."""

    @property
    def trailers(self) -> Headers:
        """Returns the response trailers.

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

    def close(self) -> None:
        """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.
        """

@final
class FullResponse:
    """A fully buffered HTTP response."""

    def __init__(
        self, status: int, headers: Headers, content: bytes, trailers: Headers
    ) -> None:
        """Creates a new FullResponse object.

        Args:
            status: The HTTP status code of the response.
            headers: The response headers.
            content: The response content.
            trailers: The response trailers.
        """

    @property
    def status(self) -> int:
        """Returns the HTTP status code of the response."""

    @property
    def headers(self) -> Headers:
        """Returns the response headers."""

    @property
    def content(self) -> bytes:
        """Returns the response content."""

    @property
    def trailers(self) -> Headers:
        """Returns the response trailers."""

    def text(self) -> str:
        """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.
        """

    def json(self) -> _JSON:
        """Parses and returns the response content as JSON.

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

@final
class ReadError(Exception):
    """An error representing a read error during response reading."""

@final
class WriteError(Exception):
    """An error representing a write error during request sending."""

@final
class TooManyRedirects(Exception):
    """An error raised when a request exceeded the transport's max_redirects."""

@final
class HTTPHeaderName:
    """An enum type corresponding to HTTP header names."""

    def __init__(self, name: str) -> None:
        """Creates a new HTTPHeaderName. When available, prefer one of the
        class attributes.

        Args:
            name: The header name.
        """

    ACCEPT: HTTPHeaderName
    """The "accept" header."""

    ACCEPT_CHARSET: HTTPHeaderName
    """The "accept-charset" header."""

    ACCEPT_ENCODING: HTTPHeaderName
    """The "accept-encoding" header."""

    ACCEPT_LANGUAGE: HTTPHeaderName
    """The "accept-language" header."""

    ACCEPT_RANGES: HTTPHeaderName
    """The "accept-ranges" header."""

    ACCESS_CONTROL_ALLOW_CREDENTIALS: HTTPHeaderName
    """The "access-control-allow-credentials" header."""

    ACCESS_CONTROL_ALLOW_HEADERS: HTTPHeaderName
    """The "access-control-allow-headers" header."""

    ACCESS_CONTROL_ALLOW_METHODS: HTTPHeaderName
    """The "access-control-allow-methods" header."""

    ACCESS_CONTROL_ALLOW_ORIGIN: HTTPHeaderName
    """The "access-control-allow-origin" header."""

    ACCESS_CONTROL_EXPOSE_HEADERS: HTTPHeaderName
    """The "access-control-expose-headers" header."""

    ACCESS_CONTROL_MAX_AGE: HTTPHeaderName
    """The "access-control-max-age" header."""

    ACCESS_CONTROL_REQUEST_HEADERS: HTTPHeaderName
    """The "access-control-request-headers" header."""

    ACCESS_CONTROL_REQUEST_METHOD: HTTPHeaderName
    """The "access-control-request-method" header."""

    AGE: HTTPHeaderName
    """The "age" header."""

    ALLOW: HTTPHeaderName
    """The "allow" header."""

    ALT_SVC: HTTPHeaderName
    """The "alt-svc" header."""

    AUTHORIZATION: HTTPHeaderName
    """The "authorization" header."""

    CACHE_CONTROL: HTTPHeaderName
    """The "cache-control" header."""

    CACHE_STATUS: HTTPHeaderName
    """The "cache-status" header."""

    CDN_CACHE_CONTROL: HTTPHeaderName
    """The "cdn-cache-control" header."""

    CONNECTION: HTTPHeaderName
    """The "connection" header."""

    CONTENT_DISPOSITION: HTTPHeaderName
    """The "content-disposition" header."""

    CONTENT_ENCODING: HTTPHeaderName
    """The "content-encoding" header."""

    CONTENT_LANGUAGE: HTTPHeaderName
    """The "content-language" header."""

    CONTENT_LENGTH: HTTPHeaderName
    """The "content-length" header."""

    CONTENT_LOCATION: HTTPHeaderName
    """The "content-location" header."""

    CONTENT_RANGE: HTTPHeaderName
    """The "content-range" header."""

    CONTENT_SECURITY_POLICY: HTTPHeaderName
    """The "content-security-policy" header."""

    CONTENT_SECURITY_POLICY_REPORT_ONLY: HTTPHeaderName
    """The "content-security-policy-report-only" header."""

    CONTENT_TYPE: HTTPHeaderName
    """The "content-type" header."""

    COOKIE: HTTPHeaderName
    """The "cookie" header."""

    DNT: HTTPHeaderName
    """The "dnt" header."""

    DATE: HTTPHeaderName
    """The "date" header."""

    ETAG: HTTPHeaderName
    """The "etag" header."""

    EXPECT: HTTPHeaderName
    """The "expect" header."""

    EXPIRES: HTTPHeaderName
    """The "expires" header."""

    FORWARDED: HTTPHeaderName
    """The "forwarded" header."""

    FROM: HTTPHeaderName
    """The "from" header."""

    HOST: HTTPHeaderName
    """The "host" header."""

    IF_MATCH: HTTPHeaderName
    """The "if-match" header."""

    IF_MODIFIED_SINCE: HTTPHeaderName
    """The "if-modified-since" header."""

    IF_NONE_MATCH: HTTPHeaderName
    """The "if-none-match" header."""

    IF_RANGE: HTTPHeaderName
    """The "if-range" header."""

    IF_UNMODIFIED_SINCE: HTTPHeaderName
    """The "if-unmodified-since" header."""

    LAST_MODIFIED: HTTPHeaderName
    """The "last-modified" header."""

    LINK: HTTPHeaderName
    """The "link" header."""

    LOCATION: HTTPHeaderName
    """The "location" header."""

    MAX_FORWARDS: HTTPHeaderName
    """The "max-forwards" header."""

    ORIGIN: HTTPHeaderName
    """The "origin" header."""

    PRAGMA: HTTPHeaderName
    """The "pragma" header."""

    PROXY_AUTHENTICATE: HTTPHeaderName
    """The "proxy-authenticate" header."""

    PROXY_AUTHORIZATION: HTTPHeaderName
    """The "proxy-authorization" header."""

    PUBLIC_KEY_PINS: HTTPHeaderName
    """The "public-key-pins" header."""

    PUBLIC_KEY_PINS_REPORT_ONLY: HTTPHeaderName
    """The "public-key-pins-report-only" header."""

    RANGE: HTTPHeaderName
    """The "range" header."""

    REFERER: HTTPHeaderName
    """The "referer" header."""

    REFERRER_POLICY: HTTPHeaderName
    """The "referrer-policy" header."""

    REFRESH: HTTPHeaderName
    """The "refresh" header."""

    RETRY_AFTER: HTTPHeaderName
    """The "retry-after" header."""

    SEC_WEBSOCKET_ACCEPT: HTTPHeaderName
    """The "sec-websocket-accept" header."""

    SEC_WEBSOCKET_EXTENSIONS: HTTPHeaderName
    """The "sec-websocket-extensions" header."""

    SEC_WEBSOCKET_KEY: HTTPHeaderName
    """The "sec-websocket-key" header."""

    SEC_WEBSOCKET_PROTOCOL: HTTPHeaderName
    """The "sec-websocket-protocol" header."""

    SEC_WEBSOCKET_VERSION: HTTPHeaderName
    """The "sec-websocket-version" header."""

    SERVER: HTTPHeaderName
    """The "server" header."""

    SET_COOKIE: HTTPHeaderName
    """The "set-cookie" header."""

    STRICT_TRANSPORT_SECURITY: HTTPHeaderName
    """The "strict-transport-security" header."""

    TE: HTTPHeaderName
    """The "te" header."""

    TRAILER: HTTPHeaderName
    """The "trailer" header."""

    TRANSFER_ENCODING: HTTPHeaderName
    """The "transfer-encoding" header."""

    USER_AGENT: HTTPHeaderName
    """The "user-agent" header."""

    UPGRADE: HTTPHeaderName
    """The "upgrade" header."""

    UPGRADE_INSECURE_REQUESTS: HTTPHeaderName
    """The "upgrade-insecure-requests" header."""

    VARY: HTTPHeaderName
    """The "vary" header."""

    VIA: HTTPHeaderName
    """The "via" header."""

    WARNING: HTTPHeaderName
    """The "warning" header."""

    WWW_AUTHENTICATE: HTTPHeaderName
    """The "www-authenticate" header."""

    X_CONTENT_TYPE_OPTIONS: HTTPHeaderName
    """The "x-content-type-options" header."""

    X_DNS_PREFETCH_CONTROL: HTTPHeaderName
    """The "x-dns-prefetch-control" header."""

    X_FRAME_OPTIONS: HTTPHeaderName
    """The "x-frame-options" header."""

    X_XSS_PROTECTION: HTTPHeaderName
    """The "x-xss-protection" header."""

def set_sync_timeout(timeout: float) -> AbstractContextManager[None]: ...
def get_sync_timeout() -> datetime.timedelta | None: ...

class _BrotliDecompressor:
    def feed(self, data: bytes, *, end: bool) -> bytes: ...

class _ZstdDecompressor:
    def feed(self, data: bytes, *, end: bool) -> bytes: ...

class _Backoff:
    def __init__(
        self,
        initial_interval: float,
        randomization_factor: float,
        multiplier: float,
        max_interval: float,
    ) -> None: ...
    def next_backoff(self) -> float | None: ...