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

xtr_http_client-4.0.4/README.md → xtr_http_client-5.0.0/PKG-INFO

@@ -1,3 +1,34 @@
+Metadata-Version: 2.4
+Name: xtr-http-client
+Version: 5.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
+Author-email: Xterr <me@xterr.dev>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+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: httpx[http2]>=0.27 ; extra == 'http2'
+Requires-Python: >=3.11
+Provides-Extra: http2
+Description-Content-Type: text/markdown
+
 <div align="center">
 
 # xtr-http-client
@@ -28,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
 
@@ -105,6 +142,21 @@ 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 `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:
+
+```python
+with open("photo.png", "rb") as photo:
+    response = await client.request("POST", "upload", body={"caption": "hi", "photo": photo})
+```
+
+A `Content-Type: multipart/form-data; boundary=...` set by the caller keeps its boundary. The
+file is read synchronously while the body is sent, which suits uploads of a modest size. A part
+holds one scalar — a string, bytes, a number, a boolean (`true`/`false`) or `None` — or a list of
+them, one part each; a nested value is refused with `InvalidArgumentError` naming the field, so
+encode it (as JSON, say) first.
+
 `with_options()` turns options into the defaults of another client of the same type, leaving
 the one everyone else holds as it was:
 
@@ -214,9 +266,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 +324,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 +390,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 +413,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/PKG-INFO → xtr_http_client-5.0.0/README.md

@@ -1,39 +1,3 @@
-Metadata-Version: 2.4
-Name: xtr-http-client
-Version: 4.0.4
-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
-Author-email: Xterr <me@xterr.dev>
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 3 - Alpha
-Classifier: Framework :: AsyncIO
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Internet :: WWW/HTTP
-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>=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">
 
 # xtr-http-client
@@ -64,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
 
@@ -141,6 +111,21 @@ 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 `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:
+
+```python
+with open("photo.png", "rb") as photo:
+    response = await client.request("POST", "upload", body={"caption": "hi", "photo": photo})
+```
+
+A `Content-Type: multipart/form-data; boundary=...` set by the caller keeps its boundary. The
+file is read synchronously while the body is sent, which suits uploads of a modest size. A part
+holds one scalar — a string, bytes, a number, a boolean (`true`/`false`) or `None` — or a list of
+them, one part each; a nested value is refused with `InvalidArgumentError` naming the field, so
+encode it (as JSON, say) first.
+
 `with_options()` turns options into the defaults of another client of the same type, leaving
 the one everyone else holds as it was:
 
@@ -250,9 +235,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 +293,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 +359,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 +382,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-5.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-http-client"
-version = "4.0.4"
+version = "5.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,12 +29,11 @@ dependencies = [
     "typing-extensions>=4.4",
     "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",
-    "xtr-service-contracts>=4.0,<5",
+    "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",
 ]
 
 [[project.authors]]
@@ -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"
@@ -61,9 +58,10 @@ dev = [
     "anyio>=4.0",
     "h2>=4.0",
     "ty>=0.0.83",
-    "xtr-clock>=4.0,<5",
-    "xtr-dependency-injection>=4.0,<5",
-    "xtr-rate-limiter>=4.0,<5",
+    "xtr-clock>=5.0,<6",
+    "xtr-dependency-injection>=5.0,<6",
+    "xtr-http-foundation>=5.0,<6",
+    "xtr-rate-limiter>=5.0,<6",
 ]
 
 [build-system]

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

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-http-client"
-version = "4.0.4"
+version = "5.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,27 +27,18 @@ dependencies = [
     "typing-extensions>=4.4",
     "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",
-    "xtr-service-contracts>=4.0,<5",
+    "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",
 ]
 
 [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.
@@ -67,9 +58,11 @@ dev = [
     "anyio>=4.0",
     "h2>=4.0",
     "ty>=0.0.83",
-    "xtr-clock>=4.0,<5",
-    "xtr-dependency-injection>=4.0,<5",
-    "xtr-rate-limiter>=4.0,<5",
+    "xtr-clock>=5.0,<6",
+    "xtr-dependency-injection>=5.0,<6",
+    # The networks NoPrivateNetworkHttpClient refuses; optional for an application.
+    "xtr-http-foundation>=5.0,<6",
+    "xtr-rate-limiter>=5.0,<6",
 ]
 
 [build-system]

{xtr_http_client-4.0.4 → xtr_http_client-5.0.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
 
@@ -63,6 +66,25 @@ resolved against `base_uri`, `query` is merged into the URI, and `auth_bearer` a
 where the request has no `Authorization`. A `body` or `json` option plus a request that already
 carries a body is refused.
 
+## Upload a file
+
+```python
+with open("photo.png", "rb") as photo:
+    response = await client.request("POST", "upload", body={"caption": "hi", "photo": photo})
+```
+
+- A `body` mapping holding a binary file (`open(..., "rb")`, `io.BytesIO`) is sent as
+  `multipart/form-data`; without one it stays url-encoded.
+- Each file part is named after the file's `name` (`unknown` without one) and typed by
+  `mimetypes.guess_type`, else `application/octet-stream`.
+- Beside a file, every value is a scalar or a list of scalars; a nested one raises
+  `InvalidArgumentError` naming the field — `json.dumps` it first.
+- A caller-set `Content-Type: multipart/form-data; boundary=...` keeps its boundary; do not set
+  a multipart content type without one.
+- The file is read synchronously while the body is sent: keep the file open until `request()`
+  returns, and keep uploads modest in size.
+- `MockHttpClient` hands the mapping, file included, to the script as given.
+
 ## Give each service its own defaults
 
 ```python
@@ -109,7 +131,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 +147,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 +211,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-5.0.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-5.0.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-5.0.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-5.0.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-5.0.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-5.0.0}/src/xtr_http_client/httpx_http_client.py

@@ -156,6 +156,7 @@ class HttpxHttpClient(HttpClientMixin, HttpClientInterface):
             url,
             content=payload.content,
             data=payload.form,
+            files=payload.files,
             json=payload.document,
             headers=headers,
             extensions=extensions,

{xtr_http_client-4.0.4 → xtr_http_client-5.0.0}/src/xtr_http_client/internal/httpx_request.py

@@ -8,8 +8,13 @@ per part, made here, away from the exchange and the redirect chain that follow.
 
 from __future__ import annotations
 
+import io
+import mimetypes
+import os
+import re
 from collections.abc import AsyncIterable, Mapping, Sequence
-from typing import TYPE_CHECKING, Final, NamedTuple, cast
+from pathlib import PurePath
+from typing import TYPE_CHECKING, BinaryIO, Final, NamedTuple, cast
 
 import httpx
 
@@ -47,12 +52,30 @@ _FORM: Final = "application/x-www-form-urlencoded"
 _NO_BODY: Final = (None, b"", "")
 
 
+# Read the way the backend reads it: a boundary it cannot find here is one it would not use
+# either, and it would then write a body the caller's header does not describe.
+# What one multipart part holds; a boolean is an int, written "true" or "false".
+_PART_SCALARS: Final = (str, bytes, int, float)
+_NAMED_BOUNDARY: Final = re.compile(r'^multipart/form-data;.*\bboundary=(?:"[^"]+"|[^;\s"]+)')
+
+# What a file with no name of its own is sent as: a server reads a part without a file name
+# as a plain value, so a file has to be called something.
+_UNNAMED: Final = "unknown"
+_OCTET_STREAM: Final = "application/octet-stream"
+
+
 class Payload(NamedTuple):
-    """The one body of a request, in whichever of three shapes it is to be sent."""
+    """The one body of a request, in whichever of four shapes it is to be sent.
+
+    ``files`` sits beside ``form`` rather than replacing it: a form holding a file is sent
+    as multipart, its plain values in ``form`` and each file, with the name and content type
+    its part is labelled with, in ``files``.
+    """
 
     content: bytes | str | AsyncIterator[bytes] | None
     form: Mapping[str, object] | None
     document: object
+    files: Mapping[str, tuple[str, BinaryIO, str]] | None = None
 
 
 def target_url(request: RequestInterface, options: Mapping[str, object]) -> httpx.URL:
@@ -161,9 +184,9 @@ async def assemble_payload(
 def _asked_for(options: Mapping[str, object], headers: list[tuple[str, str]]) -> Payload:
     """What the options alone say to send, for a request that carried no body.
 
-    A mapping is a form, which the backend writes out; bytes, text and an
-    iterable are a body nobody labelled, so they are said to be a form here;
-    and a JSON document labels itself.
+    A mapping is a form, which the backend writes out — as multipart when it
+    holds a file; bytes, text and an iterable are a body nobody labelled, so
+    they are said to be a form here; and a JSON document labels itself.
     """
     document = options.get("json")
     if document is not None:
@@ -171,7 +194,7 @@ def _asked_for(options: Mapping[str, object], headers: list[tuple[str, str]]) ->
 
     body = options.get("body")
     if isinstance(body, Mapping):
-        return Payload(None, cast("Mapping[str, object]", body), None)
+        return _form(cast("Mapping[str, object]", body), headers)
     if isinstance(body, (bytes, str)) and body:
         _imply_form(headers)
 
@@ -184,6 +207,70 @@ def _asked_for(options: Mapping[str, object], headers: list[tuple[str, str]]) ->
     return Payload(None, None, None)
 
 
+def _form(body: Mapping[str, object], headers: list[tuple[str, str]]) -> Payload:
+    """A form, url-encoded unless one of its values is a binary file.
+
+    The content type is left for the backend to write with the boundary it
+    picks, unless the caller already named one: then that boundary is the one
+    the body is written with. A content type naming none would describe a
+    body it cannot be read by, so it is dropped.
+    """
+    files = {
+        # The standard library's binary file classes are what `BinaryIO` describes, though
+        # the two are not declared related.
+        name: _file_part(cast("BinaryIO", cast("object", value)))
+        for name, value in body.items()
+        if isinstance(value, (io.RawIOBase, io.BufferedIOBase))
+    }
+    if not files:
+        return Payload(None, body, None)
+
+    content_type = next(
+        (value for name, value in headers if name.lower() == "content-type"),
+        "",
+    )
+    if not _NAMED_BOUNDARY.match(content_type):
+        headers[:] = [entry for entry in headers if entry[0].lower() != "content-type"]
+
+    plain = {name: value for name, value in body.items() if name not in files}
+    for name, value in plain.items():
+        _check_part(name, value)
+
+    return Payload(None, plain, None, files)
+
+
+def _check_part(name: str, value: object) -> None:
+    """Refuse a plain value of a multipart form that no part can hold.
+
+    A part holds one scalar, and a list or tuple of them is one part per item;
+    anything nested would otherwise fail deep inside the backend, naming no field.
+
+    Raises:
+        InvalidArgumentError: Naming the field and the type it was given.
+    """
+    given = debug_type(value)
+    items: Sequence[object] = (
+        cast("Sequence[object]", value) if isinstance(value, (list, tuple)) else (value,)
+    )
+    if all(isinstance(item, _PART_SCALARS) or item is None for item in items):
+        return
+    raise InvalidArgumentError(
+        f'Option "body" field "{name}" must be a string, a number, a boolean, None or a list '
+        f'of them when the body is multipart, "{given}" given.'
+    )
+
+
+def _file_part(file: BinaryIO) -> tuple[str, BinaryIO, str]:
+    """``file``, with the file name and the content type its part is labelled with."""
+    name = cast("object", getattr(file, "name", None))
+    if isinstance(name, bytes):
+        name = os.fsdecode(name)
+    filename = PurePath(name).name if isinstance(name, str) and name else _UNNAMED
+    content_type = mimetypes.guess_type(filename)[0] or _OCTET_STREAM
+
+    return filename, file, content_type
+
+
 async def checked_body(source: AsyncIterable[object]) -> AsyncIterator[bytes]:
     """``source``, with a piece that is not bytes refused before it reaches the wire.
 

{xtr_http_client-4.0.4 → xtr_http_client-5.0.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]: