xtr-http-client 5.2.0__tar.gz → 6.0.0__tar.gz

{xtr_http_client-5.2.0 → xtr_http_client-6.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xtr-http-client
-Version: 5.2.0
+Version: 6.0.0
 Summary: An async HTTP client behind one interface: typed request options, bodies read on demand, scoped clients, a private-network guard and a mock client for tests.
 Keywords: http,http-client,request,response,mock,asyncio
 Author: Xterr
@@ -19,11 +19,11 @@ Classifier: Typing :: Typed
 Requires-Dist: typing-extensions>=4.4
 Requires-Dist: anyio>=4.0
 Requires-Dist: httpx>=0.27
-Requires-Dist: xtr-http-client-contracts>=5.0,<6
-Requires-Dist: xtr-http-message>=5.0,<6
-Requires-Dist: xtr-http-message-contracts>=5.0,<6
-Requires-Dist: xtr-logging-contracts>=5.0,<6
-Requires-Dist: xtr-service-contracts>=5.0,<6
+Requires-Dist: xtr-http-client-contracts>=6.0,<7
+Requires-Dist: xtr-http-message>=6.0,<7
+Requires-Dist: xtr-http-message-contracts>=6.0,<7
+Requires-Dist: xtr-logging-contracts>=6.0,<7
+Requires-Dist: xtr-service-contracts>=6.0,<7
 Requires-Dist: httpx[http2]>=0.27 ; extra == 'http2'
 Requires-Python: >=3.11
 Provides-Extra: http2
@@ -142,6 +142,9 @@ the rest. An option this client does not know is refused with `InvalidArgumentEr
 the closest one it does, because an option spelled wrong that was quietly dropped is a setting
 that silently never applied.
 
+A host `resolve` pins to an address stays pinned for the requests after it; `reset()` forgets
+every pin and keeps the connections open.
+
 A `body` mapping holding a file opened `"rb"` is uploaded as `multipart/form-data` — plain
 values as `data`, each file as a part named after its file and typed from that name — and a
 mapping without one stays url-encoded:

{xtr_http_client-5.2.0 → xtr_http_client-6.0.0}/README.md

@@ -111,6 +111,9 @@ the rest. An option this client does not know is refused with `InvalidArgumentEr
 the closest one it does, because an option spelled wrong that was quietly dropped is a setting
 that silently never applied.
 
+A host `resolve` pins to an address stays pinned for the requests after it; `reset()` forgets
+every pin and keeps the connections open.
+
 A `body` mapping holding a file opened `"rb"` is uploaded as `multipart/form-data` — plain
 values as `data`, each file as a part named after its file and typed from that name — and a
 mapping without one stays url-encoded:

{xtr_http_client-5.2.0 → xtr_http_client-6.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-http-client"
-version = "5.2.0"
+version = "6.0.0"
 description = "An async HTTP client behind one interface: typed request options, bodies read on demand, scoped clients, a private-network guard and a mock client for tests."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -29,11 +29,11 @@ dependencies = [
     "typing-extensions>=4.4",
     "anyio>=4.0",
     "httpx>=0.27",
-    "xtr-http-client-contracts>=5.0,<6",
-    "xtr-http-message>=5.0,<6",
-    "xtr-http-message-contracts>=5.0,<6",
-    "xtr-logging-contracts>=5.0,<6",
-    "xtr-service-contracts>=5.0,<6",
+    "xtr-http-client-contracts>=6.0,<7",
+    "xtr-http-message>=6.0,<7",
+    "xtr-http-message-contracts>=6.0,<7",
+    "xtr-logging-contracts>=6.0,<7",
+    "xtr-service-contracts>=6.0,<7",
 ]
 
 [[project.authors]]
@@ -58,10 +58,11 @@ dev = [
     "anyio>=4.0",
     "h2>=4.0",
     "ty>=0.0.83",
-    "xtr-clock>=5.0,<6",
-    "xtr-dependency-injection>=5.0,<6",
-    "xtr-http-foundation>=5.0,<6",
-    "xtr-rate-limiter>=5.0,<6",
+    "xtr-clock>=6.0,<7",
+    "xtr-dependency-injection>=6.0,<7",
+    "xtr-http-foundation>=6.0,<7",
+    "xtr-messenger>=6.0,<7",
+    "xtr-rate-limiter>=6.0,<7",
 ]
 
 [build-system]

{xtr_http_client-5.2.0 → xtr_http_client-6.0.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-http-client"
-version = "5.2.0"
+version = "6.0.0"
 description = "An async HTTP client behind one interface: typed request options, bodies read on demand, scoped clients, a private-network guard and a mock client for tests."
 readme = "README.md"
 authors = [
@@ -27,11 +27,11 @@ dependencies = [
     "typing-extensions>=4.4",
     "anyio>=4.0",
     "httpx>=0.27",
-    "xtr-http-client-contracts>=5.0,<6",
-    "xtr-http-message>=5.0,<6",
-    "xtr-http-message-contracts>=5.0,<6",
-    "xtr-logging-contracts>=5.0,<6",
-    "xtr-service-contracts>=5.0,<6",
+    "xtr-http-client-contracts>=6.0,<7",
+    "xtr-http-message>=6.0,<7",
+    "xtr-http-message-contracts>=6.0,<7",
+    "xtr-logging-contracts>=6.0,<7",
+    "xtr-service-contracts>=6.0,<7",
 ]
 
 [project.optional-dependencies]
@@ -58,11 +58,13 @@ dev = [
     "anyio>=4.0",
     "h2>=4.0",
     "ty>=0.0.83",
-    "xtr-clock>=5.0,<6",
-    "xtr-dependency-injection>=5.0,<6",
+    "xtr-clock>=6.0,<7",
+    "xtr-dependency-injection>=6.0,<7",
     # The networks NoPrivateNetworkHttpClient refuses; optional for an application.
-    "xtr-http-foundation>=5.0,<6",
-    "xtr-rate-limiter>=5.0,<6",
+    "xtr-http-foundation>=6.0,<7",
+    # A worker resets the clients between the messages it handles in the kernel tests.
+    "xtr-messenger>=6.0,<7",
+    "xtr-rate-limiter>=6.0,<7",
 ]
 
 [build-system]

{xtr_http_client-5.2.0 → xtr_http_client-6.0.0}/src/xtr_http_client/httpx_http_client.py

@@ -10,11 +10,12 @@ import httpx
 from typing_extensions import Unpack, override
 from xtr_http_client_contracts import HttpClientInterface
 from xtr_http_message import Request
+from xtr_service_contracts import ResetInterface
 
 from .http_client_mixin import HttpClientMixin
 from .internal.httpx_clients import HttpxClients
 from .internal.httpx_errors import timed_out, transport_error
-from .internal.httpx_redirect import next_hop, same_origin
+from .internal.httpx_redirect import exchange
 from .internal.httpx_request import (
     assemble_headers,
     assemble_payload,
@@ -38,7 +39,7 @@ __all__ = ["HttpxHttpClient"]
 
 
 @final
-class HttpxHttpClient(HttpClientMixin, HttpClientInterface):
+class HttpxHttpClient(HttpClientMixin, HttpClientInterface, ResetInterface):
     """Sends requests over real connections, and hands back answers as they arrive.
 
     A request returns once the status line and the headers are in, whatever
@@ -51,8 +52,10 @@ class HttpxHttpClient(HttpClientMixin, HttpClientInterface):
     has no ``Authorization`` of its own — which is what lets one set of
     client-wide defaults sit under requests that each know their own mind.
     What each part of an outgoing request is assembled from is in
-    :mod:`xtr_http_client.internal.httpx_request`; what is here is the
-    exchange, and the redirect chain it may turn into.
+    :mod:`xtr_http_client.internal.httpx_request`, and the redirect chain an
+    exchange may turn into is followed in
+    :mod:`xtr_http_client.internal.httpx_redirect`; what is here is the
+    exchange itself, under its deadline.
 
     Connections are pooled by how they connect rather than by host: a proxy,
     a trust store, a protocol version and the deadlines all decide what a
@@ -60,6 +63,10 @@ class HttpxHttpClient(HttpClientMixin, HttpClientInterface):
     ``max_host_connections`` is each pool's ceiling across every host it
     reaches.
 
+    A host a request pins to an address through ``resolve`` stays pinned for
+    the requests after it, in the pool it went through; :meth:`reset` forgets
+    every pin, and keeps the connections open until the client is closed.
+
     ```python
     async with HttpxHttpClient(max_host_connections=4) as client:
         response = await client.request("GET", "https://example.com/orders")
@@ -164,6 +171,11 @@ class HttpxHttpClient(HttpClientMixin, HttpClientInterface):
 
         return await self._send(client, outgoing, merged, headers)
 
+    @override
+    async def reset(self) -> None:
+        """Forget the address every host was pinned to, keeping the connections open."""
+        self._clients.reset()
+
     async def aclose(self) -> None:
         """Close every pool, and with it every connection this client holds."""
         await self._clients.aclose()
@@ -207,7 +219,7 @@ class HttpxHttpClient(HttpClientMixin, HttpClientInterface):
 
         try:
             with anyio.fail_after(limit):
-                response, history = await _exchange(
+                response, history = await exchange(
                     client,
                     outgoing,
                     _basic_credentials(options, headers),
@@ -229,43 +241,6 @@ class HttpxHttpClient(HttpClientMixin, HttpClientInterface):
         )
 
 
-async def _exchange(
-    client: httpx.AsyncClient,
-    outgoing: httpx.Request,
-    auth: tuple[str, str] | None,
-    max_redirects: int,
-) -> tuple[httpx.Response, list[httpx.Response]]:
-    """Send, then follow where each answer points until one points nowhere.
-
-    Following is done here, a hop at a time, for the one thing the backend
-    cannot be told: credentials belong to the host they were meant for, so an
-    ``Authorization`` the backend dropped on the way out of that host is put
-    back the moment the chain returns to it, and nowhere else.
-    """
-    response = await client.send(outgoing, auth=auth, stream=True, follow_redirects=False)
-    history: list[httpx.Response] = []
-    origin = response.request.url
-    authorization = cast("str | None", response.request.headers.get("authorization"))
-
-    while len(history) < max_redirects:
-        following = next_hop(response)
-        if following is None:
-            break
-
-        if (
-            authorization is not None
-            and "authorization" not in following.headers
-            and same_origin(following.url, origin)
-        ):
-            following.headers["Authorization"] = authorization
-
-        history.append(response)
-        await response.aclose()
-        response = await client.send(following, stream=True, follow_redirects=False)
-
-    return response, history
-
-
 def _reachable(url: str) -> str:
     """``url`` with every part of it written in the form that reaches it.
 

{xtr_http_client-5.2.0 → xtr_http_client-6.0.0}/src/xtr_http_client/internal/httpx_clients.py

@@ -43,8 +43,8 @@ class HttpxClients:
     change in them asks for a different pool rather than being ignored.
 
     Each pool also remembers the addresses that requests pinned their hosts
-    to, for as long as the pool lives: a host reached at an address once is
-    reached at it again, without asking a resolver a second time.
+    to, until :meth:`reset` or :meth:`aclose`: a host reached at an address
+    once is reached at it again, without asking a resolver a second time.
 
     ``max_connections`` is the backend's pool-wide ceiling, not a per-host
     one: it counts every connection the pool holds, whichever host each of
@@ -90,6 +90,15 @@ class HttpxClients:
 
         return client, self._resolved[key]
 
+    def reset(self) -> None:
+        """Forget the address every host was pinned to, keeping every pool open.
+
+        A pin is what the requests of one unit of work asked for; the
+        connections are how the next one gets anywhere, so they stay.
+        """
+        for resolved in self._resolved.values():
+            resolved.clear()
+
     async def aclose(self) -> None:
         """Close every pool, and with it every connection any of them holds."""
         clients = list(self._clients.values())

xtr_http_client-6.0.0/src/xtr_http_client/internal/httpx_redirect.py

@@ -0,0 +1,109 @@
+"""Following a redirect chain: where each answer points, and whether it stays where it began."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+if TYPE_CHECKING:
+    import httpx
+
+__all__ = ["exchange", "next_hop", "same_origin"]
+
+
+async def exchange(
+    client: httpx.AsyncClient,
+    outgoing: httpx.Request,
+    auth: tuple[str, str] | None,
+    max_redirects: int,
+) -> tuple[httpx.Response, list[httpx.Response]]:
+    """Send, then follow where each answer points until one points nowhere.
+
+    Following is done here, a hop at a time, for the one thing the backend
+    cannot be told: credentials belong to the host they were meant for, so an
+    ``Authorization`` the backend dropped on the way out of that host is put
+    back the moment the chain returns to it, and nowhere else.
+
+    Args:
+        client: The pool the request and every hop after it are sent through.
+        outgoing: The request to send.
+        auth: The user and password the first request authenticates with.
+        max_redirects: How many hops may be followed.
+
+    Returns:
+        The last answer, and every answer before it, oldest first.
+    """
+    response = await client.send(outgoing, auth=auth, stream=True, follow_redirects=False)
+    history: list[httpx.Response] = []
+    origin = response.request.url
+    authorization = cast("str | None", response.request.headers.get("authorization"))
+
+    while len(history) < max_redirects:
+        following = next_hop(response)
+        if following is None:
+            break
+
+        if (
+            authorization is not None
+            and "authorization" not in following.headers
+            and same_origin(following.url, origin)
+        ):
+            following.headers["Authorization"] = authorization
+
+        history.append(response)
+        await response.aclose()
+        response = await client.send(following, stream=True, follow_redirects=False)
+
+    return response, history
+
+
+def next_hop(response: httpx.Response) -> httpx.Request | None:
+    """Return the request that following ``response`` would make.
+
+    Args:
+        response: The answer to read a redirect off.
+
+    Returns:
+        The next request, or ``None`` when there is nowhere to go — either
+        because the answer is not a redirect, or because where it points is
+        not somewhere a request can be made to.
+    """
+    following = response.next_request
+    if following is None:
+        return None
+    location = cast("str", response.headers.get("location", ""))
+    if _names_no_host(location) or not following.url.host:
+        return None
+
+    return following
+
+
+def same_origin(one: httpx.URL, other: httpx.URL) -> bool:
+    """Tell whether two URLs name the same scheme, host and port.
+
+    Args:
+        one: A URL.
+        other: The URL to compare it with.
+
+    Returns:
+        ``True`` when a connection to either would be a connection to the
+        same place.
+    """
+    return (one.scheme, one.host, one.port) == (other.scheme, other.host, other.port)
+
+
+def _names_no_host(location: str) -> bool:
+    """Whether a Location names an authority and then leaves it empty.
+
+    ``//?foo=bar`` says "another host, the same scheme" and names no host, so
+    there is nowhere for it to point; a relative reference such as ``..``
+    names no authority at all, which is not the same thing — it is resolved
+    against the URL it arrived on.
+    """
+    if not location.startswith("//"):
+        return False
+
+    authority = location[2:]
+    for delimiter in ("/", "?", "#"):
+        authority = authority.partition(delimiter)[0]
+
+    return authority == ""

xtr_http_client-5.2.0/src/xtr_http_client/internal/httpx_redirect.py

@@ -1,63 +0,0 @@
-"""Where an answer points, and whether following it stays where it started."""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, cast
-
-if TYPE_CHECKING:
-    import httpx
-
-__all__ = ["next_hop", "same_origin"]
-
-
-def next_hop(response: httpx.Response) -> httpx.Request | None:
-    """Return the request that following ``response`` would make.
-
-    Args:
-        response: The answer to read a redirect off.
-
-    Returns:
-        The next request, or ``None`` when there is nowhere to go — either
-        because the answer is not a redirect, or because where it points is
-        not somewhere a request can be made to.
-    """
-    following = response.next_request
-    if following is None:
-        return None
-    location = cast("str", response.headers.get("location", ""))
-    if _names_no_host(location) or not following.url.host:
-        return None
-
-    return following
-
-
-def same_origin(one: httpx.URL, other: httpx.URL) -> bool:
-    """Tell whether two URLs name the same scheme, host and port.
-
-    Args:
-        one: A URL.
-        other: The URL to compare it with.
-
-    Returns:
-        ``True`` when a connection to either would be a connection to the
-        same place.
-    """
-    return (one.scheme, one.host, one.port) == (other.scheme, other.host, other.port)
-
-
-def _names_no_host(location: str) -> bool:
-    """Whether a Location names an authority and then leaves it empty.
-
-    ``//?foo=bar`` says "another host, the same scheme" and names no host, so
-    there is nowhere for it to point; a relative reference such as ``..``
-    names no authority at all, which is not the same thing — it is resolved
-    against the URL it arrived on.
-    """
-    if not location.startswith("//"):
-        return False
-
-    authority = location[2:]
-    for delimiter in ("/", "?", "#"):
-        authority = authority.partition(delimiter)[0]
-
-    return authority == ""