021-python-clients 0.2.0__tar.gz → 0.3.0__tar.gz

{021_python_clients-0.2.0 → 021_python_clients-0.3.0}/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes are recorded here by release-please from Conventional Commits.
 
+## [0.3.0](https://github.com/from021-io/python-clients/compare/v0.2.0...v0.3.0) (2026-10-21)
+
+
+### ⚠ BREAKING CHANGES
+
+* **http:** HTTP durations include body consumption and cleanup, counts emit at completion and all HTTP series gain http.response.body.complete. Attempt failure logs are enabled by default. See CONTRACT.md for dashboard and consumer migration notes.
+
+### Features
+
+* **http:** observe complete response bodies and streams ([333cece](https://github.com/from021-io/python-clients/commit/333cece69c41a9ef16828f83e303be4183a5a187))
+
+
+### Refactors
+
+* **http:** group clients and transports by capability ([1a7b41a](https://github.com/from021-io/python-clients/commit/1a7b41a5dba214fb109acccc9e3e08a9d123e3ee))
+
 ## [0.2.0](https://github.com/from021-io/python-clients/compare/v0.1.0...v0.2.0) (2026-10-21)
 
 
@@ -22,10 +38,14 @@ All notable changes are recorded here by release-please from Conventional Commit
 
 ### Added
 
+- Add `HttpClient.stream` and a native httpx `ObservedTransport` for incremental bodies with explicit lifetime and no streaming retries.
+
 - Add an optional Vercel Blob client with observed CRUD, explicit public/private access, bounded operations and SDK-native metadata/errors.
 
 ### Changed
 
+- **Breaking — HTTP telemetry:** HTTP/httpx2 spans and request durations now include body consumption and resource close. Counters are emitted at completion, gain `http.response.body.complete`, and failures produce sanitized attempt logs. QStash/Resend retain one logical failure log. Cancellation closes resources before propagating; closed HTTP clients cannot reopen.
+
 - Group Redis, S3 and KMS under cache, storage and crypto, retaining the 0.1.0 imports as compatibility aliases.
 
 ## 0.1.0 (2026-10-21)

{021_python_clients-0.2.0 → 021_python_clients-0.3.0}/CONTRACT.md

@@ -19,7 +19,11 @@ Redis lives in `clients_021.cache.redis`, S3 in `clients_021.storage.s3` and KMS
 `clients_021.crypto.kms`. The 0.1.0 root modules (`redis`, `s3`, `kms`) continue to re-export
 the same clients and result types (`ObjectInfo`, `DataKey`). Existing call signatures,
 metric/span names and error semantics are unchanged. Capability package imports do not
-load optional SDKs. HTTP transports remain in `clients_021.http` and `clients_021.httpx2`.
+load optional SDKs. HTTP implementations live in `clients_021.http.httpx` and
+`clients_021.http.httpx2`. `clients_021.http` retains `HttpClient`, `HttpResponse`,
+`HttpMethod`, `IDEMPOTENT_METHODS` and `RETRY_STATUS`; the root `clients_021` exports remain
+unchanged. `clients_021.httpx2.ObservedTransport` re-exports the same class as the new path.
+Importing `clients_021.http` does not require the `httpx2` extra.
 
 ## Metrics
 
@@ -36,7 +40,7 @@ version, environment). Durations use 021-python-observability's buckets.
 | `storage.client.operation.duration` | Histogram / `s` | same | S3, Vercel Blob |
 | `crypto.client.operation.count` | Counter / `{operation}` | dependency, operation, status, error.type | KMS |
 | `crypto.client.operation.duration` | Histogram / `s` | same | KMS |
-| `http.client.request.count` | Counter / `{request}` | dependency, http.request.method, http.response.status_code, error.type | HTTP, httpx2, QStash transport, Resend (its HTTP request) |
+| `http.client.request.count` | Counter / `{request}` | dependency, http.request.method, http.response.status_code, error.type, http.response.body.complete | HTTP, httpx2, QStash transport, Resend (its HTTP request) |
 | `http.client.request.duration` | Histogram / `s` | same | HTTP, httpx2, QStash transport, Resend (its HTTP request) |
 
 - `status`: `ok` or `error`. `error.type` only on errors.
@@ -52,7 +56,7 @@ version, environment). Durations use 021-python-observability's buckets.
   `NotFoundException`, for KMS).
 - Resend records two levels: the `send` operation (`messaging.client.operation.*`) and,
   inside it, its HTTP request (`http.client.request.*`), both under the same `dependency`.
-- HTTP transport metrics inherit 021-python-observability's labels (`timeout`, `cancelled`,
+- HTTP transport metrics use the bounded labels (`timeout`, `cancelled`,
   `connection_error` or `internal_error`). These describe the transport exception, while
   `DependencyUnavailable.reason` describes the failure returned to the caller.
 - httpx2 uses `timeout`, `connection_error`, `cancelled`, or the exception class name.
@@ -70,21 +74,69 @@ metric labels plus `db.system.name=redis`, `messaging.system=aws_sqs`,
 Resend's `HTTP <dependency>` span is a child of its `<dependency> send` span. Status ERROR on failure (and on HTTP
 status ≥ 400).
 Cancellation propagates unchanged and records ERROR with `error.type=cancelled`.
-HTTP transports measure through response headers; they do not measure body consumption.
+HTTP transports measure from sending the request through response-body EOF and resource
+close, or explicit early close. Uploads and incremental downloads are included, as are
+consumer pauses between chunks and cleanup latency. Each attempt ends its span and emits
+one count and one duration exactly once. An HTTP 200 followed by a body timeout is ERROR
+with status code 200 and `error.type=timeout`; the status code describes the headers only.
+
+`http.response.body.complete` is a boolean on HTTP spans and metric points: true after
+response-body EOF, false when no response arrived or it was closed before EOF. It does not
+imply success: an HTTP rejection or close failure can still set ERROR. An intentional
+partial close without an error does not set ERROR. Cancellation sets `error.type=cancelled`,
+including cancellation while reading, closing or waiting between chunks in a stream context.
+
+The HTTP span is current only while sending, reading, closing and emitting its log. It is
+not left attached while a caller processes a chunk; interleaved and cross-task consumers
+keep their own context. All HTTP attempt spans retain the parent active at request start.
 
 QStash adds one logical `publish` operation around the HTTP transport request. The
 messaging duration includes reading and validating the acknowledgement; the nested HTTP
-span measures through response headers. Both use the configured static dependency name.
+span includes reading and closing the response body. Both use the configured static dependency name.
 Local input validation occurs before either operation is recorded.
 
+## Logging and coverage limits
+
+Redis, SQS, QStash, S3, Vercel Blob, Resend, SES and KMS emit a structured
+`dependency.call_failed` warning when an observed remote operation raises an exception.
+Fields are `dependency`, `operation` and `error_type`; provider messages and exception
+chains are not logged. Successful calls and cancellation do not emit this warning;
+cancellation still records an error span and metrics.
+
+HTTP and httpx2 emit one `dependency.call_failed` warning per failed attempt (transport,
+body or close exception, cancellation, or HTTP status >= 400). Fields are only `dependency`,
+`operation` (normalized method) and `error_type`. HTTP rejection logs use `status_<code>`;
+the metric still uses only its status-code label for that case. The logger runs within the
+HTTP span so configured log processors can attach its trace/span IDs. Successful completed
+attempts emit no log. Intentional partial close emits `dependency.stream_closed` at INFO
+with dependency and operation; it is not an outage.
+
+`log_failures=False` suppresses these HTTP attempt logs without disabling metrics or spans.
+QStash and Resend set this option because their logical operation already emits a failure
+warning; they do not log the same failure at both levels. SDK retry loops can produce one
+warning per failed attempt. HTTP counters measure attempts, not logical API/SDK calls.
+
+The transport observes network bytes and connection cleanup. Parsing JSON, SSE events,
+model output, content decoding above the raw stream, and application errors while processing
+chunks belong to the caller/SDK operation. A 200 SSE response containing an application
+error event is not detected by an HTTP transport.
+S3 presigning and local AES work in KMS are outside remote-operation telemetry.
+
+Instrumentation takes effect only when applications use these wrappers. The application
+must also configure logging, exporters and shutdown/flush through 021-python-observability.
+Defining a client in this package does not migrate existing SDK usage or guarantee that
+telemetry reaches an external backend.
+
 ## Trace propagation
 
-- HTTP (`HttpClient`): `traceparent`, `tracestate` and `x-request-id` are sent (by
-  021-python-observability's transport).
-- httpx2 (`ObservedTransport`): nothing is sent unless `propagate=True`.
+- HTTP (`HttpClient`, `http.httpx.ObservedTransport`): the current `traceparent` and
+  `tracestate` replace the caller's trace pair, and a bound `x-request-id` is sent.
+  A native httpx transport can disable injection with `propagate=False`.
+- httpx2 (`ObservedTransport`): no context is injected unless `propagate=True`.
+  With injection disabled, caller-supplied headers are left as supplied.
   When enabled, both caller-supplied trace headers are replaced with the current context.
 - Resend: nothing is sent. The `traceparent`, `tracestate` and `x-request-id` headers that
-  021-python-observability's transport adds are removed before the request leaves.
+  the HTTP transport adds are removed before the request leaves.
 - SES, KMS and Vercel Blob: nothing is sent by the default transports.
 - SQS: `traceparent` and `tracestate` are message attributes; `ReceivedMessage.trace_context()`
   returns the producer's context. Caller-supplied values for both trace attributes are
@@ -98,10 +150,12 @@ Local input validation occurs before either operation is recorded.
 
 `DependencyUnavailable(dependency, operation, reason)` with `reason` one of `timeout`,
 `connection_error`, `throttled`, `status_<5xx>`. Raised only when retrying later may work.
-HTTP: only after the last attempt; HTTP statuses are returned, never raised.
+`HttpClient.request`: only after the last attempt; HTTP statuses are returned, never raised.
+`HttpClient.stream`: exactly one attempt; transport/body failures use the same conversion,
+with no replay after headers or a partial body. Native httpx/httpx2 `ObservedTransport`
+instances preserve SDK exceptions and never retry.
 HTTP local protocol/unsupported protocol errors and Redis authentication
-or authorization errors retain their native type and are not treated as outages. httpx2
-transports always preserve the native exception for the owning SDK.
+or authorization errors retain their native type and are not treated as outages.
 
 QStash maps HTTP 429 to `throttled`, 5xx to `status_<code>`, and transport outages to
 `timeout` or `connection_error`, with operation `publish`. Other non-2xx responses raise
@@ -169,9 +223,22 @@ provider options. The publication timeout is mandatory and finite. Consumers rem
 responsible for idempotency and signature verification. A closed QStash client cannot
 publish again.
 
-`HttpClient.request` accepts at most one of `json`, `form` or raw byte `content`. Passing
+`HttpClient.request` and `HttpClient.stream` accept at most one of `json`, `form` or raw byte `content`. Passing
 more than one non-None body format raises `ValueError` before sending a request.
 
+`HttpClient.stream` is an async context manager yielding a native httpx response; it does
+not buffer the response and also accepts an async iterable of upload bytes. Use `async with`
+and `aiter_bytes`, `aiter_lines` or `aiter_raw`. SDK callers using manual `send(stream=True)`
+must eventually call `response.aclose()`; an abandoned response cannot finalize its
+telemetry or free its connection. Client shutdown does not replace closing active responses.
+Close responses and finish consumers before closing the client/Observability.
+
+Body resources close once on EOF, read failure or explicit close. Cleanup is shielded from
+cancellation and awaited; cancellation is then re-raised. A secondary cleanup failure does
+not replace a read failure. These async clients run on asyncio. Custom transports must implement a terminating `aclose()`.
+Timeouts remain per network I/O, not a total stream deadline. `HttpClient` closes an injected
+transport once even when multiple dependency pools borrow it; closed clients cannot reopen.
+
 Vercel Blob uses the optional `vercel-blob>=0.5,<0.6` SDK and explicit read-write credentials,
 store ID and access mode. It owns a shared transport; each operation borrows it in a separate
 SDK session. No environment credentials or global SDK client perform requests. The total
@@ -181,6 +248,17 @@ retries operations; an injected transport must respect this policy. Overwrite an
 suffixes default to false. Callers decide whether a repeated write is safe. A closed client
 cannot reopen its pool. No additional HTTP metrics are emitted by this client.
 
+## Migration from 0.2.x
+
+This is a breaking telemetry change, released with the next pre-1.0 minor version. HTTP
+metric names and span names stay the same, but their durations now include bodies, consumer
+backpressure and close; counts are emitted at completion instead of at headers. Existing
+series gain `http.response.body.complete`. Revisit latency thresholds, filter/aggregate the
+new label and expect long-lived streams to report only when they complete or close. Native
+transport logs are now enabled by default; use the explicit opt-out when an enclosing
+logical operation already owns the warning. Do not add a second observed transport around
+these clients, or each request would be counted twice.
+
 ## Never recorded
 
 Keys, URLs, query strings, bodies, message ids, receipts, object names, bucket or queue

{021_python_clients-0.2.0 → 021_python_clients-0.3.0}/CONTRIBUTING.md

@@ -8,15 +8,14 @@ not need to be reimplemented here.
 ## Layout and public API
 
 Group domain clients by capability, with a module per provider even when the package
-currently has one provider. HTTP transports are cross-cutting infrastructure and stay at
-the root. Tests stay in `tests/test_<provider>.py`.
+currently has one provider. HTTP implementations live under `http/`, with explicit
+imports for optional transports. Tests stay in `tests/test_<provider>.py`.
 
 ```text
 clients_021/
   email/          # _message.py (shared protocol/types), resend.py, ses.py
   queue/          # sqs.py, qstash.py
-  http.py
-  httpx2.py
+  http/           # httpx.py (HttpClient/ObservedTransport), httpx2.py (ObservedTransport)
   cache/          # redis.py
   storage/        # s3.py, vercel_blob.py
   crypto/         # kms.py
@@ -24,7 +23,9 @@ clients_021/
 
 The original `clients_021.redis`, `clients_021.s3` and `clients_021.kms` imports remain
 compatibility re-exports of the same classes and result types. New code uses the capability
-paths. Do not remove compatibility modules without a breaking release.
+paths. `clients_021.http` re-exports its existing types from `http.httpx`, and the original
+`clients_021.httpx2` remains an alias for `http.httpx2`. Keep `clients_021.HttpClient`
+available too. Do not remove compatibility modules without a breaking release.
 
 Public result and exception types live beside their provider unless they are truly shared.
 A common protocol requires interchangeable operations and semantics: `EmailSender.send`
@@ -64,7 +65,11 @@ Each implementation must make these decisions explicit in README.md and CONTRACT
 Use `_observe.observed` for a logical cache, messaging, storage or crypto operation. HTTP-backed
 clients may also emit the transport's HTTP span/metrics: one logical operation and one
 network request are different measurements. Do not sum those counters as distinct
-business operations. Disable exception recording when provider errors can contain data.
+business operations. Disable nested HTTP attempt logs with `log_failures=False` when the
+logical operation owns the failure log. HTTP transport duration includes raw-body consumption
+and resource close; keep measurement once-only, incremental, and detached from consumer
+context between chunks. Test read/close errors, cancellation (including repeated cancellation
+while closing), early close, and cross-task consumption. Disable exception recording when provider errors can contain data.
 The safe wrapper message does not make a native chained exception safe to log.
 
 Expose small, stable results when the caller needs them. Validate acknowledgements before

{021_python_clients-0.2.0 → 021_python_clients-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: 021-python-clients
-Version: 0.2.0
+Version: 0.3.0
 Summary: Observed clients for Redis, SQS, QStash, S3, Vercel Blob, HTTP, email and KMS, built on 021-python-observability
 Project-URL: Repository, https://github.com/from021-io/python-clients
 Project-URL: Changelog, https://github.com/from021-io/python-clients/blob/main/CHANGELOG.md
@@ -48,8 +48,8 @@ uv add "021-python-clients[redis,aws,httpx2,vercel-blob]"   # pick the extras yo
 
 | Module | Extra | What it gives |
 | --- | --- | --- |
-| `clients_021.http` | none | `HttpClient`: one httpx client per dependency, timeouts, retries on idempotent methods |
-| `clients_021.httpx2` | `httpx2` | `ObservedTransport` for SDKs built on httpx2 (Anthropic, OpenAI) |
+| `clients_021.http.httpx` | none | `HttpClient`: buffered requests, streaming and full-body telemetry; native `ObservedTransport` |
+| `clients_021.http.httpx2` | `httpx2` | `ObservedTransport` for SDKs built on httpx2 (Anthropic, OpenAI) |
 | `clients_021.cache.redis` | `redis` | `RedisClient`: JSON with TTL, one-time reads, windowed counters, ping |
 | `clients_021.queue.qstash` | none | `QStashClient`: JSON publishing, deduplication, delivery options and forwarded trace context |
 | `clients_021.queue.sqs` | `aws` | `SqsClient`: send, receive, delete, visibility, trace carried in the message |
@@ -66,10 +66,12 @@ Every client takes the service's `Observability` (from `setup_observability`) an
 
 Providers with the same purpose live under one capability package: `email/` contains
 Resend and SES; `queue/` contains SQS and QStash; `storage/` contains S3 and Vercel Blob; `cache/`
-contains Redis; `crypto/` contains KMS. HTTP transports remain at the root. Import providers
-explicitly:
+contains Redis; `crypto/` contains KMS. `http/` contains the httpx client and httpx2
+transport. Import providers explicitly:
 
 ```python
+from clients_021.http import HttpClient
+from clients_021.http.httpx2 import ObservedTransport  # requires the httpx2 extra
 from clients_021.queue.sqs import SqsClient
 from clients_021.queue.qstash import QStashClient
 from clients_021.storage.s3 import S3Client
@@ -85,7 +87,9 @@ does not load the optional AWS SDK.
 
 The 0.1.0 imports `clients_021.redis`, `clients_021.s3` and `clients_021.kms` remain
 compatible aliases for the same classes and result types. Importing a capability package
-does not load its optional SDKs.
+does not load its optional SDKs. `clients_021.HttpClient` and `clients_021.http` keep their
+published exports; `clients_021.httpx2.ObservedTransport` remains an alias for
+`clients_021.http.httpx2.ObservedTransport`.
 
 ## What every call gets
 
@@ -97,7 +101,8 @@ does not load its optional SDKs.
   `crypto.client.operation.*` (KMS), `http.client.request.*` (HTTP, and the HTTP request
   under QStash and Resend). Labels are bounded; see [CONTRACT.md](CONTRACT.md).
 - Redis, SQS, QStash, S3, Vercel Blob, email and KMS emit a `dependency.call_failed` warning on failure,
-  with dependency, operation and error type only. HTTP transports emit spans and metrics.
+  with dependency, operation and error type only. HTTP/httpx2 also log failed attempts,
+  including body failures and cancellation; QStash/Resend suppress the nested HTTP log.
 - `DependencyUnavailable(dependency, operation, reason)` when the service timed out,
   refused the connection, throttled or failed with a 5xx. Map it to a 503. Errors that mean
   the request is wrong (access denied, a missing bucket, a wrong Redis type) keep their
@@ -290,21 +295,58 @@ ciphertext keep their botocore type (they are bugs or attacks, not outages); a t
 envelope raises `cryptography`'s `InvalidTag`. The envelope layout is in
 [CONTRACT.md](CONTRACT.md).
 
+### HTTP bodies and streaming
+
+```python
+from clients_021.http import HttpClient
+
+http = HttpClient(obs, timeout_seconds=10)
+try:
+    async with http.stream("GET", download_url, dependency="documents") as response:
+        response.raise_for_status()
+        async for chunk in response.aiter_bytes():
+            await write_chunk(chunk)
+finally:
+    await http.aclose()
+```
+
+These async clients run on asyncio. `request()` returns a buffered `HttpResponse`; `stream()` yields a native httpx response
+without buffering and accepts an async iterable as upload `content`. Streaming sends once,
+even for GET. The buffered client's configured idempotent retries are unchanged. Close the
+response context before closing the client. For SDKs using native httpx, inject
+`clients_021.http.httpx.ObservedTransport`; httpx2 SDKs use the transport below.
+
+Each HTTP attempt emits one span, counter and duration after body EOF and connection close,
+or early close. This includes upload, download, pauses between chunks and cleanup. Body
+errors after 200 headers are recorded as errors. `http.response.body.complete` distinguishes
+EOF from partial/unread close; it does not mean the status or cleanup succeeded. Intentional
+partial close is INFO `dependency.stream_closed`; exceptions, cancellation and HTTP >= 400
+produce WARNING `dependency.call_failed`. No success log, URL, header, body or provider
+error message is emitted. `log_failures=False` disables attempt logs when an enclosing
+operation owns the warning, as QStash and Resend do.
+
+These duration semantics and the completion label change the 0.2.x telemetry contract;
+see [migration notes](CONTRACT.md#migration-from-02x) before updating dashboards or alerts.
+
 ### SDKs on httpx2
 
 For an SDK on httpx2:
 
 ```python
 from anthropic import AsyncAnthropic, DefaultAsyncHttpxClient
-from clients_021.httpx2 import ObservedTransport
+from clients_021.http.httpx2 import ObservedTransport
 
 transport = ObservedTransport(obs, dependency="anthropic")
 claude = AsyncAnthropic(http_client=DefaultAsyncHttpxClient(transport=transport))
 ```
 
-It does not send `traceparent` to third-party APIs unless `propagate=True`.
+It does not inject trace context into third-party API requests unless `propagate=True`.
 The transport preserves SDK exceptions so the SDK retains control of retries and error
-handling; it does not convert them to `DependencyUnavailable`.
+handling; it does not convert them to `DependencyUnavailable`. Its span stays open through
+incremental response reads and close. Use the SDK's stream context manager, or close manual
+responses explicitly; abandoning a stream leaves both its connection and span open. Caller
+processing keeps its own trace context, including when streams are interleaved or consumed
+in another task.
 
 ## Service integration
 
@@ -338,7 +380,7 @@ async with AsyncExitStack() as resources:
 
 Retry policies are explicit:
 
-- HTTP retries GET, HEAD, OPTIONS, PUT and DELETE on network failures, timeouts,
+- Buffered HTTP (`request`) retries GET, HEAD, OPTIONS, PUT and DELETE on network failures, timeouts,
   remote protocol/proxy connection failures and 502/503/504. `retries=2` means at most
   three attempts.
   POST and PATCH run once. Invalid URLs/protocols and invalid request construction keep
@@ -372,10 +414,11 @@ stop an SDK request already running in its thread. Timeouts are per SDK/network
 not an overall deadline. Limit consumer concurrency and let in-flight work finish before
 closing the clients. Redis window counters require Redis server 7 or newer (`EXPIRE NX`).
 
-HTTP transport spans end when response headers arrive. Body downloads and SDK streaming
-are outside that span; instrument the enclosing service/SDK operation when you need total
-latency or failures while consuming the body. S3 `get` buffers the entire object in memory;
-use a dedicated streaming adapter for large files.
+HTTP spans now include network body consumption and cleanup. The SDK/application still
+owns content decoding, JSON/SSE interpretation and processing errors outside raw-stream I/O.
+Timeouts remain per I/O, not a total stream deadline. Cancellation waits for shielded body
+cleanup before propagating. Close all responses and consumers before shutdown/flush.
+S3 `get` buffers the entire object in memory; use a dedicated streaming adapter for large files.
 
 ## Development
 

{021_python_clients-0.2.0 → 021_python_clients-0.3.0}/README.md

@@ -12,8 +12,8 @@ uv add "021-python-clients[redis,aws,httpx2,vercel-blob]"   # pick the extras yo
 
 | Module | Extra | What it gives |
 | --- | --- | --- |
-| `clients_021.http` | none | `HttpClient`: one httpx client per dependency, timeouts, retries on idempotent methods |
-| `clients_021.httpx2` | `httpx2` | `ObservedTransport` for SDKs built on httpx2 (Anthropic, OpenAI) |
+| `clients_021.http.httpx` | none | `HttpClient`: buffered requests, streaming and full-body telemetry; native `ObservedTransport` |
+| `clients_021.http.httpx2` | `httpx2` | `ObservedTransport` for SDKs built on httpx2 (Anthropic, OpenAI) |
 | `clients_021.cache.redis` | `redis` | `RedisClient`: JSON with TTL, one-time reads, windowed counters, ping |
 | `clients_021.queue.qstash` | none | `QStashClient`: JSON publishing, deduplication, delivery options and forwarded trace context |
 | `clients_021.queue.sqs` | `aws` | `SqsClient`: send, receive, delete, visibility, trace carried in the message |
@@ -30,10 +30,12 @@ Every client takes the service's `Observability` (from `setup_observability`) an
 
 Providers with the same purpose live under one capability package: `email/` contains
 Resend and SES; `queue/` contains SQS and QStash; `storage/` contains S3 and Vercel Blob; `cache/`
-contains Redis; `crypto/` contains KMS. HTTP transports remain at the root. Import providers
-explicitly:
+contains Redis; `crypto/` contains KMS. `http/` contains the httpx client and httpx2
+transport. Import providers explicitly:
 
 ```python
+from clients_021.http import HttpClient
+from clients_021.http.httpx2 import ObservedTransport  # requires the httpx2 extra
 from clients_021.queue.sqs import SqsClient
 from clients_021.queue.qstash import QStashClient
 from clients_021.storage.s3 import S3Client
@@ -49,7 +51,9 @@ does not load the optional AWS SDK.
 
 The 0.1.0 imports `clients_021.redis`, `clients_021.s3` and `clients_021.kms` remain
 compatible aliases for the same classes and result types. Importing a capability package
-does not load its optional SDKs.
+does not load its optional SDKs. `clients_021.HttpClient` and `clients_021.http` keep their
+published exports; `clients_021.httpx2.ObservedTransport` remains an alias for
+`clients_021.http.httpx2.ObservedTransport`.
 
 ## What every call gets
 
@@ -61,7 +65,8 @@ does not load its optional SDKs.
   `crypto.client.operation.*` (KMS), `http.client.request.*` (HTTP, and the HTTP request
   under QStash and Resend). Labels are bounded; see [CONTRACT.md](CONTRACT.md).
 - Redis, SQS, QStash, S3, Vercel Blob, email and KMS emit a `dependency.call_failed` warning on failure,
-  with dependency, operation and error type only. HTTP transports emit spans and metrics.
+  with dependency, operation and error type only. HTTP/httpx2 also log failed attempts,
+  including body failures and cancellation; QStash/Resend suppress the nested HTTP log.
 - `DependencyUnavailable(dependency, operation, reason)` when the service timed out,
   refused the connection, throttled or failed with a 5xx. Map it to a 503. Errors that mean
   the request is wrong (access denied, a missing bucket, a wrong Redis type) keep their
@@ -254,21 +259,58 @@ ciphertext keep their botocore type (they are bugs or attacks, not outages); a t
 envelope raises `cryptography`'s `InvalidTag`. The envelope layout is in
 [CONTRACT.md](CONTRACT.md).
 
+### HTTP bodies and streaming
+
+```python
+from clients_021.http import HttpClient
+
+http = HttpClient(obs, timeout_seconds=10)
+try:
+    async with http.stream("GET", download_url, dependency="documents") as response:
+        response.raise_for_status()
+        async for chunk in response.aiter_bytes():
+            await write_chunk(chunk)
+finally:
+    await http.aclose()
+```
+
+These async clients run on asyncio. `request()` returns a buffered `HttpResponse`; `stream()` yields a native httpx response
+without buffering and accepts an async iterable as upload `content`. Streaming sends once,
+even for GET. The buffered client's configured idempotent retries are unchanged. Close the
+response context before closing the client. For SDKs using native httpx, inject
+`clients_021.http.httpx.ObservedTransport`; httpx2 SDKs use the transport below.
+
+Each HTTP attempt emits one span, counter and duration after body EOF and connection close,
+or early close. This includes upload, download, pauses between chunks and cleanup. Body
+errors after 200 headers are recorded as errors. `http.response.body.complete` distinguishes
+EOF from partial/unread close; it does not mean the status or cleanup succeeded. Intentional
+partial close is INFO `dependency.stream_closed`; exceptions, cancellation and HTTP >= 400
+produce WARNING `dependency.call_failed`. No success log, URL, header, body or provider
+error message is emitted. `log_failures=False` disables attempt logs when an enclosing
+operation owns the warning, as QStash and Resend do.
+
+These duration semantics and the completion label change the 0.2.x telemetry contract;
+see [migration notes](CONTRACT.md#migration-from-02x) before updating dashboards or alerts.
+
 ### SDKs on httpx2
 
 For an SDK on httpx2:
 
 ```python
 from anthropic import AsyncAnthropic, DefaultAsyncHttpxClient
-from clients_021.httpx2 import ObservedTransport
+from clients_021.http.httpx2 import ObservedTransport
 
 transport = ObservedTransport(obs, dependency="anthropic")
 claude = AsyncAnthropic(http_client=DefaultAsyncHttpxClient(transport=transport))
 ```
 
-It does not send `traceparent` to third-party APIs unless `propagate=True`.
+It does not inject trace context into third-party API requests unless `propagate=True`.
 The transport preserves SDK exceptions so the SDK retains control of retries and error
-handling; it does not convert them to `DependencyUnavailable`.
+handling; it does not convert them to `DependencyUnavailable`. Its span stays open through
+incremental response reads and close. Use the SDK's stream context manager, or close manual
+responses explicitly; abandoning a stream leaves both its connection and span open. Caller
+processing keeps its own trace context, including when streams are interleaved or consumed
+in another task.
 
 ## Service integration
 
@@ -302,7 +344,7 @@ async with AsyncExitStack() as resources:
 
 Retry policies are explicit:
 
-- HTTP retries GET, HEAD, OPTIONS, PUT and DELETE on network failures, timeouts,
+- Buffered HTTP (`request`) retries GET, HEAD, OPTIONS, PUT and DELETE on network failures, timeouts,
   remote protocol/proxy connection failures and 502/503/504. `retries=2` means at most
   three attempts.
   POST and PATCH run once. Invalid URLs/protocols and invalid request construction keep
@@ -336,10 +378,11 @@ stop an SDK request already running in its thread. Timeouts are per SDK/network
 not an overall deadline. Limit consumer concurrency and let in-flight work finish before
 closing the clients. Redis window counters require Redis server 7 or newer (`EXPIRE NX`).
 
-HTTP transport spans end when response headers arrive. Body downloads and SDK streaming
-are outside that span; instrument the enclosing service/SDK operation when you need total
-latency or failures while consuming the body. S3 `get` buffers the entire object in memory;
-use a dedicated streaming adapter for large files.
+HTTP spans now include network body consumption and cleanup. The SDK/application still
+owns content decoding, JSON/SSE interpretation and processing errors outside raw-stream I/O.
+Timeouts remain per I/O, not a total stream deadline. Cancellation waits for shielded body
+cleanup before propagating. Close all responses and consumers before shutdown/flush.
+S3 `get` buffers the entire object in memory; use a dedicated streaming adapter for large files.
 
 ## Development
 

{021_python_clients-0.2.0 → 021_python_clients-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "021-python-clients"
-version = "0.2.0"
+version = "0.3.0"
 description = "Observed clients for Redis, SQS, QStash, S3, Vercel Blob, HTTP, email and KMS, built on 021-python-observability"
 readme = "README.md"
 license = "Apache-2.0"

{021_python_clients-0.2.0 → 021_python_clients-0.3.0}/src/clients_021/__init__.py

@@ -3,7 +3,7 @@
 `clients_021.http`, `clients_021.queue.qstash` and `clients_021.email` (Resend) need no extras;
 `clients_021.cache.redis` needs the `redis` extra; `clients_021.queue.sqs`,
 `clients_021.storage.s3`, `clients_021.email.ses` and `clients_021.crypto.kms` the `aws` extra;
-`clients_021.httpx2` the `httpx2` extra.
+`clients_021.http.httpx2` the `httpx2` extra.
 `clients_021.storage.vercel_blob` needs the `vercel-blob` extra.
 """
 

{021_python_clients-0.2.0 → 021_python_clients-0.3.0}/src/clients_021/email/resend.py

@@ -98,7 +98,11 @@ class ResendSender:
         }
         inner = transport if transport is not None else httpx.AsyncHTTPTransport()
         self._http = HttpClient(
-            obs, timeout_seconds=timeout_seconds, retries=0, transport=_WithoutTraceHeaders(inner)
+            obs,
+            timeout_seconds=timeout_seconds,
+            retries=0,
+            log_failures=False,
+            transport=_WithoutTraceHeaders(inner),
         )
 
     async def send(self, message: EmailMessage, *, idempotency_key: str | None = None) -> str:

021_python_clients-0.3.0/src/clients_021/http/__init__.py

@@ -0,0 +1,11 @@
+"""HTTP clients and transports; optional implementations are imported explicitly."""
+
+from clients_021.http.httpx import (
+    IDEMPOTENT_METHODS,
+    RETRY_STATUS,
+    HttpClient,
+    HttpMethod,
+    HttpResponse,
+)
+
+__all__ = ["IDEMPOTENT_METHODS", "RETRY_STATUS", "HttpClient", "HttpMethod", "HttpResponse"]