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

xtr_http_client/internal/retry_count_response.py

@@ -0,0 +1,148 @@
+"""A response that also reports how many attempts it took to get it."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Self, cast, final
+
+from typing_extensions import override
+from xtr_http_client_contracts import HttpResponseInterface
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from types import TracebackType
+
+    from xtr_http_message_contracts import StreamInterface
+
+__all__ = ["with_retry_count"]
+
+
+def with_retry_count(response: HttpResponseInterface, retry_count: int) -> HttpResponseInterface:
+    """``response`` with ``retry_count`` among what its transfer reports.
+
+    A response is handed over by whoever opened the transfer, and the record
+    it reads from is that transfer's own; a client that wrapped another has
+    nothing to write into it. So the count is added by wrapping the response
+    instead — everything but ``get_info`` is the wrapped response's, which
+    keeps the one body and the one record rather than copying either.
+
+    Args:
+        response: The answer the last attempt came back with.
+        retry_count: How many attempts were made again before this one
+            answered.
+
+    Returns:
+        A response reading exactly as ``response`` does, whose
+        ``get_info("retry_count")`` is ``retry_count``.
+    """
+    return _RetryCountResponse(response, retry_count)
+
+
+@final
+class _RetryCountResponse(HttpResponseInterface):
+    __slots__ = ("_inner", "_retry_count")
+
+    def __init__(self, inner: HttpResponseInterface, retry_count: int) -> None:
+        self._inner = inner
+        self._retry_count = retry_count
+
+    @override
+    def get_status_code(self) -> int:
+        return self._inner.get_status_code()
+
+    @override
+    def get_reason_phrase(self) -> str:
+        return self._inner.get_reason_phrase()
+
+    @override
+    def with_status(self, code: int, reason_phrase: str = "") -> Self:
+        return self._around(self._inner.with_status(code, reason_phrase))
+
+    @override
+    def get_protocol_version(self) -> str:
+        return self._inner.get_protocol_version()
+
+    @override
+    def with_protocol_version(self, version: str) -> Self:
+        return self._around(self._inner.with_protocol_version(version))
+
+    @override
+    def get_headers(self) -> Mapping[str, Sequence[str]]:
+        return self._inner.get_headers()
+
+    @override
+    def has_header(self, name: str) -> bool:
+        return self._inner.has_header(name)
+
+    @override
+    def get_header(self, name: str) -> Sequence[str]:
+        return self._inner.get_header(name)
+
+    @override
+    def get_header_line(self, name: str) -> str:
+        return self._inner.get_header_line(name)
+
+    @override
+    def with_header(self, name: str, value: str | Sequence[str]) -> Self:
+        return self._around(self._inner.with_header(name, value))
+
+    @override
+    def with_added_header(self, name: str, value: str | Sequence[str]) -> Self:
+        return self._around(self._inner.with_added_header(name, value))
+
+    @override
+    def without_header(self, name: str) -> Self:
+        return self._around(self._inner.without_header(name))
+
+    @override
+    def get_body(self) -> StreamInterface:
+        return self._inner.get_body()
+
+    @override
+    def with_body(self, body: StreamInterface) -> Self:
+        return self._around(self._inner.with_body(body))
+
+    @override
+    def get_info(self, key: str | None = None) -> object:
+        if key is None:
+            whole = self._inner.get_info()
+            entries = (
+                dict(cast("Mapping[str, object]", whole)) if isinstance(whole, Mapping) else {}
+            )
+            entries["retry_count"] = self._retry_count
+
+            return entries
+        if key == "retry_count":
+            return self._retry_count
+
+        return self._inner.get_info(key)
+
+    @override
+    async def cancel(self) -> None:
+        await self._inner.cancel()
+
+    @override
+    async def get_content(self, throw: bool = True) -> bytes:
+        return await self._inner.get_content(throw)
+
+    @override
+    async def to_array(self, throw: bool = True) -> dict[str, object]:
+        return await self._inner.to_array(throw)
+
+    @override
+    async def __aenter__(self) -> Self:
+        _ = await self._inner.__aenter__()
+
+        return self
+
+    @override
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self._inner.__aexit__(exc_type, exc, traceback)
+
+    def _around(self, inner: HttpResponseInterface) -> Self:
+        return type(self)(inner, self._retry_count)

xtr_http_client/internal/retry_delay.py

@@ -0,0 +1,45 @@
+"""How long the server itself said to wait before asking again."""
+
+from __future__ import annotations
+
+import time
+from email.utils import parsedate_to_datetime
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from xtr_http_message_contracts import ResponseInterface
+
+__all__ = ["retry_after_ms"]
+
+
+def retry_after_ms(response: ResponseInterface) -> int | None:
+    """The wait a ``Retry-After`` header asks for, in milliseconds.
+
+    The header comes in two shapes — a number of seconds, or the date the
+    answer will be worth asking for again — and both are read, because which
+    one a server sends is the server's business. A date already past asks for
+    no wait at all rather than a negative one.
+
+    Args:
+        response: The answer that may be asking to be asked again later.
+
+    Returns:
+        The wait in milliseconds, or ``None`` when the header is absent or is
+        neither a number nor a date, which leaves the wait to the strategy.
+    """
+    after = response.get_header("retry-after")
+    if not after:
+        return None
+
+    value = after[0].strip()
+    try:
+        return int(float(value) * 1000)
+    except (OverflowError, ValueError):
+        pass
+
+    try:
+        when = parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+
+    return max(0, int(when.timestamp() - time.time())) * 1000

xtr_http_client/internal/retry_options.py

@@ -0,0 +1,98 @@
+"""The options a retrying client reads, rewrites and keeps to itself."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterable, Mapping, Sequence
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from xtr_http_message_contracts import RequestInterface
+
+__all__ = ["base_uri_rotation", "replays_body", "replays_request", "retries", "with_base_uri"]
+
+
+def base_uri_rotation(value: object) -> tuple[str, ...] | None:
+    """The base URIs an attempt moves along, or ``None`` when there is one URI.
+
+    Args:
+        value: What the ``base_uri`` option was given as.
+
+    Returns:
+        Every URI in order when several were named, or ``None`` when the
+        option is one URI, or none, which is for the wrapped client to resolve
+        against as it always does.
+    """
+    if isinstance(value, str) or not isinstance(value, Sequence):
+        return None
+
+    return tuple(str(uri) for uri in value)
+
+
+def with_base_uri(
+    options: Mapping[str, object],
+    base_uris: Sequence[str],
+    attempt: int,
+) -> dict[str, object]:
+    """``options`` carrying the one base URI this attempt is to be made against.
+
+    Moving along the list is what makes several base URIs worth naming: the
+    first attempt goes to the first, the second to the second, and once the
+    list runs out every further attempt stays on the last — the alternative
+    being to come back to a URI that has already refused.
+
+    Args:
+        options: The options the request is being made with.
+        base_uris: The URIs to move along, empty when none were named.
+        attempt: How many attempts came before this one.
+
+    Returns:
+        The options to hand the wrapped client, whose ``base_uri`` is one URI
+        or is gone — a list of them is this client's to walk, and means
+        nothing to a client that sends one request.
+    """
+    sent = dict(options)
+    if base_uris:
+        sent["base_uri"] = base_uris[min(attempt, len(base_uris) - 1)]
+    elif base_uri_rotation(sent.get("base_uri")) is not None:
+        del sent["base_uri"]
+
+    return sent
+
+
+def retries(value: object, fallback: int) -> int:
+    """How many times a request may be made again, as the option says or not.
+
+    Args:
+        value: What the ``max_retries`` option was given as.
+        fallback: What the client was built with, used when the option says
+            nothing.
+
+    Returns:
+        The number of retries allowed.
+    """
+    if isinstance(value, bool) or not isinstance(value, int):
+        return fallback
+
+    return value
+
+
+def replays_body(options: Mapping[str, object]) -> bool:
+    """Whether the body in ``options`` can be sent a second time.
+
+    A body produced as it goes is gone once it has gone out: whatever
+    produced it has been drained, and there is nothing left to send again. A
+    request carrying one is made once, because a retry would send a request
+    with no body at all rather than the request that failed.
+    """
+    return not isinstance(options.get("body"), AsyncIterable)
+
+
+def replays_request(request: RequestInterface) -> bool:
+    """Whether the body of ``request`` can be sent a second time.
+
+    A stream that cannot be rewound has the same problem as a body produced
+    as it goes: it has been read to its end by the attempt that failed.
+    """
+    body = request.get_body()
+
+    return body.get_size() == 0 or body.is_seekable()

xtr_http_client/mock_http_client.py

@@ -0,0 +1,253 @@
+"""The client that answers from a script, so a test never leaves the process."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Iterable, Iterator, Mapping
+from typing import TYPE_CHECKING, Final, cast, final
+
+from typing_extensions import Unpack, override
+from xtr_http_client_contracts import HttpClientInterface, RequestOptions
+from xtr_http_message import Request
+from xtr_service_contracts import ResetInterface
+
+from .exception import InvalidArgumentError, TransportError
+from .http_client_mixin import HttpClientMixin
+from .internal.debug_type import debug_type
+from .internal.httpx_request import target_url
+from .response.mock_response import MockResponse
+
+if TYPE_CHECKING:
+    from xtr_http_message_contracts import RequestInterface
+
+__all__ = ["MockHttpClient", "ResponseFactory"]
+
+ScriptedFactory = Callable[[str, str, RequestOptions], "MockResponse | Awaitable[MockResponse]"]
+"""Something called with a request, that says what is to come back for it."""
+
+ResponseFactory = MockResponse | ScriptedFactory | Iterable[MockResponse | ScriptedFactory]
+"""Where a scripted client's answers come from: one, many, or one per request."""
+
+_EMPTY: Final = "The response factory iterator passed to MockHttpClient is empty."
+_EXHAUSTED: Final = (
+    "No more response left in the response factory iterator passed to MockHttpClient: "
+    "the number of requests exceeds the number of responses."
+)
+
+# Nothing a factory could legitimately be, so it can stand for "the iterator
+# had nothing left" without `None` — a perfectly good thing to yield — meaning
+# that too.
+_NOTHING: Final = object()
+
+
+@final
+class MockHttpClient(HttpClientMixin, HttpClientInterface, ResetInterface):
+    """Answers every request from what a test wrote out, and opens no connection.
+
+    It is the same client as any other here — the options it refuses, the
+    defaults it starts from and the way a request and its options are merged
+    are all the ones a real transfer uses — with the transfer replaced by a
+    script. So a test exercises the code that calls out, down to the options
+    it passed, without a server to point it at.
+
+    ```python
+    client = MockHttpClient([MockResponse(b"first"), MockResponse(b"second")])
+    async with await client.request("GET", "/orders") as response:
+        assert await response.get_content() == b"first"
+    assert client.get_requests_count() == 1
+    ```
+
+    What the answers come from is whatever a test finds easiest to write:
+
+    - nothing, and every request is answered with an empty 200;
+    - one :class:`MockResponse <xtr_http_client.response.mock_response.MockResponse>`,
+      which answers one request, and a second request is a mistake, reported
+      as the script running out;
+    - an iterable of them, one per request, in order — a request past the end
+      of it is a mistake and is reported as one, since a test that makes more
+      requests than it wrote answers for is no longer testing what it says;
+    - a callable, which is handed the method, the URL and the merged options
+      and says what to answer with — the way to assert on the request that was
+      made, and to answer differently depending on it. It may be async.
+
+    An iterable may hold callables too, so one request in a sequence can be
+    answered that way while the rest are written out.
+
+    Nothing is followed and nothing is resolved: a 3xx is the answer, and a
+    relative URL is resolved against ``base_uri`` — which starts at
+    ``https://example.com`` so a test can say ``/orders`` and mean something.
+    """
+
+    __slots__ = ("_factory", "_requests_count")
+
+    _factory: ScriptedFactory | Iterator[MockResponse | ScriptedFactory] | None
+
+    def __init__(
+        self,
+        response_factory: ResponseFactory | None = None,
+        base_uri: str | None = "https://example.com",
+    ) -> None:
+        """Start from ``response_factory``, which nothing is taken from until asked.
+
+        Args:
+            response_factory: Where the answers come from.
+            base_uri: What a relative URL is resolved against. ``None`` leaves
+                a relative URL unresolvable, which is then refused.
+        """
+        super().__init__({"base_uri": base_uri})
+        self._requests_count = 0
+        self.set_response_factory(response_factory)
+
+    def set_response_factory(self, response_factory: ResponseFactory | None = None) -> None:
+        """Answer from ``response_factory`` from now on.
+
+        What was left of the previous one is dropped, and the count of
+        requests already made is kept: a test that changes its mind about the
+        answers has not unmade the requests.
+
+        Args:
+            response_factory: Where the answers come from.
+        """
+        if isinstance(response_factory, MockResponse):
+            # A single answer is one item of a script, so it answers one request.
+            self._factory = iter([response_factory])
+        elif isinstance(response_factory, Iterable):
+            # Taken one at a time from here on, so a generator is not drawn
+            # on until the request its answer is for.
+            self._factory = iter(response_factory)
+        else:
+            self._factory = response_factory
+
+    def get_requests_count(self) -> int:
+        """Return how many requests this client has been asked to make."""
+        return self._requests_count
+
+    @override
+    async def reset(self) -> None:
+        """Forget how many requests were made, leaving the answers as they are."""
+        self._requests_count = 0
+
+    @override
+    async def request(
+        self,
+        method: str,
+        url: str,
+        **options: Unpack[RequestOptions],
+    ) -> MockResponse:
+        """Answer a request for ``method`` and ``url`` from the script.
+
+        Args:
+            method: The HTTP method, in upper case.
+            url: The URL to request, absolute or relative to ``base_uri``.
+            **options: How the request would have been made.
+
+        Returns:
+            The scripted answer, issued for this request.
+
+        Raises:
+            InvalidArgumentError: For an invalid method, URL or option.
+            TransportError: When the script says the transfer fails, or has
+                no answer left to give.
+        """
+        self.validate_method(method)
+
+        return await self.send_request(Request(method, url), **options)
+
+    @override
+    async def send_request(
+        self,
+        request: RequestInterface,
+        **options: Unpack[RequestOptions],
+    ) -> MockResponse:
+        """Answer ``request`` from the script, the options filling what it leaves out.
+
+        Args:
+            request: The request that would have been sent.
+            **options: What the request leaves out.
+
+        Returns:
+            The scripted answer, issued for this request.
+
+        Raises:
+            InvalidArgumentError: For an invalid method, URL or option, and
+                for a body given both with the request and as an option.
+            TransportError: When the script says the transfer fails, has no
+                answer left to give, or gives something that is not an answer.
+        """
+        self.validate_options(options)
+        self.validate_method(request.get_method())
+        merged = self.merge_default_options(options, self._default_options)
+        self.validate_auth(merged)
+        self.validate_body(merged)
+
+        method = request.get_method()
+        url = _resolved(request, merged)
+        answer = await self._scripted(method, url, merged)
+        self._requests_count += 1
+
+        if not isinstance(answer, MockResponse):
+            raise TransportError(
+                "The response factory passed to MockHttpClient must return/yield an "
+                f'instance of MockResponse, "{debug_type(answer)}" given.'
+            )
+
+        return answer.issue(method, url, merged)
+
+    async def _scripted(self, method: str, url: str, options: Mapping[str, object]) -> object:
+        """Whatever the script offers for this request, answer or not."""
+        factory = self._factory
+
+        if factory is None:
+            return MockResponse()
+        if callable(factory):
+            return await _called(factory, method, url, options)
+
+        return await _called(_taken(factory, self._requests_count), method, url, options)
+
+
+def _taken(factory: Iterator[object], made: int) -> object:
+    """The next thing the script offers.
+
+    Raises:
+        TransportError: When there is nothing left — which is a test that
+            wrote no answers at all, or fewer than it makes requests, and
+            those are two different mistakes.
+    """
+    offered = next(factory, _NOTHING)
+    if offered is _NOTHING:
+        raise TransportError(_EXHAUSTED if made else _EMPTY)
+
+    return offered
+
+
+async def _called(
+    offered: object,
+    method: str,
+    url: str,
+    options: Mapping[str, object],
+) -> object:
+    """``offered`` itself, or what it answers with when it is something to call."""
+    if not callable(offered):
+        return offered
+
+    said = offered(method, url, cast("RequestOptions", options))
+    if isinstance(said, Awaitable):
+        return await said
+
+    return said
+
+
+def _resolved(request: RequestInterface, options: Mapping[str, object]) -> str:
+    """The URL the request is for, resolved and with ``query`` merged in.
+
+    Raises:
+        InvalidArgumentError: When the URL is relative and there is no base to
+            resolve it against, since what was asked for then names nothing.
+    """
+    url = target_url(request, options)
+    if url.is_relative_url:
+        raise InvalidArgumentError(
+            f'Invalid URL "{url}": it is relative, and no "base_uri" option '
+            "says what to resolve it against."
+        )
+
+    return str(url)