httpware 0.4.0__tar.gz → 0.5.0__tar.gz

{httpware-0.4.0 → httpware-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: httpware
-Version: 0.4.0
+Version: 0.5.0
 Summary: Resilience-first async HTTP client framework for Python
 Keywords: http,async,client,resilience,retry,circuit-breaker,middleware,httpx,pydantic
 Author: Artur Shiriev
@@ -89,6 +89,25 @@ async def main() -> None:
         user = await client.get("/users/1", response_model=User)
 ```
 
+### Streaming responses
+
+For large responses or server-sent events, stream the body chunk-by-chunk. `stream()` is an async context manager:
+
+```python
+from httpware import AsyncClient
+
+
+async def main() -> None:
+    async with AsyncClient(base_url="https://api.example.com") as client:
+        async with client.stream("GET", "/big-file") as response:
+            async for chunk in response.aiter_bytes():
+                process(chunk)
+```
+
+`stream()` auto-raises `StatusError` subclasses on 4xx/5xx with the response body pre-read, so `exc.response.content` is accessible from the caught exception.
+
+It does NOT pass through the middleware chain: `Retry`, `Bulkhead`, and any custom middleware are bypassed. (Retry separately refuses to retry any request — stream or non-stream — whose body was an async-iterable, since streams can't replay across attempts.)
+
 ## Errors
 
 All 4xx/5xx responses raise typed exceptions automatically: `NotFoundError`, `ServiceUnavailableError`, `RateLimitedError`, etc. — all subclasses of `httpware.StatusError`. Transport-layer transient failures raise `NetworkError`; the resilience middleware raise `RetryBudgetExhaustedError` and `BulkheadFullError`. Everything inherits `httpware.ClientError`.

{httpware-0.4.0 → httpware-0.5.0}/README.md

@@ -61,6 +61,25 @@ async def main() -> None:
         user = await client.get("/users/1", response_model=User)
 ```
 
+### Streaming responses
+
+For large responses or server-sent events, stream the body chunk-by-chunk. `stream()` is an async context manager:
+
+```python
+from httpware import AsyncClient
+
+
+async def main() -> None:
+    async with AsyncClient(base_url="https://api.example.com") as client:
+        async with client.stream("GET", "/big-file") as response:
+            async for chunk in response.aiter_bytes():
+                process(chunk)
+```
+
+`stream()` auto-raises `StatusError` subclasses on 4xx/5xx with the response body pre-read, so `exc.response.content` is accessible from the caught exception.
+
+It does NOT pass through the middleware chain: `Retry`, `Bulkhead`, and any custom middleware are bypassed. (Retry separately refuses to retry any request — stream or non-stream — whose body was an async-iterable, since streams can't replay across attempts.)
+
 ## Errors
 
 All 4xx/5xx responses raise typed exceptions automatically: `NotFoundError`, `ServiceUnavailableError`, `RateLimitedError`, etc. — all subclasses of `httpware.StatusError`. Transport-layer transient failures raise `NetworkError`; the resilience middleware raise `RetryBudgetExhaustedError` and `BulkheadFullError`. Everything inherits `httpware.ClientError`.

{httpware-0.4.0 → httpware-0.5.0}/pyproject.toml

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

{httpware-0.4.0 → httpware-0.5.0}/src/httpware/client.py

@@ -1,7 +1,8 @@
 """AsyncClient — the thin httpx2 wrapper."""
 
+import contextlib
 import typing
-from collections.abc import Sequence
+from collections.abc import AsyncIterator, Sequence
 from http import HTTPStatus
 
 import httpx2
@@ -44,6 +45,48 @@ def _default_pydantic_decoder() -> ResponseDecoder:
     return PydanticDecoder()
 
 
+@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.TimeoutException as exc:
+        raise TimeoutError(str(exc)) from exc
+    except (httpx2.InvalidURL, httpx2.CookieConflict) as exc:
+        raise TransportError(str(exc)) from exc
+    except httpx2.NetworkError as exc:
+        raise NetworkError(str(exc)) from exc
+    except httpx2.HTTPError as exc:
+        raise TransportError(str(exc)) from exc
+
+
+def _raise_on_status_error(response: httpx2.Response) -> None:
+    """Raise the appropriate StatusError subclass for a 4xx/5xx response. No-op for 2xx/3xx."""
+    status = response.status_code
+    if HTTPStatus.BAD_REQUEST <= status < 600:  # noqa: PLR2004 — 600 is the synthetic upper bound for 5xx
+        exc_class = STATUS_TO_EXCEPTION.get(
+            status,
+            ClientStatusError if status < HTTPStatus.INTERNAL_SERVER_ERROR else ServerStatusError,
+        )
+        raise exc_class(response)
+
+
+STREAMING_BODY_MARKER = "httpware.streaming_body"
+"""Key set on ``httpx2.Request.extensions`` by ``_request_with_body`` when content/data/files is an async-iterable.
+
+``Retry.__call__`` reads this marker to refuse retrying a streamed-body request
+(the consumed iterator cannot replay across attempts)."""
+
+
+def _is_streaming_body(value: typing.Any) -> bool:
+    """Return True if value is an async-iterable that cannot be safely replayed for retry."""
+    if value is None:
+        return False
+    if isinstance(value, (bytes, bytearray, memoryview, str, dict)):
+        return False
+    return hasattr(value, "__aiter__")
+
+
 class AsyncClient:
     """Async HTTP client: thin wrapper around httpx2 with typed decoding and middleware."""
 
@@ -106,26 +149,13 @@ class AsyncClient:
 
     async def _terminal(self, request: httpx2.Request) -> httpx2.Response:
         try:
-            response = await self._httpx2_client.send(request)
-        except httpx2.TimeoutException as exc:
-            raise TimeoutError(str(exc)) from exc
-        except (httpx2.InvalidURL, httpx2.CookieConflict) as exc:
-            raise TransportError(str(exc)) from exc
-        except httpx2.NetworkError as exc:
-            raise NetworkError(str(exc)) from exc
-        except httpx2.HTTPError as exc:
-            raise TransportError(str(exc)) from exc
+            async with _httpx2_exception_mapper():
+                response = await self._httpx2_client.send(request)
         except RuntimeError as exc:
             if "closed" in str(exc):
                 raise TransportError(str(exc)) from exc
             raise
-        status = response.status_code
-        if HTTPStatus.BAD_REQUEST <= status < 600:  # noqa: PLR2004 — 600 is the synthetic upper bound for 5xx
-            exc_class = STATUS_TO_EXCEPTION.get(
-                status,
-                ClientStatusError if status < HTTPStatus.INTERNAL_SERVER_ERROR else ServerStatusError,
-            )
-            raise exc_class(response)
+        _raise_on_status_error(response)
         return response
 
     @typing.overload
@@ -150,7 +180,7 @@ class AsyncClient:
         """Delegate request construction to the wrapped httpx2.AsyncClient."""
         return self._httpx2_client.build_request(method, url, **kwargs)
 
-    async def _request_with_body(  # noqa: PLR0913 — mirrors httpx2 per-method signatures
+    async def _request_with_body(  # noqa: PLR0913, C901 — mirrors httpx2 per-method signatures; kwargs-forwarding complexity is structural
         self,
         method: str,
         url: str,
@@ -186,6 +216,8 @@ class AsyncClient:
         if files is not None:
             kwargs["files"] = files
         request = self._httpx2_client.build_request(method, url, **kwargs)
+        if _is_streaming_body(content) or _is_streaming_body(data) or _is_streaming_body(files):
+            request.extensions[STREAMING_BODY_MARKER] = True
         return await self.send(request, response_model=response_model)
 
     @typing.overload
@@ -663,6 +695,66 @@ class AsyncClient:
             response_model=response_model,
         )
 
+    @contextlib.asynccontextmanager
+    async def stream(  # noqa: PLR0913, C901 — mirrors httpx2 per-method signatures; kwargs-forwarding complexity is structural
+        self,
+        method: str,
+        url: str,
+        *,
+        params: typing.Any | None = None,
+        headers: typing.Any | None = None,
+        cookies: typing.Any | None = None,
+        timeout: typing.Any = httpx2.USE_CLIENT_DEFAULT,
+        extensions: typing.Any | None = None,
+        json: typing.Any | None = None,
+        content: typing.Any | None = None,
+        data: typing.Any | None = None,
+        files: typing.Any | None = None,
+    ) -> AsyncIterator[httpx2.Response]:
+        """Stream an HTTP response. Bypasses the middleware chain.
+
+        Yields an httpx2.Response; consume the body via response.aiter_bytes(),
+        response.aiter_text(), response.aiter_lines(), or response.aiter_raw().
+        The body is NOT pre-read for 2xx/3xx (streaming preserved); the response
+        is closed when the context exits.
+
+        Bypasses the middleware chain (no Retry, no Bulkhead, no user-installed
+        middleware) for v1 — see planning/specs/2026-06-05-streaming-design.md.
+
+        Auto-raises StatusError subclasses on 4xx/5xx (NotFoundError,
+        ServiceUnavailableError, etc.) — consistent with client.get()/post()/etc.
+        On error the response body is pre-read so exc.response.content is
+        accessible. You lose the streaming property on errors; rare in practice.
+
+        Maps httpx2 exceptions raised during the request OR body consumption to
+        httpware exceptions via _httpx2_exception_mapper.
+        """
+        kwargs: dict[str, typing.Any] = {}
+        if params is not None:
+            kwargs["params"] = params
+        if headers is not None:
+            kwargs["headers"] = headers
+        if cookies is not None:
+            kwargs["cookies"] = cookies
+        if timeout is not httpx2.USE_CLIENT_DEFAULT:
+            kwargs["timeout"] = timeout
+        if extensions is not None:
+            kwargs["extensions"] = extensions
+        if json is not None:
+            kwargs["json"] = json
+        if content is not None:
+            kwargs["content"] = content
+        if data is not None:
+            kwargs["data"] = data
+        if files is not None:
+            kwargs["files"] = files
+
+        async with _httpx2_exception_mapper(), self._httpx2_client.stream(method, url, **kwargs) as response:
+            if HTTPStatus.BAD_REQUEST <= response.status_code < 600:  # noqa: PLR2004 — 600 is the synthetic upper bound for 5xx
+                await response.aread()  # pre-read body so exc.response.content works
+                _raise_on_status_error(response)
+            yield response
+
     async def __aenter__(self) -> typing.Self:
         """Enter the async context manager; return self."""
         return self

{httpware-0.4.0 → httpware-0.5.0}/src/httpware/middleware/resilience/retry.py

@@ -16,6 +16,7 @@ from http import HTTPStatus
 
 import httpx2
 
+from httpware.client import STREAMING_BODY_MARKER
 from httpware.errors import NetworkError, RetryBudgetExhaustedError, StatusError, TimeoutError  # noqa: A004
 from httpware.middleware import Next
 from httpware.middleware.resilience._backoff import full_jitter_delay
@@ -43,6 +44,7 @@ DEFAULT_IDEMPOTENT_METHODS = frozenset(
 )
 
 _MAX_ATTEMPTS_INVALID = "max_attempts must be >= 1"
+_STREAMING_BODY_REFUSAL_NOTE = "httpware: not retrying — request body is a stream that cannot replay across attempts"
 
 
 def _parse_retry_after(value: str) -> float | None:
@@ -90,7 +92,7 @@ class Retry:
         self.budget = budget if budget is not None else RetryBudget()
         self._sleep = _sleep
 
-    async def __call__(self, request: httpx2.Request, next: Next) -> httpx2.Response:  # noqa: A002, C901, PLR0912 — complexity budget: 3 error clauses + idempotency gate + budget gate + Retry-After branch + backoff
+    async def __call__(self, request: httpx2.Request, next: Next) -> httpx2.Response:  # noqa: A002, C901, PLR0912, PLR0915 — complexity budget: 3 error clauses + idempotency gate + streaming-body refusal + budget gate + Retry-After branch + backoff
         """Process a request through the retry loop. See module docstring."""
         method_eligible = request.method.upper() in self.retry_methods
         last_exc: BaseException | None = None
@@ -106,12 +108,17 @@ class Retry:
                 else:
                     return await next(request)
             except StatusError as exc:
-                if not method_eligible or exc.response.status_code not in self.retry_status_codes:
+                retryable_status = exc.response.status_code in self.retry_status_codes
+                if not method_eligible or not retryable_status:
+                    if retryable_status and request.extensions.get(STREAMING_BODY_MARKER):
+                        exc.add_note(_STREAMING_BODY_REFUSAL_NOTE)
                     raise
                 last_exc = exc
                 last_response = exc.response
             except (NetworkError, TimeoutError) as exc:
                 if not method_eligible:
+                    if request.extensions.get(STREAMING_BODY_MARKER):
+                        exc.add_note(_STREAMING_BODY_REFUSAL_NOTE)
                     raise
                 last_exc = exc
                 last_response = None
@@ -119,11 +126,20 @@ class Retry:
                 wrapped = TimeoutError("attempt timed out")
                 wrapped.__cause__ = exc  # set now; the retry path (last_exc = wrapped) has no `from` clause
                 if not method_eligible:
+                    if request.extensions.get(STREAMING_BODY_MARKER):
+                        wrapped.add_note(_STREAMING_BODY_REFUSAL_NOTE)
                     raise wrapped from exc
                 last_exc = wrapped
                 last_response = None
 
             # ---- retryable failure path
+            if request.extensions.get(STREAMING_BODY_MARKER):
+                if last_exc is None:  # pragma: no cover — invariant from except branch
+                    msg = "Retry: streaming-body refusal reached with no last_exc"
+                    raise AssertionError(msg)
+                last_exc.add_note(_STREAMING_BODY_REFUSAL_NOTE)
+                raise last_exc
+
             if is_last:
                 if last_exc is None:  # pragma: no cover — structural invariant from except branch
                     msg = "Retry: last_exc unset on final attempt — unreachable"