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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xtr-http-client
-Version: 5.0.1
+Version: 5.2.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
@@ -393,22 +393,24 @@ removing it undoes.
 - **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
-  cannot make for you (see [xtr-recipes](../xtr-recipes)).
-- **Activate** — `HttpClientBundle: {"all": True}` in `BUNDLES` in `<app>/bundles.py`,
+- **Recipe** — `uv run xtr-recipes recipes:sync` does the *Activate* and *Configure* steps below:
+  it lists `HttpClientBundle` and writes `<app>/config/packages/http_client.py` with the bundle's
+  own defaults. There is no environment or ignore line to write; it prints the step to name the
+  services the application calls in that file, which a recipe cannot make for you (see
+  [xtr-recipes](../xtr-recipes)).
+- **Activate** — `HttpClientBundle: {"all": True}` in `BUNDLES` in `<app>/config/bundles.py`,
   imported from `xtr_http_client.bundle`.
 - **Brings along** — the rate limiter bundle when xtr-rate-limiter is installed.
-- **Configure** — optional: with no configuration there is one client, an
-  `HttpClientInterface` sending requests as they are given. Default options, a client per
-  service, retries, a pace and a mock for tests go in `<app>/config/http_client.py`, a
+- **Configure** — optional: the recipe writes `<app>/config/packages/http_client.py` holding the
+  defaults, one client — an `HttpClientInterface` sending requests as they are given. Default
+  options, a client per service, retries, a pace and a mock for tests go in that same
   `@configure` function returning `HttpClientConfig` — see [Kernel / bundle](#kernel--bundle).
 - **Environment** — nothing. A credential given as `env(...)` is read when the client needing
   it is built.
 - **Ignore** — nothing.
-- **Remove** — drop the `BUNDLES` entry, delete `<app>/config/http_client.py`, then
-  `uv remove xtr-http-client`.
+- **Remove** — drop the `BUNDLES` entry; `uv run xtr-recipes recipes:remove xtr-http-client`
+  deletes `<app>/config/packages/http_client.py`, unless you edited it, in which case it is
+  moved aside to `http_client.py.removed`. Then `uv remove xtr-http-client`.
 - **Check** — `debug:bundles` shows `http_client` as `listed` and `active`.
 
 ## Kernel / bundle
@@ -418,14 +420,14 @@ not a dependency, and nothing outside `xtr_http_client.bundle` needs it — list
 configure the clients:
 
 ```python
-# app/bundles.py
+# app/config/bundles.py
 from xtr_http_client.bundle import HttpClientBundle
 
 BUNDLES = {HttpClientBundle: {"all": True}}
 ```
 
 ```python
-# app/config/http_client.py
+# app/config/packages/http_client.py
 from xtr_dependency_injection import configure, env
 
 from xtr_http_client.bundle import (

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

@@ -362,22 +362,24 @@ removing it undoes.
 - **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
-  cannot make for you (see [xtr-recipes](../xtr-recipes)).
-- **Activate** — `HttpClientBundle: {"all": True}` in `BUNDLES` in `<app>/bundles.py`,
+- **Recipe** — `uv run xtr-recipes recipes:sync` does the *Activate* and *Configure* steps below:
+  it lists `HttpClientBundle` and writes `<app>/config/packages/http_client.py` with the bundle's
+  own defaults. There is no environment or ignore line to write; it prints the step to name the
+  services the application calls in that file, which a recipe cannot make for you (see
+  [xtr-recipes](../xtr-recipes)).
+- **Activate** — `HttpClientBundle: {"all": True}` in `BUNDLES` in `<app>/config/bundles.py`,
   imported from `xtr_http_client.bundle`.
 - **Brings along** — the rate limiter bundle when xtr-rate-limiter is installed.
-- **Configure** — optional: with no configuration there is one client, an
-  `HttpClientInterface` sending requests as they are given. Default options, a client per
-  service, retries, a pace and a mock for tests go in `<app>/config/http_client.py`, a
+- **Configure** — optional: the recipe writes `<app>/config/packages/http_client.py` holding the
+  defaults, one client — an `HttpClientInterface` sending requests as they are given. Default
+  options, a client per service, retries, a pace and a mock for tests go in that same
   `@configure` function returning `HttpClientConfig` — see [Kernel / bundle](#kernel--bundle).
 - **Environment** — nothing. A credential given as `env(...)` is read when the client needing
   it is built.
 - **Ignore** — nothing.
-- **Remove** — drop the `BUNDLES` entry, delete `<app>/config/http_client.py`, then
-  `uv remove xtr-http-client`.
+- **Remove** — drop the `BUNDLES` entry; `uv run xtr-recipes recipes:remove xtr-http-client`
+  deletes `<app>/config/packages/http_client.py`, unless you edited it, in which case it is
+  moved aside to `http_client.py.removed`. Then `uv remove xtr-http-client`.
 - **Check** — `debug:bundles` shows `http_client` as `listed` and `active`.
 
 ## Kernel / bundle
@@ -387,14 +389,14 @@ not a dependency, and nothing outside `xtr_http_client.bundle` needs it — list
 configure the clients:
 
 ```python
-# app/bundles.py
+# app/config/bundles.py
 from xtr_http_client.bundle import HttpClientBundle
 
 BUNDLES = {HttpClientBundle: {"all": True}}
 ```
 
 ```python
-# app/config/http_client.py
+# app/config/packages/http_client.py
 from xtr_dependency_injection import configure, env
 
 from xtr_http_client.bundle import (

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

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-http-client"
-version = "5.0.1"
+version = "5.2.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"

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

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-http-client"
-version = "5.0.1"
+version = "5.2.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 = [

{xtr_http_client-5.0.1 → xtr_http_client-5.2.0}/src/xtr_http_client/.agents/skills/xtr-http-client/SKILL.md

@@ -208,17 +208,18 @@ async def test_it_reads_the_created_order() -> None:
 ## Use in an application
 
 `uv run xtr-recipes recipes:sync` applies the recipe shipped with this package: 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, which a recipe cannot make for you.
+`HttpClientBundle` and writes `<app>/config/packages/http_client.py` with the bundle's own
+defaults. There is no 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 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`
+2. **Activate** — `HttpClientBundle: {"all": True}` in `BUNDLES` in `<app>/config/bundles.py`
    (`from xtr_http_client.bundle import HttpClientBundle`).
 3. **Brings along** — the rate limiter bundle when xtr-rate-limiter is installed.
-4. **Configure** — optional: with no configuration there is one client sending requests as they
-   are given. Otherwise `<app>/config/http_client.py`:
+4. **Configure** — the recipe writes `<app>/config/packages/http_client.py` holding the defaults,
+   one client sending requests as they are given, and that is where the rest goes:
 
    ```python
    from xtr_dependency_injection import configure, env
@@ -269,8 +270,9 @@ step to name the services the application calls, which a recipe cannot make for
    ```
 
 7. **Check** — `debug:bundles` shows `http_client` as `listed` and `active`.
-8. **Remove** — drop the `BUNDLES` entry, delete `<app>/config/http_client.py`, then
-   `uv remove xtr-http-client`.
+8. **Remove** — drop the `BUNDLES` entry; `uv run xtr-recipes recipes:remove xtr-http-client`
+   deletes `<app>/config/packages/http_client.py`, unless you edited it, in which case it is
+   moved aside to `http_client.py.removed`. Then `uv remove xtr-http-client`.
 
 ## Errors
 

xtr_http_client-5.2.0/src/xtr_http_client/recipe/files/config/http_client.py.tmpl

@@ -0,0 +1,34 @@
+"""The HTTP clients: the default one, and one per service the application calls.
+
+```python
+HttpClientConfig(
+    default_options=ClientOptionsConfig(
+        timeout=10, retry_failed=RetryFailedConfig(enabled=True)
+    ),
+    scoped_clients={
+        "github": ScopedClientConfig(
+            base_uri="https://api.github.com/", auth_bearer=env("GITHUB_TOKEN")
+        ),
+    },
+)
+```
+"""
+
+from __future__ import annotations
+
+from xtr_dependency_injection import configure
+from xtr_http_client.bundle import HttpClientConfig
+
+__all__ = ["http_client"]
+
+
+@configure
+def http_client() -> HttpClientConfig:
+    """One client, sending requests as they are given."""
+    # default_options is what every request starts from: a timeout, headers, retries.
+    #
+    # A client in scoped_clients is qualified by its name and carries its own base URI,
+    # headers and credentials, over what default_options sets.
+    #
+    # max_host_connections caps the connections one pool holds at once, six unless set.
+    return HttpClientConfig()

{xtr_http_client-5.0.1 → xtr_http_client-5.2.0}/src/xtr_http_client/recipe/manifest.toml

@@ -5,9 +5,11 @@
 # "<module>:<class>" = the environments it is listed with, exactly as in BUNDLES.
 "xtr_http_client.bundle:HttpClientBundle" = { all = true }
 
-# No [files]: configuring is optional. With none there is one client sending
-# requests as they are given; an application naming the services it calls
-# writes config/http_client.py itself, which is what [notes] asks for.
+[files]
+# Destination under the application package = template under this recipe.
+# The bundle's own defaults written out — one client sending requests as they
+# are given — as the place the services it calls are named, as [notes] asks.
+"config/packages/http_client.py" = "files/config/http_client.py.tmpl"
 
 # No [env]: nothing is required. A credential an application gives as env(...)
 # is read when the client needing it is built.
@@ -18,6 +20,6 @@ lines = []
 
 [notes]
 steps = [
-  "Name the services the application calls in config/http_client.py — a scoped client per base URI, with its headers and credentials — when one client with no defaults is not enough.",
+  "Name the services the application calls in config/packages/http_client.py — a scoped client per base URI, with its headers and credentials — when one client with no defaults is not enough.",
 ]
 check = ["<script> debug:bundles — http_client is listed and active"]