httpware 0.15.0__tar.gz → 0.15.2__tar.gz

{httpware-0.15.0 → httpware-0.15.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: httpware
-Version: 0.15.0
+Version: 0.15.2
 Summary: Python HTTP client framework with sync & async clients and built-in resilience
 Keywords: http-client,httpx,async,asyncio,resilience,retry,circuit-breaker,bulkhead,middleware,pydantic,msgspec,python
 Author: Artur Shiriev
@@ -33,11 +33,17 @@ Provides-Extra: otel
 Provides-Extra: pydantic
 Description-Content-Type: text/markdown
 
-# httpware
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)"  srcset="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/httpware/lockup-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/httpware/lockup-light.svg">
+    <img alt="httpware" src="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/httpware/lockup.png" width="420">
+  </picture>
+</p>
 
 [![PyPI version](https://img.shields.io/pypi/v/httpware.svg)](https://pypi.org/project/httpware/)
 [![Supported Python versions](https://img.shields.io/pypi/pyversions/httpware.svg)](https://pypi.org/project/httpware/)
-[![Downloads](https://img.shields.io/pypi/dm/httpware.svg)](https://pypistats.org/packages/httpware)
+[![Downloads](https://static.pepy.tech/badge/httpware/month)](https://pepy.tech/projects/httpware)
 [![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/modern-python/httpware/actions/workflows/ci.yml)
 [![CI](https://github.com/modern-python/httpware/actions/workflows/ci.yml/badge.svg)](https://github.com/modern-python/httpware/actions/workflows/ci.yml)
 [![License](https://img.shields.io/github/license/modern-python/httpware.svg)](https://github.com/modern-python/httpware/blob/main/LICENSE)
@@ -47,13 +53,19 @@ Description-Content-Type: text/markdown
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
 
-**A Python HTTP client framework with sync and async clients for building resilient service clients.**
+**Typed, resilient HTTP clients for Python — typed errors, typed response bodies, and composable resilience (retry, bulkhead, circuit breaker), sync or async.**
 
 ## Why httpware
 
-- **Typed errors, no `raise_for_status()`** — 4xx/5xx automatically raise a status-keyed exception tree (`NotFoundError`, `RateLimitedError`, …), all under `httpware.StatusError`.
-- **Typed response bodies** — `response_model=YourType` decodes the body straight to your pydantic or msgspec model; a missing decoder fails fast, *before* the request goes out.
-- **Production resilience as composable middleware** — retry + retry-budget, bulkhead, circuit breaker, and timeout, composed at construction — all over standard `httpx2`.
+- **Errors you can catch by name** — a 404 raises `NotFoundError`, a 429
+  `RateLimitedError`, automatically; everything else bubbles up under one
+  `httpware.StatusError` base. No `raise_for_status()`, no status-code
+  branching.
+- **Typed response bodies** — `response_model=User` decodes the body straight
+  to your pydantic or msgspec type; a missing decoder fails fast, *before* the
+  request goes out.
+- **Composable resilience** — retry + retry-budget, bulkhead, circuit breaker,
+  and timeout as middleware over standard `httpx2`.
 
 Built on `httpx2`: httpware re-exports `httpx2.Request`/`httpx2.Response` and stays a thin wrapper, not a new HTTP abstraction.
 

{httpware-0.15.0 → httpware-0.15.2}/README.md

@@ -1,8 +1,14 @@
-# httpware
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)"  srcset="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/httpware/lockup-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/httpware/lockup-light.svg">
+    <img alt="httpware" src="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/httpware/lockup.png" width="420">
+  </picture>
+</p>
 
 [![PyPI version](https://img.shields.io/pypi/v/httpware.svg)](https://pypi.org/project/httpware/)
 [![Supported Python versions](https://img.shields.io/pypi/pyversions/httpware.svg)](https://pypi.org/project/httpware/)
-[![Downloads](https://img.shields.io/pypi/dm/httpware.svg)](https://pypistats.org/packages/httpware)
+[![Downloads](https://static.pepy.tech/badge/httpware/month)](https://pepy.tech/projects/httpware)
 [![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/modern-python/httpware/actions/workflows/ci.yml)
 [![CI](https://github.com/modern-python/httpware/actions/workflows/ci.yml/badge.svg)](https://github.com/modern-python/httpware/actions/workflows/ci.yml)
 [![License](https://img.shields.io/github/license/modern-python/httpware.svg)](https://github.com/modern-python/httpware/blob/main/LICENSE)
@@ -12,13 +18,19 @@
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
 
-**A Python HTTP client framework with sync and async clients for building resilient service clients.**
+**Typed, resilient HTTP clients for Python — typed errors, typed response bodies, and composable resilience (retry, bulkhead, circuit breaker), sync or async.**
 
 ## Why httpware
 
-- **Typed errors, no `raise_for_status()`** — 4xx/5xx automatically raise a status-keyed exception tree (`NotFoundError`, `RateLimitedError`, …), all under `httpware.StatusError`.
-- **Typed response bodies** — `response_model=YourType` decodes the body straight to your pydantic or msgspec model; a missing decoder fails fast, *before* the request goes out.
-- **Production resilience as composable middleware** — retry + retry-budget, bulkhead, circuit breaker, and timeout, composed at construction — all over standard `httpx2`.
+- **Errors you can catch by name** — a 404 raises `NotFoundError`, a 429
+  `RateLimitedError`, automatically; everything else bubbles up under one
+  `httpware.StatusError` base. No `raise_for_status()`, no status-code
+  branching.
+- **Typed response bodies** — `response_model=User` decodes the body straight
+  to your pydantic or msgspec type; a missing decoder fails fast, *before* the
+  request goes out.
+- **Composable resilience** — retry + retry-budget, bulkhead, circuit breaker,
+  and timeout as middleware over standard `httpx2`.
 
 Built on `httpx2`: httpware re-exports `httpx2.Request`/`httpx2.Response` and stays a thin wrapper, not a new HTTP abstraction.
 

{httpware-0.15.0 → httpware-0.15.2}/pyproject.toml

@@ -31,7 +31,7 @@ classifiers = [
     "Topic :: Internet :: WWW/HTTP",
     "Framework :: AsyncIO",
 ]
-version = "0.15.0"
+version = "0.15.2"
 dependencies = [
     "httpx2>=2.0.0,<3.0",
 ]

httpware-0.15.2/src/httpware/_internal/body_cap.py

@@ -0,0 +1,146 @@
+"""Response-body cap enforcement: validate, read-capped (sync + async)."""
+
+import typing
+from collections.abc import Mapping
+from http import HTTPStatus
+
+import httpx2
+
+from httpware.errors import ResponseTooLargeError
+
+
+_MAX_RESPONSE_BODY_BYTES_INVALID = "max_response_body_bytes must be >= 1"
+
+
+def _validate_max_response_body_bytes(cap: int | None) -> None:
+    """Reject a non-None cap below 1. None means unbounded (the default)."""
+    if cap is not None and cap < 1:
+        raise ValueError(_MAX_RESPONSE_BODY_BYTES_INVALID)
+
+
+def _parse_content_length(raw: str | None) -> int | None:
+    """Return a non-negative int Content-Length, or None for missing/garbage. Never raises."""
+    if raw is None:
+        return None
+    try:
+        value = int(raw)
+    except ValueError:
+        return None
+    return value if value >= 0 else None
+
+
+class _CapExceeded(Exception):  # noqa: N818 — internal control-flow signal, not a user-facing error
+    """Internal signal: decoded bytes crossed the cap mid-read. Carries bytes read so far."""
+
+    def __init__(self, *, read: int) -> None:
+        self.read = read
+        super().__init__(f"decoded body exceeded cap after {read} bytes")
+
+
+def _accumulate_capped(chunks: typing.Iterable[bytes], cap: int) -> bytes:
+    """Concatenate `chunks`, raising `_CapExceeded` the moment the running total exceeds `cap`.
+
+    Counts decoded bytes (the in-memory footprint). Grown in a single bytearray
+    so there is no transient list-plus-join double allocation.
+    """
+    buf = bytearray()
+    for chunk in chunks:
+        buf += chunk
+        if len(buf) > cap:
+            raise _CapExceeded(read=len(buf))
+    return bytes(buf)
+
+
+def _safe_extensions(extensions: Mapping[str, typing.Any]) -> dict[str, typing.Any]:
+    """Copy response extensions, dropping the now-stale `network_stream`.
+
+    The rebuilt buffered Response never touches its network stream, so carrying a
+    consumed/closed one wholesale is sloppy. `http_version`/`reason_phrase` and
+    any other keys are preserved.
+    """
+    return {key: value for key, value in extensions.items() if key != "network_stream"}
+
+
+# Headers describing the wire encoding of the body. The accumulator yields the
+# DECODED body, so these no longer apply; httpx2 recomputes content-length from
+# the buffered content. Carrying content-encoding forward makes httpx2 try to
+# re-decode already-decoded bytes and raise.
+_WIRE_BODY_HEADERS = ("content-encoding", "content-length", "transfer-encoding")
+_BODILESS_STATUS = frozenset({HTTPStatus.NO_CONTENT, HTTPStatus.NOT_MODIFIED})  # 204, 304
+
+
+def _buffered_headers(headers: httpx2.Headers) -> httpx2.Headers:
+    """Copy `headers`, stripping wire-encoding headers stale after decoding+buffering."""
+    out = httpx2.Headers(headers)
+    for name in _WIRE_BODY_HEADERS:
+        if name in out:
+            del out[name]
+    return out
+
+
+def _response_has_body(method: str, status_code: int) -> bool:
+    """Whether a response carries a message body (RFC 9110 §6.4.1).
+
+    HEAD responses and 204/304 never have a body regardless of a declared
+    Content-Length, so they must never trip the cap.
+    """
+    return method.upper() != "HEAD" and status_code not in _BODILESS_STATUS
+
+
+def _reject_if_declared_length_exceeds_cap(response: httpx2.Response, cap: int) -> int | None:
+    """Return the parsed Content-Length, raising ResponseTooLargeError(reason="declared") if it already exceeds cap."""
+    content_length = _parse_content_length(response.headers.get("content-length"))
+    if content_length is not None and content_length > cap:
+        raise ResponseTooLargeError(
+            status_code=response.status_code, limit=cap, content_length=content_length, reason="declared"
+        )
+    return content_length
+
+
+def _build_buffered_response(response: httpx2.Response, content: bytes, request: httpx2.Request) -> httpx2.Response:
+    """Rebuild a buffered Response from the original streaming `response` and the final decoded `content`."""
+    return httpx2.Response(
+        status_code=response.status_code,
+        headers=_buffered_headers(response.headers),
+        content=content,
+        request=request,
+        extensions=_safe_extensions(response.extensions),
+        history=response.history,
+    )
+
+
+def _read_capped(response: httpx2.Response, cap: int, request: httpx2.Request) -> httpx2.Response:
+    """Buffer a streaming sync `response` under `cap` decoded bytes; return a buffered Response.
+
+    Raises `ResponseTooLargeError` (reason="declared") if the declared
+    Content-Length already exceeds `cap` — before any byte is read — and
+    (reason="streamed") if the decoded body crosses `cap` mid-read. Does not
+    close `response`; the caller owns the stream lifecycle.
+    """
+    if not _response_has_body(request.method, response.status_code):
+        response.read()  # empty body; preserve the original response (and its headers)
+        return response
+    content_length = _reject_if_declared_length_exceeds_cap(response, cap)
+    try:
+        content = _accumulate_capped(response.iter_bytes(), cap)
+    except _CapExceeded:
+        raise ResponseTooLargeError(
+            status_code=response.status_code, limit=cap, content_length=content_length, reason="streamed"
+        ) from None
+    return _build_buffered_response(response, content, request)
+
+
+async def _read_capped_async(response: httpx2.Response, cap: int, request: httpx2.Request) -> httpx2.Response:
+    """Async mirror of `_read_capped` (counts decoded bytes from `aiter_bytes`)."""
+    if not _response_has_body(request.method, response.status_code):
+        await response.aread()  # empty body; preserve the original response (and its headers)
+        return response
+    content_length = _reject_if_declared_length_exceeds_cap(response, cap)
+    buf = bytearray()
+    async for chunk in response.aiter_bytes():
+        buf += chunk
+        if len(buf) > cap:
+            raise ResponseTooLargeError(
+                status_code=response.status_code, limit=cap, content_length=content_length, reason="streamed"
+            )
+    return _build_buffered_response(response, bytes(buf), request)

httpware-0.15.2/src/httpware/_internal/exception_mapping.py

@@ -0,0 +1,54 @@
+"""httpx2 -> httpware exception mapping + context-manager wrappers (shared).
+
+map_httpx2_exception is a pure function used by both Client._terminal and
+AsyncClient._terminal, and by both stream() methods. Clause ordering:
+TimeoutException -> InvalidURL/CookieConflict -> NetworkError -> HTTPError
+(subclass before parent so the right type wins). The two context managers
+below wrap it for use as `with`/`async with` blocks around the httpx2 call.
+"""
+
+import contextlib
+from collections.abc import AsyncIterator, Iterator
+
+import httpx2
+
+from httpware.errors import NetworkError, TimeoutError, TransportError  # noqa: A004
+
+
+def map_httpx2_exception(exc: BaseException) -> NetworkError | TimeoutError | TransportError:
+    """Map an httpx2 exception to its httpware equivalent.
+
+    Order is significant: more-specific httpx2 types must match before more
+    general ones. We return the mapped exception; the caller does `raise ... from exc`.
+    """
+    if isinstance(exc, httpx2.TimeoutException):
+        return TimeoutError(str(exc))
+    if isinstance(exc, (httpx2.InvalidURL, httpx2.CookieConflict)):
+        return TransportError(str(exc))
+    if isinstance(exc, httpx2.NetworkError):
+        return NetworkError(str(exc))
+    if isinstance(exc, httpx2.HTTPError):
+        return TransportError(str(exc))
+    return TransportError(str(exc))  # pragma: no cover — defensive default; httpx2.HTTPError is the root
+
+
+@contextlib.asynccontextmanager
+async def _httpx2_exception_mapper() -> AsyncIterator[None]:
+    """Map httpx2 exceptions to httpware exceptions. Shared by AsyncClient._terminal and stream()."""
+    try:
+        yield
+    except httpx2.HTTPError as exc:
+        raise map_httpx2_exception(exc) from exc
+    except (httpx2.InvalidURL, httpx2.CookieConflict) as exc:
+        raise map_httpx2_exception(exc) from exc
+
+
+@contextlib.contextmanager
+def _httpx2_exception_mapper_sync() -> Iterator[None]:
+    """Map httpx2 exceptions to httpware exceptions. Sync sibling of _httpx2_exception_mapper."""
+    try:
+        yield
+    except httpx2.HTTPError as exc:
+        raise map_httpx2_exception(exc) from exc
+    except (httpx2.InvalidURL, httpx2.CookieConflict) as exc:
+        raise map_httpx2_exception(exc) from exc

{httpware-0.15.0 → httpware-0.15.2}/src/httpware/_internal/observability.py

@@ -1,6 +1,6 @@
 """Observability emission helper — structured logging + opt-in OpenTelemetry span events.
 
-See planning/specs/2026-06-05-observability-design.md for the contract.
+See architecture/resilience.md (Observability section) for the contract.
 
 Logger names (``httpware.retry``, ``httpware.bulkhead``, ``httpware.circuit_breaker``,
 ``httpware.timeout``) and event names (``retry.giving_up``, ``bulkhead.rejected``,