xtr-http-client 4.0.4__tar.gz → 4.1.0__tar.gz

{xtr_http_client-4.0.4 → xtr_http_client-4.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xtr-http-client
-Version: 4.0.4
+Version: 4.1.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
@@ -20,18 +20,13 @@ Requires-Dist: typing-extensions>=4.4
 Requires-Dist: anyio>=4.0
 Requires-Dist: httpx>=0.27
 Requires-Dist: xtr-http-client-contracts>=4.0,<5
-Requires-Dist: xtr-http-foundation>=4.0,<5
 Requires-Dist: xtr-http-message>=4.0,<5
 Requires-Dist: xtr-http-message-contracts>=4.0,<5
 Requires-Dist: xtr-logging-contracts>=4.0,<5
 Requires-Dist: xtr-service-contracts>=4.0,<5
-Requires-Dist: xtr-dependency-injection>=4.0,<5 ; extra == 'di'
 Requires-Dist: httpx[http2]>=0.27 ; extra == 'http2'
-Requires-Dist: xtr-rate-limiter>=4.0,<5 ; extra == 'throttling'
 Requires-Python: >=3.11
-Provides-Extra: di
 Provides-Extra: http2
-Provides-Extra: throttling
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -64,12 +59,18 @@ calls out sees one type however much is layered under it.
 
 ```sh
 uv add xtr-http-client
-uv add "xtr-http-client[di]"            # + the bundle
-uv add "xtr-http-client[throttling]"    # + the limiter the throttling client paces by
-uv add "xtr-http-client[http2]"         # + the framing a request asking for version "2" needs
+uv add "xtr-http-client[http2]"                   # + the framing a request asking for version "2" needs
+uv add xtr-http-client xtr-dependency-injection   # + the container, for the HttpClientBundle
+uv add xtr-rate-limiter                           # beside it: the limiter the throttling client paces by
+uv add xtr-http-foundation                        # beside it: the networks the private-network guard refuses
 ```
 
-Requires Python 3.11+.
+Requires Python 3.11+. `http2` is the only extra, and the container is not a dependency: the
+bundle is used when [xtr-dependency-injection](../xtr-dependency-injection) is installed beside the
+package, never as an extra, and every client works without it, built by hand as below. Installed
+beside it too, [xtr-rate-limiter](../xtr-rate-limiter) supplies the limiter `ThrottlingHttpClient`
+paces by, and [xtr-http-foundation](../xtr-http-foundation) the networks
+`NoPrivateNetworkHttpClient` refuses.
 
 ## Quick start
 
@@ -250,9 +251,9 @@ from xtr_http_client import ThrottlingHttpClient
 client = ThrottlingHttpClient(inner, limiter)
 ```
 
-`limiter` is an [xtr-rate-limiter](../xtr-rate-limiter) `LimiterInterface`, from the
-`throttling` extra. A token is booked before each request and the request waits for the moment
-that booking is due; booking first and waiting after is what makes the pace hold under
+`limiter` is an [xtr-rate-limiter](../xtr-rate-limiter) `LimiterInterface`, from that package
+installed beside this one. A token is booked before each request and the request waits for the
+moment that booking is due; booking first and waiting after is what makes the pace hold under
 concurrency, since requests then leave in the order they were asked for rather than all at
 once. Which requests share a pace is decided by which of them are given the same limiter — one
 per host, one per account, one for the whole application — and a copy made by `with_options()`
@@ -308,6 +309,10 @@ alike. `subnets` replaces that set and `allow_list` opens one receiver without o
 network it sits in; both take addresses or CIDR networks, never host names. What a host
 resolved to is remembered for the client's life, and `reset()` forgets it.
 
+xtr-http-foundation is not a dependency: install it beside this package (`uv add
+xtr-http-foundation`) to use the guard. Without it, building `NoPrivateNetworkHttpClient`
+raises `LogicError`, so nothing goes out unchecked.
+
 ### `MockHttpClient` — answer from a script
 
 The same client as any other here — the options it refuses, the defaults it starts from and the
@@ -370,8 +375,9 @@ Everything adding this package to an application on
 [xtr-dependency-injection](../xtr-dependency-injection) takes — and, read backwards, what
 removing it undoes.
 
-- **Install** — `uv add "xtr-http-client[di]"`; add `throttling` to pace a client with an
-  [xtr-rate-limiter](../xtr-rate-limiter) limiter, `http2` to ask for HTTP/2.
+- **Install** — `uv add xtr-http-client xtr-dependency-injection`: the bundle needs the container
+  installed beside it, never as an extra. Add `http2` to ask for HTTP/2, and install
+  [xtr-rate-limiter](../xtr-rate-limiter) beside it to pace a client with one of its limiters.
 - **Recipe** — `uv run xtr-recipes recipes:sync` does the *Activate* step below: it lists
   `HttpClientBundle`. There is no config file, environment or ignore line to write; it prints the
   step to name the services the application calls in `config/http_client.py`, which a recipe
@@ -392,6 +398,10 @@ removing it undoes.
 
 ## Kernel / bundle
 
+With [xtr-dependency-injection](../xtr-dependency-injection) installed beside the package — it is
+not a dependency, and nothing outside `xtr_http_client.bundle` needs it — list the bundle, then
+configure the clients:
+
 ```python
 # app/bundles.py
 from xtr_http_client.bundle import HttpClientBundle

{xtr_http_client-4.0.4 → xtr_http_client-4.1.0}/README.md

@@ -28,12 +28,18 @@ calls out sees one type however much is layered under it.
 
 ```sh
 uv add xtr-http-client
-uv add "xtr-http-client[di]"            # + the bundle
-uv add "xtr-http-client[throttling]"    # + the limiter the throttling client paces by
-uv add "xtr-http-client[http2]"         # + the framing a request asking for version "2" needs
+uv add "xtr-http-client[http2]"                   # + the framing a request asking for version "2" needs
+uv add xtr-http-client xtr-dependency-injection   # + the container, for the HttpClientBundle
+uv add xtr-rate-limiter                           # beside it: the limiter the throttling client paces by
+uv add xtr-http-foundation                        # beside it: the networks the private-network guard refuses
 ```
 
-Requires Python 3.11+.
+Requires Python 3.11+. `http2` is the only extra, and the container is not a dependency: the
+bundle is used when [xtr-dependency-injection](../xtr-dependency-injection) is installed beside the
+package, never as an extra, and every client works without it, built by hand as below. Installed
+beside it too, [xtr-rate-limiter](../xtr-rate-limiter) supplies the limiter `ThrottlingHttpClient`
+paces by, and [xtr-http-foundation](../xtr-http-foundation) the networks
+`NoPrivateNetworkHttpClient` refuses.
 
 ## Quick start
 
@@ -214,9 +220,9 @@ from xtr_http_client import ThrottlingHttpClient
 client = ThrottlingHttpClient(inner, limiter)
 ```
 
-`limiter` is an [xtr-rate-limiter](../xtr-rate-limiter) `LimiterInterface`, from the
-`throttling` extra. A token is booked before each request and the request waits for the moment
-that booking is due; booking first and waiting after is what makes the pace hold under
+`limiter` is an [xtr-rate-limiter](../xtr-rate-limiter) `LimiterInterface`, from that package
+installed beside this one. A token is booked before each request and the request waits for the
+moment that booking is due; booking first and waiting after is what makes the pace hold under
 concurrency, since requests then leave in the order they were asked for rather than all at
 once. Which requests share a pace is decided by which of them are given the same limiter — one
 per host, one per account, one for the whole application — and a copy made by `with_options()`
@@ -272,6 +278,10 @@ alike. `subnets` replaces that set and `allow_list` opens one receiver without o
 network it sits in; both take addresses or CIDR networks, never host names. What a host
 resolved to is remembered for the client's life, and `reset()` forgets it.
 
+xtr-http-foundation is not a dependency: install it beside this package (`uv add
+xtr-http-foundation`) to use the guard. Without it, building `NoPrivateNetworkHttpClient`
+raises `LogicError`, so nothing goes out unchecked.
+
 ### `MockHttpClient` — answer from a script
 
 The same client as any other here — the options it refuses, the defaults it starts from and the
@@ -334,8 +344,9 @@ Everything adding this package to an application on
 [xtr-dependency-injection](../xtr-dependency-injection) takes — and, read backwards, what
 removing it undoes.
 
-- **Install** — `uv add "xtr-http-client[di]"`; add `throttling` to pace a client with an
-  [xtr-rate-limiter](../xtr-rate-limiter) limiter, `http2` to ask for HTTP/2.
+- **Install** — `uv add xtr-http-client xtr-dependency-injection`: the bundle needs the container
+  installed beside it, never as an extra. Add `http2` to ask for HTTP/2, and install
+  [xtr-rate-limiter](../xtr-rate-limiter) beside it to pace a client with one of its limiters.
 - **Recipe** — `uv run xtr-recipes recipes:sync` does the *Activate* step below: it lists
   `HttpClientBundle`. There is no config file, environment or ignore line to write; it prints the
   step to name the services the application calls in `config/http_client.py`, which a recipe
@@ -356,6 +367,10 @@ removing it undoes.
 
 ## Kernel / bundle
 
+With [xtr-dependency-injection](../xtr-dependency-injection) installed beside the package — it is
+not a dependency, and nothing outside `xtr_http_client.bundle` needs it — list the bundle, then
+configure the clients:
+
 ```python
 # app/bundles.py
 from xtr_http_client.bundle import HttpClientBundle

{xtr_http_client-4.0.4 → xtr_http_client-4.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-http-client"
-version = "4.0.4"
+version = "4.1.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"
@@ -30,7 +30,6 @@ dependencies = [
     "anyio>=4.0",
     "httpx>=0.27",
     "xtr-http-client-contracts>=4.0,<5",
-    "xtr-http-foundation>=4.0,<5",
     "xtr-http-message>=4.0,<5",
     "xtr-http-message-contracts>=4.0,<5",
     "xtr-logging-contracts>=4.0,<5",
@@ -42,9 +41,7 @@ name = "Xterr"
 email = "me@xterr.dev"
 
 [project.optional-dependencies]
-di = ["xtr-dependency-injection>=4.0,<5"]
 http2 = ["httpx[http2]>=0.27"]
-throttling = ["xtr-rate-limiter>=4.0,<5"]
 
 [project.entry-points."xtr_dependency_injection.bundles"]
 http_client = "xtr_http_client.bundle:HttpClientBundle"
@@ -63,6 +60,7 @@ dev = [
     "ty>=0.0.83",
     "xtr-clock>=4.0,<5",
     "xtr-dependency-injection>=4.0,<5",
+    "xtr-http-foundation>=4.0,<5",
     "xtr-rate-limiter>=4.0,<5",
 ]
 

{xtr_http_client-4.0.4 → xtr_http_client-4.1.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-http-client"
-version = "4.0.4"
+version = "4.1.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 = [
@@ -28,7 +28,6 @@ dependencies = [
     "anyio>=4.0",
     "httpx>=0.27",
     "xtr-http-client-contracts>=4.0,<5",
-    "xtr-http-foundation>=4.0,<5",
     "xtr-http-message>=4.0,<5",
     "xtr-http-message-contracts>=4.0,<5",
     "xtr-logging-contracts>=4.0,<5",
@@ -36,18 +35,10 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-di = [
-    "xtr-dependency-injection>=4.0,<5",
-]
 # The HTTP/2 framing, which only a request asking for version "2" needs.
 http2 = [
     "httpx[http2]>=0.27",
 ]
-# The limiter the throttling client paces requests by; nothing else needs it,
-# so the package imports and every other client works without it.
-throttling = [
-    "xtr-rate-limiter>=4.0,<5",
-]
 
 # Advertises the bundle so debug:bundles can name it when installed but not listed.
 # Advertising activates nothing: an application lists the bundles it wants.
@@ -69,6 +60,8 @@ dev = [
     "ty>=0.0.83",
     "xtr-clock>=4.0,<5",
     "xtr-dependency-injection>=4.0,<5",
+    # The networks NoPrivateNetworkHttpClient refuses; optional for an application.
+    "xtr-http-foundation>=4.0,<5",
     "xtr-rate-limiter>=4.0,<5",
 ]
 

{xtr_http_client-4.0.4 → xtr_http_client-4.1.0}/src/xtr_http_client/.agents/skills/xtr-http-client/SKILL.md

@@ -28,6 +28,9 @@ client, so the calling code sees one type however deep the stack is.
   `MockHttpClient`.
 - Options are the contract's `RequestOptions`. An option it does not know is refused, never
   ignored.
+- In an application, with xtr-dependency-injection installed beside the package (it is not a
+  dependency): activate `HttpClientBundle` and inject `HttpClientInterface`. Without the
+  container, build the clients yourself; only `xtr_http_client.bundle` needs it.
 
 ## Make a request
 
@@ -109,7 +112,7 @@ client = RetryableHttpClient(inner, GenericRetryStrategy([500, 502, 503]), max_r
 ```python
 from xtr_http_client import NoPrivateNetworkHttpClient, ThrottlingHttpClient, TraceableHttpClient
 
-paced = ThrottlingHttpClient(inner, limiter)  # xtr-rate-limiter LimiterInterface, [throttling]
+paced = ThrottlingHttpClient(inner, limiter)  # a LimiterInterface from xtr-rate-limiter
 traced = TraceableHttpClient(inner)
 guarded = NoPrivateNetworkHttpClient(inner, allow_list=("10.1.2.3",))
 ```
@@ -125,6 +128,8 @@ guarded = NoPrivateNetworkHttpClient(inner, allow_list=("10.1.2.3",))
   Refusal is `TransportError`: `Host "<host>" is blocked for "<url>".`. Without `subnets` it
   refuses `IpUtils.PRIVATE_SUBNETS`; `allow_list` opens one receiver. Addresses and CIDR
   networks only — never host names.
+  It needs xtr-http-foundation installed beside this package (`uv add xtr-http-foundation`);
+  without it, building the guard raises `LogicError`.
 
 ## Use the transport directly
 
@@ -187,8 +192,9 @@ async def test_it_reads_the_created_order() -> None:
 `HttpClientBundle`. There is no config file, environment or ignore line to write; it prints the
 step to name the services the application calls, which a recipe cannot make for you.
 
-1. **Install** — `uv add "xtr-http-client[di]"`; add `throttling` to pace a client with an
-   xtr-rate-limiter limiter, `http2` to ask for HTTP/2.
+1. **Install** — `uv add xtr-http-client xtr-dependency-injection`: the bundle needs the container
+   installed beside it, never as an extra. Add `http2` to ask for HTTP/2, and install
+   xtr-rate-limiter beside it to pace a client with one of its limiters.
 2. **Activate** — `HttpClientBundle: {"all": True}` in `BUNDLES` in `<app>/bundles.py`
    (`from xtr_http_client.bundle import HttpClientBundle`).
 3. **Brings along** — the rate limiter bundle when xtr-rate-limiter is installed.

{xtr_http_client-4.0.4 → xtr_http_client-4.1.0}/src/xtr_http_client/bundle/_clients.py

@@ -124,7 +124,7 @@ def _mock_transport() -> MockHttpClient:
 
 def _limiters(rate_limiter: str) -> object:
     """Return the annotation asking for the limiter factory ``rate_limiter`` names."""
-    # The throttling extra is optional: a client is only paced while the rate
+    # xtr-rate-limiter is optional: a client is only paced while the rate
     # limiter bundle is active, which proves it installed.
     from xtr_rate_limiter import RateLimiterFactoryInterface  # noqa: PLC0415
 

{xtr_http_client-4.0.4 → xtr_http_client-4.1.0}/src/xtr_http_client/bundle/client_options_config.py

@@ -44,7 +44,7 @@ class ClientOptionsConfig:
         extra: Additional options a client may ignore.
         retry_failed: Whether and how a failed request is made again.
         rate_limiter: The name of the xtr-rate-limiter limiter every request
-            waits its turn from; needs the ``throttling`` extra.
+            waits its turn from; needs xtr-rate-limiter installed.
     """
 
     _NOT_OPTIONS: ClassVar[frozenset[str]] = frozenset({"retry_failed", "rate_limiter"})

{xtr_http_client-4.0.4 → xtr_http_client-4.1.0}/src/xtr_http_client/bundle/http_client_bundle.py

@@ -81,5 +81,5 @@ def _check_pace(owner: str, rate_limiter: str | None, pacing: bool) -> None:
     if rate_limiter is not None and not pacing:
         raise InvalidArgumentError(
             f'{owner} is paced by the "{rate_limiter}" rate limiter, but the rate limiter '
-            f'bundle is not active: install "xtr-http-client[throttling]".'
+            "bundle is not active: install xtr-rate-limiter."
         )

{xtr_http_client-4.0.4 → xtr_http_client-4.1.0}/src/xtr_http_client/exception/__init__.py

@@ -8,7 +8,8 @@ at the root, :class:`TransportError` for "there is no answer" (with
 :class:`ClientError`, :class:`ServerError`), :class:`DecodingError` for an
 answer that is not what it was read as (with :class:`JsonError` for a body that
 is not the JSON it was read as), and :class:`InvalidArgumentError` for a request
-this client refuses to make.
+this client refuses to make. :class:`LogicError` is this package's own: a client
+built in a way that cannot work.
 """
 
 from __future__ import annotations
@@ -26,6 +27,8 @@ from xtr_http_client_contracts import (
     TransportTimeoutError,
 )
 
+from .logic_error import LogicError
+
 __all__ = [
     "ClientError",
     "DecodingError",
@@ -33,6 +36,7 @@ __all__ = [
     "HttpError",
     "InvalidArgumentError",
     "JsonError",
+    "LogicError",
     "RedirectionError",
     "ServerError",
     "TransportError",

xtr_http_client-4.1.0/src/xtr_http_client/exception/logic_error.py

@@ -0,0 +1,16 @@
+"""This library was used in a way that cannot work."""
+
+from __future__ import annotations
+
+from xtr_http_client_contracts import HttpClientError
+
+__all__ = ["LogicError"]
+
+
+class LogicError(HttpClientError, RuntimeError):
+    """A client was built in a way that cannot work, whatever it is asked to send.
+
+    Building the private-network guard without xtr-http-foundation installed,
+    which holds the networks it refuses, is a mistake in the application's
+    setup rather than in a request, so retrying it changes nothing.
+    """

{xtr_http_client-4.0.4 → xtr_http_client-4.1.0}/src/xtr_http_client/no_private_network_http_client.py

@@ -12,11 +12,10 @@ from urllib.parse import urljoin
 import anyio
 from typing_extensions import Unpack, override
 from xtr_http_client_contracts import HttpClientInterface
-from xtr_http_foundation import IpUtils
 from xtr_http_message import Request, Stream, Uri
 from xtr_service_contracts import ResetInterface
 
-from .exception import InvalidArgumentError, TransportError
+from .exception import InvalidArgumentError, LogicError, TransportError
 from .internal.option_merge import as_options
 
 if TYPE_CHECKING:
@@ -24,6 +23,7 @@ if TYPE_CHECKING:
     from typing import Self
 
     from xtr_http_client_contracts import HttpResponseInterface, RequestOptions
+    from xtr_http_foundation import IpUtils
     from xtr_http_message_contracts import RequestInterface
 
 __all__ = ["NoPrivateNetworkHttpClient"]
@@ -64,9 +64,12 @@ class NoPrivateNetworkHttpClient(HttpClientInterface, ResetInterface):
     What a host resolves to is remembered for as long as this client lives,
     so a chain of hops back to the same host asks the resolver once;
     :meth:`reset` forgets it.
+
+    The networks it refuses come from xtr-http-foundation, which is not a
+    dependency of this package: install it beside it to use this client.
     """
 
-    __slots__ = ("_allow_list", "_client", "_dns_cache", "_resolver", "_subnets")
+    __slots__ = ("_allow_list", "_client", "_dns_cache", "_ip_utils", "_resolver", "_subnets")
 
     def __init__(
         self,
@@ -89,9 +92,14 @@ class NoPrivateNetworkHttpClient(HttpClientInterface, ResetInterface):
                 have to be resolved, and could point anywhere by then.
             resolver: What every address of a host and port is asked of.
                 ``None`` asks the platform's own resolver.
+
+        Raises:
+            LogicError: When xtr-http-foundation is not installed, since there
+                is then no way to tell which addresses to refuse.
         """
+        self._ip_utils = _ip_utils()
         self._client = client
-        self._subnets = _entries(subnets) if subnets is not None else IpUtils.PRIVATE_SUBNETS
+        self._subnets = _entries(subnets) if subnets is not None else self._ip_utils.PRIVATE_SUBNETS
         self._allow_list = _entries(allow_list)
         self._resolver = resolver if resolver is not None else _getaddrinfo
         self._dns_cache: dict[str, Sequence[str]] = {}
@@ -258,10 +266,29 @@ class NoPrivateNetworkHttpClient(HttpClientInterface, ResetInterface):
         The allow list is read first, so one internal receiver is opened
         without opening the network it sits in.
         """
-        if self._allow_list and IpUtils.check_ip(address, self._allow_list):
+        if self._allow_list and self._ip_utils.check_ip(address, self._allow_list):
             return False
 
-        return IpUtils.check_ip(address, self._subnets)
+        return self._ip_utils.check_ip(address, self._subnets)
+
+
+def _ip_utils() -> type[IpUtils]:
+    """The address checks, from xtr-http-foundation when it is installed.
+
+    Raises:
+        LogicError: When it is not, so the guard fails where it is built
+            rather than letting through a request it could not check.
+    """
+    try:
+        # Optional package, so imported only when a guard is built (hence PLC0415).
+        from xtr_http_foundation import IpUtils  # noqa: PLC0415
+    except ImportError as error:
+        raise LogicError(
+            'You cannot use "NoPrivateNetworkHttpClient" if xtr-http-foundation is not '
+            'installed. Try running "uv add xtr-http-foundation".'
+        ) from error
+
+    return IpUtils
 
 
 async def _getaddrinfo(host: str, port: int) -> Sequence[str]: