pyreqwest 0.5.1__cp313-cp313-musllinux_1_1_aarch64.whl

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__ = [  # noqa: RUF022
+    "Url",
+    "HeaderMap",
+    "Mime",
+    "HeaderMapItemsView",
+    "HeaderMapKeysView",
+    "HeaderMapValuesView",
+]