xtr-http-client-contracts 4.0.2__py3-none-any.whl

xtr_http_client_contracts/__init__.py

@@ -0,0 +1,47 @@
+"""The async HTTP client contract: what code that calls out depends on, and nothing more.
+
+A library that sends an HTTP request should not decide what sends it. It takes the client
+interface, asks for a method and a URL — or hands over a message request — and gets back a
+response whose status line and headers have arrived, its body read when, and only when, the
+caller wants it.
+
+What is here is only what appears in that contract: the client, the response it answers with,
+the options a request takes, the errors any of them raises, and a conformance suite an
+implementation can run against itself.
+"""
+
+from __future__ import annotations
+
+from .exception import (
+    ClientError,
+    DecodingError,
+    HttpClientError,
+    HttpError,
+    InvalidArgumentError,
+    JsonError,
+    RedirectionError,
+    ServerError,
+    TransportError,
+    TransportTimeoutError,
+)
+from .http_client_interface import HttpClientInterface
+from .http_response_interface import HttpResponseInterface
+from .options_defaults import OPTIONS_DEFAULTS
+from .request_options import RequestOptions
+
+__all__ = [
+    "OPTIONS_DEFAULTS",
+    "ClientError",
+    "DecodingError",
+    "HttpClientError",
+    "HttpClientInterface",
+    "HttpError",
+    "HttpResponseInterface",
+    "InvalidArgumentError",
+    "JsonError",
+    "RedirectionError",
+    "RequestOptions",
+    "ServerError",
+    "TransportError",
+    "TransportTimeoutError",
+]

xtr_http_client_contracts/exception/__init__.py

@@ -0,0 +1,40 @@
+"""The errors the HTTP client contract names.
+
+:class:`HttpClientError` is the root every one of them derives from,
+including every error an implementation adds, so catching it catches anything
+calling out can go wrong with, whichever client raised it.
+
+Below it, two branches that mean different things. A
+:class:`TransportError` — with :class:`TransportTimeoutError` for running out
+of time — says there is no answer to look at. An :class:`HttpError` says
+there is one and it is not a success: :class:`RedirectionError` for a 3xx
+nobody followed, :class:`ClientError` for a 4xx, :class:`ServerError` for a
+5xx, each carrying the response. :class:`DecodingError` is the third case:
+the answer arrived whole and is not what it was being read as.
+"""
+
+from __future__ import annotations
+
+from .client_error import ClientError
+from .decoding_error import DecodingError
+from .http_client_error import HttpClientError
+from .http_error import HttpError
+from .invalid_argument_error import InvalidArgumentError
+from .json_error import JsonError
+from .redirection_error import RedirectionError
+from .server_error import ServerError
+from .transport_error import TransportError
+from .transport_timeout_error import TransportTimeoutError
+
+__all__ = [
+    "ClientError",
+    "DecodingError",
+    "HttpClientError",
+    "HttpError",
+    "InvalidArgumentError",
+    "JsonError",
+    "RedirectionError",
+    "ServerError",
+    "TransportError",
+    "TransportTimeoutError",
+]

xtr_http_client_contracts/exception/client_error.py

@@ -0,0 +1,16 @@
+"""The request was refused: a 4xx came back."""
+
+from __future__ import annotations
+
+from .http_error import HttpError
+
+__all__ = ["ClientError"]
+
+
+class ClientError(HttpError):
+    """A 4xx status: the server understood the request and would not serve it.
+
+    Retrying the same request unchanged gets the same answer, so this is the
+    one range worth telling apart — a 401 asks for credentials, a 404 says
+    there is nothing there, a 429 says to slow down.
+    """

xtr_http_client_contracts/exception/decoding_error.py

@@ -0,0 +1,32 @@
+"""The body arrived whole but is not what it was being read as."""
+
+from __future__ import annotations
+
+from .http_client_error import HttpClientError
+
+__all__ = ["DecodingError"]
+
+
+class DecodingError(HttpClientError, ValueError):
+    """A body could not be turned into the shape that was asked for.
+
+    What :meth:`HttpResponseInterface.to_array
+    <xtr_http_client_contracts.http_response_interface.HttpResponseInterface.to_array>`
+    raises when the body is empty, is not JSON, or is JSON that is not an
+    object. The transfer succeeded, so this is about the payload, not the
+    connection.
+
+    Also a :class:`ValueError`, so code that already guards what it parses
+    with ``except ValueError`` keeps working without learning a new
+    exception.
+
+    Attributes:
+        reason: What is wrong with the body, naming the URL it came from.
+    """
+
+    reason: str
+
+    def __init__(self, reason: str) -> None:
+        """Record what is wrong with the body."""
+        self.reason = reason
+        super().__init__(reason)

xtr_http_client_contracts/exception/http_client_error.py

@@ -0,0 +1,21 @@
+"""The root every error of the HTTP client contract derives from."""
+
+from __future__ import annotations
+
+__all__ = ["HttpClientError"]
+
+
+class HttpClientError(Exception):
+    """Base class for every error raised through the HTTP client contract.
+
+    Catch this to handle anything calling out can go wrong with, whichever
+    client is behind the interface; catch a subclass to handle one cause.
+    Every subclass carries what a caller needs as typed attributes and
+    composes its message from them.
+
+    A server answering is not a cause: a request that came back with a 404 or
+    a 503 succeeded as a transfer, so ``request()`` returns the response and
+    nothing is raised until someone reads its content and asks to be told.
+    What raises on its own is the transfer failing, a body that will not
+    decode, and an option no client here understands.
+    """

xtr_http_client_contracts/exception/http_error.py

@@ -0,0 +1,51 @@
+"""A server answered, and the answer was not a success."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .http_client_error import HttpClientError
+
+if TYPE_CHECKING:
+    from xtr_http_client_contracts.http_response_interface import HttpResponseInterface
+
+__all__ = ["HttpError"]
+
+
+class HttpError(HttpClientError):
+    """The status code says the request did not get what it asked for.
+
+    Never raised by making the request: a status is an answer, not a failure
+    of the transfer, so it reaches the caller as a response. This is raised
+    where the caller asks to be told about it —
+    :meth:`HttpResponseInterface.get_content
+    <xtr_http_client_contracts.http_response_interface.HttpResponseInterface.get_content>`
+    or :meth:`HttpResponseInterface.to_array
+    <xtr_http_client_contracts.http_response_interface.HttpResponseInterface.to_array>`
+    with ``throw``.
+
+    Catch this to handle any unsuccessful status;
+    :class:`RedirectionError <...redirection_error.RedirectionError>`,
+    :class:`ClientError <...client_error.ClientError>` and
+    :class:`ServerError <...server_error.ServerError>` are the three ranges,
+    and they are siblings, so catching one leaves the others alone.
+
+    The response comes along because it is the only place the answer is left:
+    the status code, the headers and the body, which is kept.
+
+    Attributes:
+        response: The response that was answered with.
+        reason: What the status means for this request, naming the code and
+            the URL. The message is this, composed by whoever raised it —
+            the body of an error document is the most useful thing to put
+            there and reading it is awaited, which a constructor cannot do.
+    """
+
+    response: HttpResponseInterface
+    reason: str
+
+    def __init__(self, response: HttpResponseInterface, reason: str) -> None:
+        """Record the response the status came on, and what it means."""
+        self.response = response
+        self.reason = reason
+        super().__init__(reason)

xtr_http_client_contracts/exception/invalid_argument_error.py

@@ -0,0 +1,27 @@
+"""A method, URL or option the client cannot use; raised before anything is sent."""
+
+from __future__ import annotations
+
+from .transport_error import TransportError
+
+__all__ = ["InvalidArgumentError"]
+
+
+# Both bases reach `BaseException`, which basedpyright flags as unsafe multiple inheritance.
+# It is safe here: `ValueError` adds no state, so `TransportError.__init__` is the only one
+# construction runs.
+class InvalidArgumentError(  # pyright: ignore[reportUnsafeMultipleInheritance]
+    TransportError,
+    ValueError,
+):
+    """The request was refused before it was sent, for something it asked for.
+
+    An unknown option name, an option whose value the client cannot honour, a
+    method or URL it cannot make a request with, or a body given both with the
+    request and as an option. Nothing reached the network, so there is no
+    response, and the same call with a corrected argument would go through.
+
+    Also a :class:`ValueError`, so code that already guards the arguments it
+    passes with ``except ValueError`` keeps working without learning a new
+    exception.
+    """

xtr_http_client_contracts/exception/json_error.py

@@ -0,0 +1,19 @@
+"""A body that is not the JSON object to_array() promises."""
+
+from __future__ import annotations
+
+from .decoding_error import DecodingError
+
+__all__ = ["JsonError"]
+
+
+class JsonError(DecodingError):
+    """The body is JSON, but not the object :meth:`HttpResponseInterface.to_array` promises.
+
+    A JSON array, string, number or ``null`` where an object was asked for. The
+    body was read in full and parsed, so the failure is the shape of the payload,
+    not the transfer.
+
+    Also a :class:`DecodingError`, so code that already catches a body it could
+    not decode keeps catching this one.
+    """

xtr_http_client_contracts/exception/redirection_error.py

@@ -0,0 +1,21 @@
+"""The answer points somewhere else, and nobody is following it any further."""
+
+from __future__ import annotations
+
+from .http_error import HttpError
+
+__all__ = ["RedirectionError"]
+
+
+class RedirectionError(HttpError):
+    """A 3xx status that was not followed.
+
+    Raised once ``max_redirects`` has been reached, or straight away when
+    following was turned off with ``max_redirects`` of zero or less — a
+    redirect that *is* followed never reaches the caller, since what comes
+    back is the response from the last hop.
+
+    Where the answer points is in the ``redirect_url`` entry of
+    :meth:`HttpResponseInterface.get_info
+    <xtr_http_client_contracts.http_response_interface.HttpResponseInterface.get_info>`.
+    """

xtr_http_client_contracts/exception/server_error.py

@@ -0,0 +1,15 @@
+"""The server failed to answer the request: a 5xx came back."""
+
+from __future__ import annotations
+
+from .http_error import HttpError
+
+__all__ = ["ServerError"]
+
+
+class ServerError(HttpError):
+    """A 5xx status: the request may have been fine, the server was not.
+
+    The far side is at fault, so the same request may well succeed later.
+    Nothing here retries; what to do about it is the caller's to decide.
+    """

xtr_http_client_contracts/exception/transport_error.py

@@ -0,0 +1,31 @@
+"""The transfer itself failed, so there is no response to look at."""
+
+from __future__ import annotations
+
+from .http_client_error import HttpClientError
+
+__all__ = ["TransportError"]
+
+
+class TransportError(HttpClientError):
+    """Nothing usable came back, or the request could never be made.
+
+    A host that will not resolve, a connection refused or reset, a body that
+    stopped half way, a certificate the client would not accept — and the one
+    case that never touches the network: an option the client does not
+    support. A client reports that by raising rather than by ignoring it, so
+    an option that was spelled wrong, or that this client cannot honour,
+    cannot pass for one it quietly obeyed.
+
+    It is also what reading a response raises once it has been cancelled.
+
+    Attributes:
+        reason: What went wrong, naming the URL it went wrong for.
+    """
+
+    reason: str
+
+    def __init__(self, reason: str) -> None:
+        """Record what went wrong."""
+        self.reason = reason
+        super().__init__(reason)

xtr_http_client_contracts/exception/transport_timeout_error.py

@@ -0,0 +1,27 @@
+"""Nothing arrived in time."""
+
+from __future__ import annotations
+
+from .transport_error import TransportError
+
+__all__ = ["TransportTimeoutError"]
+
+
+# Both bases reach `BaseException`, which basedpyright flags as unsafe multiple inheritance.
+# It is safe here: `TimeoutError` adds no state, so `TransportError.__init__` is the only one
+# construction runs.
+class TransportTimeoutError(  # pyright: ignore[reportUnsafeMultipleInheritance]
+    TransportError,
+    TimeoutError,
+):
+    """The transfer went quiet for longer than it was allowed to.
+
+    Raised when the idle timeout passes with nothing coming in, when the
+    whole transfer outlasts ``max_duration``, or when connecting outlasts
+    ``max_connect_duration``.
+
+    Also a :class:`TimeoutError`, which is what every async library in the
+    standard library raises and what ``anyio`` cancel scopes turn a deadline
+    into, so code that already gives up on a timeout keeps working without
+    learning a new exception.
+    """

xtr_http_client_contracts/http_client_interface.py

@@ -0,0 +1,124 @@
+"""The calls code that sends an HTTP request depends on."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, Self, runtime_checkable
+
+from typing_extensions import Unpack
+
+if TYPE_CHECKING:
+    from xtr_http_message_contracts import RequestInterface
+
+    from .http_response_interface import HttpResponseInterface
+    from .request_options import RequestOptions
+
+__all__ = ["HttpClientInterface"]
+
+
+@runtime_checkable
+class HttpClientInterface(Protocol):
+    """Sends HTTP requests and hands back responses.
+
+    A library that calls out takes this interface, and the application
+    decides what is behind it — a real transfer, a scoped client, a guard, or
+    a client answering from memory in a test.
+
+    ```python
+    response = await client.request("GET", "https://example.com/orders")
+    orders = await response.to_array()
+    ```
+
+    Several requests run at once by being made from tasks of one task group.
+
+    An option name the contract does not list is refused with
+    :class:`InvalidArgumentError
+    <xtr_http_client_contracts.exception.invalid_argument_error.InvalidArgumentError>`:
+    ``Unsupported option "foo" passed to "<client class>", did you mean "..."?``.
+    An option that was spelled wrong cannot pass for one that was obeyed.
+    """
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        **options: Unpack[RequestOptions],
+    ) -> HttpResponseInterface:
+        """Make a request, and return once the status line and the headers are in.
+
+        The same as :meth:`send_request` with a message request carrying
+        ``method`` and ``url``, no headers and an empty body.
+
+        It never raises because of the status: a 404 or a 503 is an answer,
+        and comes back as a response.
+
+        Args:
+            method: The HTTP method, in upper case.
+            url: The URL to request, absolute or relative to the
+                ``base_uri`` option.
+            **options: How the request is to be made; anything left out
+                falls back to this client's defaults.
+
+        Returns:
+            The response, with its status and headers already in.
+
+        Raises:
+            TransportTimeoutError: When no answer came in time.
+            InvalidArgumentError: For an invalid method, URL or option, before
+                anything is sent.
+            TransportError: When no answer came.
+        """
+        ...
+
+    async def send_request(
+        self,
+        request: RequestInterface,
+        **options: Unpack[RequestOptions],
+    ) -> HttpResponseInterface:
+        """Send a message request, the options filling what it leaves out.
+
+        The request is authoritative:
+
+        - a relative URI is resolved against ``base_uri``;
+        - ``query`` is merged into the URI;
+        - a header from ``headers`` is sent only when the request has none of
+          that name;
+        - ``auth_basic`` and ``auth_bearer`` apply only when the request has
+          no ``Authorization`` header;
+        - ``body`` or ``json`` with a request whose body is not empty is
+          refused: ``Define either the request body or the "body" or "json"
+          option, setting both is not supported.``.
+
+        It returns, and never raises because of the status, as
+        :meth:`request` does.
+
+        Args:
+            request: The request to send.
+            **options: What the request leaves out; anything left out of
+                both falls back to this client's defaults.
+
+        Returns:
+            The response, with its status and headers already in.
+
+        Raises:
+            TransportTimeoutError: When no answer came in time.
+            InvalidArgumentError: For an invalid method, URL or option, and for
+                a body given both with the request and as an option, before
+                anything is sent.
+            TransportError: When no answer came.
+        """
+        ...
+
+    def with_options(self, **options: Unpack[RequestOptions]) -> Self:
+        """Return a client whose requests start from these options.
+
+        Args:
+            **options: The defaults of the client returned, merged over this
+                client's own, so what is left out is kept.
+
+        Returns:
+            A new client; this one is left as it was.
+
+        Raises:
+            InvalidArgumentError: When an option is invalid, as in :meth:`request`.
+        """
+        ...

xtr_http_client_contracts/http_response_interface.py

@@ -0,0 +1,148 @@
+"""A response that has started arriving, and what a client adds to it."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, Self, runtime_checkable
+
+from xtr_http_message_contracts import ResponseInterface
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+__all__ = ["HttpResponseInterface"]
+
+
+@runtime_checkable
+class HttpResponseInterface(ResponseInterface, Protocol):
+    """An HTTP response whose body is read off the network when it is asked for.
+
+    It is a message response first: the status code and reason phrase, the
+    protocol version, the headers, the body as a stream and the ``with_*``
+    copies are the message contract's, so code typed against the plain
+    response interface takes this one as it is. A copy keeps the transfer
+    info and the very same body.
+
+    What a client adds:
+
+    - **A status is an answer, not a failure.** The response is handed back
+      once the status line and the headers are in, whatever the status.
+      :meth:`get_content` and :meth:`to_array` raise for a 3xx, 4xx or 5xx
+      when ``throw`` is left on, and return the body when it is turned off.
+    - **The body is kept.** It is read off the network on demand and kept —
+      in a temporary file past 2 MiB — so it can be read again;
+      ``get_body()`` is an async stream over that kept body.
+    - **It holds a connection until it is done with.** Leaving an
+      ``async with`` block closes the body, which frees the connection;
+      :meth:`cancel` does the same mid-transfer.
+    """
+
+    def get_info(self, key: str | None = None) -> object:
+        """Return what the transfer knows about itself, as it stands.
+
+        Never raises and never waits, so it can be read while the transfer is
+        going on.
+
+        These entries are always there:
+
+        - ``canceled`` (``bool``) — whether :meth:`cancel` was called.
+        - ``error`` (``str | None``) — what went wrong, once something has.
+        - ``http_code`` (``int``) — the last status code, or ``0`` before one
+          arrived.
+        - ``http_method`` (``str``) — the method of the last request made.
+        - ``redirect_count`` (``int``) — how many redirects were followed.
+        - ``redirect_url`` (``str | None``) — where a 3xx points, resolved,
+          when it was not followed.
+        - ``response_headers`` (``list[str]``) — the raw status and header
+          lines of every hop.
+        - ``start_time`` (``float``) — when the request was sent.
+        - ``total_time`` (``float``) — how long the transfer has taken.
+        - ``url`` (``str``) — the URL of the last hop.
+        - ``user_data`` — the ``user_data`` option, or ``None``.
+
+        ``primary_ip`` and ``retry_count`` are there when they are known.
+
+        Args:
+            key: One entry to look up. ``None`` asks for all of them.
+
+        Returns:
+            A mapping of every entry when ``key`` is ``None``; otherwise the
+            value under ``key``, or ``None`` when there is no such entry.
+        """
+        ...
+
+    async def cancel(self) -> None:
+        """Abandon the transfer and let go of what it was holding.
+
+        Afterwards ``get_info("canceled")`` reads ``True`` and
+        ``get_info("error")`` reads ``Response has been canceled.``, and
+        reading the body raises :class:`TransportError
+        <xtr_http_client_contracts.exception.transport_error.TransportError>`
+        with that message.
+        """
+        ...
+
+    async def get_content(self, throw: bool = True) -> bytes:
+        """Read the whole body, waiting for the rest of it to arrive.
+
+        Args:
+            throw: Whether an unsuccessful status is to be raised rather than
+                returned. The message is ``HTTP <code> returned for "<url>".``,
+                or the title and detail of the body when it is a JSON problem
+                document (RFC 7807, or its hydra form).
+
+        Returns:
+            Every byte of the body, empty when there was none.
+
+        Raises:
+            TransportError: When the transfer failed or was cancelled.
+            RedirectionError: On a 3xx once ``max_redirects`` was reached,
+                when ``throw``.
+            ClientError: On a 4xx, when ``throw``.
+            ServerError: On a 5xx, when ``throw``.
+        """
+        ...
+
+    async def to_array(self, throw: bool = True) -> dict[str, object]:
+        """Read the whole body and decode it as a JSON object.
+
+        Args:
+            throw: Whether an unsuccessful status is to be raised rather than
+                returned, as in :meth:`get_content`.
+
+        Returns:
+            What the body decoded to.
+
+        Raises:
+            DecodingError: When the body is empty or is not JSON.
+            JsonError: When the body is JSON but not an object.
+            TransportError: When the transfer failed or was cancelled.
+            RedirectionError: On a 3xx once ``max_redirects`` was reached,
+                when ``throw``.
+            ClientError: On a 4xx, when ``throw``.
+            ServerError: On a 5xx, when ``throw``.
+        """
+        ...
+
+    async def __aenter__(self) -> Self:
+        """Enter a block that owns the transfer.
+
+        Returns:
+            This response.
+        """
+        ...
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Close the body however the block ends, and nothing else.
+
+        Args:
+            exc_type: The class of the exception the block is leaving with,
+                or ``None`` when it is leaving normally.
+            exc: That exception.
+            traceback: Its traceback.
+        """
+        ...