pyreqwest 0.8.0__cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl

pyreqwest/compatibility/httpx/transport.py

@@ -0,0 +1,154 @@
+"""Compatibility layer for httpx, which allows pyreqwest to replace httpcore transport for httpx."""
+
+from collections.abc import AsyncIterator, Iterator
+from contextlib import AsyncExitStack, ExitStack
+
+import httpx
+
+from pyreqwest.client import Client, ClientBuilder, SyncClient, SyncClientBuilder
+from pyreqwest.exceptions import PyreqwestError
+from pyreqwest.request import RequestBuilder, SyncRequestBuilder
+from pyreqwest.response import Response, SyncResponse
+
+from ._internal import build_httpx_response, map_exception, map_extensions
+
+
+class HttpxTransport(httpx.AsyncBaseTransport):
+    """httpx transport that uses pyreqwest for HTTP requests.
+
+    Example usage:
+    ```python
+    import httpx
+    from pyreqwest.compatibility.httpx import HttpxTransport
+
+    async with httpx.AsyncClient(transport=HttpxTransport()) as httpx_client:
+        print(await httpx_client.get("https://example.com"))
+    ```
+    """
+
+    def __init__(self, client: Client | None = None, *, close_client: bool = True) -> None:
+        """Initialize the HttpxTransport.
+        :param client: An optional pyreqwest Client instance. If not provided, a default Client will be created.
+        :param close_client: Whether to close the provided Client when the transport is closed.
+        """
+        self._client: Client = client or ClientBuilder().build()
+        self._close_client = (client is None) or close_client
+
+    async def aclose(self) -> None:
+        """Close the underlying pyreqwest Client if needed."""
+        if self._close_client:
+            await self._client.close()
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        """AsyncBaseTransport implementation to handle httpx request using pyreqwest."""
+        req_builder = self._client.request(request.method, str(request.url)).headers(request.headers.multi_items())
+        req_builder = self._map_body(req_builder, request)
+        req_builder = map_extensions(req_builder, request)
+        return await self._map_response(req_builder, request)
+
+    def _map_body(self, builder: RequestBuilder, request: httpx.Request) -> RequestBuilder:
+        try:
+            return builder.body_bytes(request.content)
+        except httpx.RequestNotRead:
+            return builder.body_stream(request.stream)
+
+    async def _map_response(self, builder: RequestBuilder, request: httpx.Request) -> httpx.Response:
+        req_exit_stack = AsyncExitStack()
+        try:
+            response = await req_exit_stack.enter_async_context(builder.build_streamed())
+            return build_httpx_response(response, response_stream=ResponseStream(response, req_exit_stack))
+        except Exception as exc:
+            await req_exit_stack.aclose()
+            if isinstance(exc, PyreqwestError) and (mapped := map_exception(exc, request)):
+                raise mapped from exc
+            raise
+
+
+class SyncHttpxTransport(httpx.BaseTransport):
+    """httpx transport that uses pyreqwest for HTTP requests.
+
+    Example usage:
+    ```python
+    import httpx
+    from pyreqwest.compatibility.httpx import SyncHttpxTransport
+
+    with httpx.Client(transport=SyncHttpxTransport()) as httpx_client:
+        print(httpx_client.get("https://example.com"))
+    ```
+    """
+
+    def __init__(self, client: SyncClient | None = None, *, close_client: bool = True) -> None:
+        """Initialize the SyncHttpxTransport.
+        :param client: An optional pyreqwest SyncClient instance. If not provided, a default SyncClient will be created.
+        :param close_client: Whether to close the provided SyncClient when the transport is closed.
+        """
+        self._client: SyncClient = client or SyncClientBuilder().build()
+        self._close_client = (client is None) or close_client
+
+    def close(self) -> None:
+        """Close the underlying pyreqwest SyncClient if needed."""
+        if self._close_client:
+            self._client.close()
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        """BaseTransport implementation to handle httpx request using pyreqwest."""
+        req_builder = self._client.request(request.method, str(request.url)).headers(request.headers.multi_items())
+        req_builder = self._map_body(req_builder, request)
+        req_builder = map_extensions(req_builder, request)
+        return self._map_response(req_builder, request)
+
+    def _map_body(self, builder: SyncRequestBuilder, request: httpx.Request) -> SyncRequestBuilder:
+        try:
+            return builder.body_bytes(request.content)
+        except httpx.RequestNotRead:
+            if isinstance(request.stream, httpx.AsyncByteStream):
+                err = "Cannot use async stream in sync transport"
+                raise TypeError(err) from None
+            return builder.body_stream(request.stream)
+
+    def _map_response(self, builder: SyncRequestBuilder, request: httpx.Request) -> httpx.Response:
+        req_exit_stack = ExitStack()
+        try:
+            response = req_exit_stack.enter_context(builder.build_streamed())
+            return build_httpx_response(response, response_stream=SyncResponseStream(response, req_exit_stack))
+        except Exception as exc:
+            req_exit_stack.close()
+            if isinstance(exc, PyreqwestError) and (mapped := map_exception(exc, request)):
+                raise mapped from exc
+            raise
+
+
+class ResponseStream(httpx.AsyncByteStream):
+    """httpx AsyncByteStream that wraps a pyreqwest Response body reader."""
+
+    def __init__(self, response: Response, exit_stack: AsyncExitStack) -> None:
+        """Internally initialized."""
+        self._body_reader = response.body_reader
+        self._exit_stack = exit_stack
+
+    async def __aiter__(self) -> AsyncIterator[bytes]:
+        """Asynchronously iterate over the response body in chunks."""
+        while (chunk := await self._body_reader.read()) is not None:
+            yield bytes(chunk)
+
+    async def aclose(self) -> None:
+        """Close the response stream."""
+        await self._exit_stack.aclose()
+
+
+class SyncResponseStream(httpx.SyncByteStream):
+    """httpx SyncByteStream that wraps a pyreqwest SyncResponse body reader."""
+
+    def __init__(self, response: SyncResponse, exit_stack: ExitStack) -> None:
+        """Internally initialized."""
+        self._body_reader = response.body_reader
+        self._exit_stack = exit_stack
+
+    def __iter__(self) -> Iterator[bytes]:
+        """Iterate over the response body in chunks."""
+        while (chunk := self._body_reader.read()) is not None:
+            yield bytes(chunk)
+
+    def close(self) -> None:
+        """Close the response stream."""
+        self._exit_stack.close()

pyreqwest/cookie/__init__.py

@@ -0,0 +1,5 @@
+"""Cookie related classes."""
+
+from pyreqwest._pyreqwest.cookie import Cookie, CookieStore
+
+__all__ = ["Cookie", "CookieStore"]

pyreqwest/cookie/__init__.pyi

@@ -0,0 +1,174 @@
+"""HTTP cookie types backed by Rust's cookie and cookie_store crates."""
+
+from collections.abc import Sequence
+from datetime import datetime, timedelta
+from typing import Any, Literal, Self, TypeAlias, overload
+
+from pyreqwest.http import Url
+
+SameSite: TypeAlias = Literal["Strict", "Lax", "None"]
+
+class Cookie:
+    """An immutable HTTP cookie. Lightweight Python wrapper around the internal Rust cookie::Cookie type.
+    Use `with_*` methods to create modified copies of a Cookie.
+
+    See also Rust [docs](https://docs.rs/cookie/latest/cookie/struct.Cookie.html) for more details.
+    """
+
+    def __init__(self, name: str, value: str) -> None:
+        """Create a cookie with the given name and value (no attributes)."""
+
+    @staticmethod
+    def parse(cookie: str) -> "Cookie":
+        """Parses a Cookie from the given HTTP cookie header value string."""
+
+    @staticmethod
+    def parse_encoded(cookie: str) -> "Cookie":
+        """Like parse, but does percent-decoding of keys and values."""
+
+    @staticmethod
+    def split_parse(cookie: str) -> list["Cookie"]:
+        """Parses the HTTP Cookie header, a series of cookie names and value separated by `;`."""
+
+    @staticmethod
+    def split_parse_encoded(cookie: str) -> list["Cookie"]:
+        """Like split_parse, but does percent-decoding of keys and values."""
+
+    @property
+    def name(self) -> str:
+        """Cookie name."""
+
+    @property
+    def value(self) -> str:
+        """Raw cookie value as set (may contain surrounding whitespace)."""
+
+    @property
+    def value_trimmed(self) -> str:
+        """Value with surrounding whitespace trimmed."""
+
+    @property
+    def http_only(self) -> bool:
+        """Whether the HttpOnly attribute is set."""
+
+    @property
+    def secure(self) -> bool:
+        """Whether the Secure attribute is set."""
+
+    @property
+    def same_site(self) -> SameSite | None:
+        """SameSite attribute, or None if unspecified."""
+
+    @property
+    def partitioned(self) -> bool:
+        """Whether the Partitioned attribute is set."""
+
+    @property
+    def max_age(self) -> timedelta | None:
+        """Max-Age attribute duration, or None if not present."""
+
+    @property
+    def path(self) -> str | None:
+        """Path attribute that scopes the cookie, or None if not present."""
+
+    @property
+    def domain(self) -> str | None:
+        """Domain attribute that scopes the cookie, or None if not present."""
+
+    @property
+    def expires_datetime(self) -> datetime | None:
+        """Absolute expiration time (Expires), or None if not present."""
+
+    def encode(self) -> str:
+        """Returns cookie string with percent-encoding applied."""
+
+    def stripped(self) -> str:
+        """Return just the 'name=value' pair."""
+
+    def with_name(self, name: str) -> Self:
+        """Set name, returning a new Cookie."""
+
+    def with_value(self, value: str) -> Self:
+        """Set value, returning a new Cookie."""
+
+    def with_http_only(self, http_only: bool) -> Self:
+        """Set HttpOnly attribute, returning a new Cookie."""
+
+    def with_secure(self, secure: bool) -> Self:
+        """Set Secure attribute, returning a new Cookie."""
+
+    def with_same_site(self, same_site: SameSite | None) -> Self:
+        """Set SameSite attribute, returning a new Cookie."""
+
+    def with_partitioned(self, partitioned: bool) -> Self:
+        """Set Partitioned attribute, returning a new Cookie."""
+
+    def with_max_age(self, max_age: timedelta | None) -> Self:
+        """Set Max-Age attribute, returning a new Cookie."""
+
+    def with_path(self, path: str | None) -> Self:
+        """Set Path attribute, returning a new Cookie."""
+
+    def with_domain(self, domain: str | None) -> Self:
+        """Set Domain attribute, returning a new Cookie."""
+
+    def with_expires_datetime(self, expires: datetime | None) -> Self:
+        """Set Expires attribute, returning a new Cookie."""
+
+    def __contains__(self, item: Any) -> bool: ...
+    def __copy__(self) -> Self: ...
+    def __hash__(self) -> int: ...
+    @overload
+    def __getitem__(self, index: int) -> str: ...
+    @overload
+    def __getitem__(self, index: slice) -> Sequence[str]: ...
+    def __len__(self) -> int: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __lt__(self, other: object) -> bool: ...
+    def __le__(self, other: object) -> bool: ...
+
+class CookieStore:
+    """Thread-safe in-memory cookie store (domain/path aware). Mirrors the behavior of Rust's cookie_store.
+
+    See also Rust [docs](https://docs.rs/cookie_store/latest/cookie_store/struct.CookieStore.html) for more details.
+    """
+
+    def __init__(self) -> None:
+        """Create an empty cookie store."""
+
+    def contains(self, domain: str, path: str, name: str) -> bool:
+        """Returns true if the CookieStore contains an unexpired Cookie corresponding to the specified domain, path,
+        and name.
+        """
+
+    def contains_any(self, domain: str, path: str, name: str) -> bool:
+        """Returns true if the CookieStore contains any (even an expired) Cookie corresponding to the specified
+        domain, path, and name.
+        """
+
+    def get(self, domain: str, path: str, name: str) -> Cookie | None:
+        """Returns a reference to the unexpired Cookie corresponding to the specified domain, path, and name."""
+
+    def get_any(self, domain: str, path: str, name: str) -> Cookie | None:
+        """Returns a reference to the (possibly expired) Cookie corresponding to the specified domain, path, and
+        name.
+        """
+
+    def remove(self, domain: str, path: str, name: str) -> Cookie | None:
+        """Removes a Cookie from the store, returning the Cookie if it was in the store."""
+
+    def matches(self, url: Url | str) -> list[Cookie]:
+        """Returns a collection of references to unexpired cookies that path- and domain-match request_url, as well as
+        having HttpOnly and Secure attributes compatible with the request_url.
+        """
+
+    def insert(self, cookie: Cookie | str, request_url: Url | str) -> None:
+        """Insert a cookie as if set by a response for request_url."""
+
+    def clear(self) -> None:
+        """Remove all cookies from the store."""
+
+    def get_all_unexpired(self) -> list[Cookie]:
+        """Return all unexpired cookies currently stored."""
+
+    def get_all_any(self) -> list[Cookie]:
+        """Return all cookies in the store, including expired ones."""

pyreqwest/exceptions/__init__.py

@@ -0,0 +1,193 @@
+"""Exception classes."""
+
+from json import JSONDecodeError as JSONDecodeError_
+from typing import Any, Generic, TypedDict, TypeVar
+
+
+class Cause(TypedDict):
+    """A cause of an error."""
+
+    message: str
+
+
+class CauseErrorDetails(TypedDict):
+    """Details for errors that may have causes."""
+
+    causes: list[Cause] | None
+
+
+class StatusErrorDetails(TypedDict):
+    """Details for errors that have an associated HTTP status code."""
+
+    status: int
+
+
+T = TypeVar("T", bound=CauseErrorDetails | StatusErrorDetails)
+
+
+class PyreqwestError(Exception):
+    """Base class for all pyreqwest errors."""
+
+    def __init__(self, message: str, *args: Any) -> None:
+        """Internally initialized."""
+        assert isinstance(message, str)
+        Exception.__init__(self, message, *args)
+        self.message = message
+
+
+class DetailedPyreqwestError(PyreqwestError, Generic[T]):
+    """Base class for all pyreqwest errors with details.
+
+    Details may be available in `details`.
+    """
+
+    def __init__(self, message: str, details: T) -> None:
+        """Internally initialized."""
+        assert isinstance(details, dict)
+        PyreqwestError.__init__(self, message, details)
+        self.details = details
+
+
+class RequestError(DetailedPyreqwestError[T], Generic[T]):
+    """Error while processing a request.
+
+    Details may be available in `details`.
+    """
+
+
+class StatusError(RequestError[StatusErrorDetails]):
+    """Error due to HTTP 4xx or 5xx status code. Raised when `error_for_status` is enabled.
+
+    The status code is available in `details["status"]`.
+    """
+
+
+class RedirectError(RequestError[CauseErrorDetails]):
+    """Error due to too many redirects. Raised when `max_redirects` is exceeded.
+
+    Cause details may be available in `details["causes"]`.
+    """
+
+
+class DecodeError(RequestError[CauseErrorDetails]):
+    """Error while decoding the response.
+
+    Cause details may be available in `details["causes"]`.
+    """
+
+
+class BodyDecodeError(DecodeError):
+    """Error while decoding the request or response body.
+
+    Cause details may be available in `details["causes"]`.
+    """
+
+
+class JSONDecodeError(BodyDecodeError, JSONDecodeError_):
+    """Error while decoding the response body as JSON.
+
+    This corresponds to Python's built-in `json.JSONDecodeError`. With the difference that `pos` and `colno` are byte
+    offsets instead of UTF8 char offsets. This difference is for efficient error handling (avoiding UTF8 conversions).
+    """
+
+    def __init__(self, message: str, details: dict[str, Any]) -> None:
+        """Internally initialized."""
+        assert isinstance(details, dict)
+        assert isinstance(details["doc"], str) and isinstance(details["pos"], int)
+        JSONDecodeError_.__init__(self, message, details["doc"], details["pos"])
+        BodyDecodeError.__init__(self, message, {"causes": details["causes"]})
+
+
+class TransportError(RequestError[CauseErrorDetails]):
+    """Error while processing the transport layer.
+
+    Cause details may be available in `details["causes"]`.
+    """
+
+
+class RequestTimeoutError(TransportError, TimeoutError):
+    """Error due to a timeout.
+
+    This indicates that the timeout configured for the request was reached.
+    Cause details may be available in `details["causes"]`.
+    """
+
+
+class NetworkError(TransportError):
+    """Error due to a network failure.
+
+    This indicates that the request could not be completed due to a network failure.
+    Cause details may be available in `details["causes"]`.
+    """
+
+
+class ConnectTimeoutError(RequestTimeoutError):
+    """Timeout while connecting.
+
+    Cause details may be available in `details["causes"]`.
+    """
+
+
+class ReadTimeoutError(RequestTimeoutError):
+    """Timeout while reading body.
+
+    Cause details may be available in `details["causes"]`.
+    """
+
+
+class WriteTimeoutError(RequestTimeoutError):
+    """Timeout while sending body.
+
+    Cause details may be available in `details["causes"]`.
+    """
+
+
+class PoolTimeoutError(RequestTimeoutError):
+    """Timeout while acquiring a connection from the pool.
+
+    Cause details may be available in `details["causes"]`.
+    """
+
+
+class ConnectError(NetworkError):
+    """Network error while connecting.
+
+    Cause details may be available in `details["causes"]`.
+    """
+
+
+class ReadError(NetworkError):
+    """Network error while reading body.
+
+    Cause details may be available in `details["causes"]`.
+    """
+
+
+class WriteError(NetworkError):
+    """Network error while sending body.
+
+    Cause details may be available in `details["causes"]`.
+    """
+
+
+class ClientClosedError(RequestError[CauseErrorDetails]):
+    """Error due to user closing the client while request was being processed.
+
+    Cause details may be available in `details["causes"]`.
+    """
+
+
+class BuilderError(DetailedPyreqwestError[CauseErrorDetails], ValueError):
+    """Error while building a request.
+
+    Cause details may be available in `details["causes"]`.
+    """
+
+
+class RequestPanicError(RequestError[CauseErrorDetails]):
+    """Error due to a panic in the request processing.
+
+    This indicates a bug in pyreqwest or one of its dependencies.
+    Also, might be raised due to incorrect ProxyBuilder.custom implementation (limitation in reqwest error handling).
+    Cause details may be available in `details["causes"]`.
+    """

pyreqwest/http/__init__.py

@@ -0,0 +1,19 @@
+"""HTTP utils classes and types."""
+
+from pyreqwest._pyreqwest.http import (
+    HeaderMap,
+    HeaderMapItemsView,
+    HeaderMapKeysView,
+    HeaderMapValuesView,
+    Mime,
+    Url,
+)
+
+__all__ = [
+    "Url",
+    "HeaderMap",
+    "Mime",
+    "HeaderMapItemsView",
+    "HeaderMapKeysView",
+    "HeaderMapValuesView",
+]