httpware 0.6.0__tar.gz → 0.8.0__tar.gz

{httpware-0.6.0 → httpware-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: httpware
-Version: 0.6.0
+Version: 0.8.0
 Summary: Resilience-first async HTTP client framework for Python
 Keywords: http,async,client,resilience,retry,circuit-breaker,middleware,httpx,pydantic
 Author: Artur Shiriev
@@ -37,7 +37,7 @@ Description-Content-Type: text/markdown
 
 **Async HTTP client framework for Python.**
 
-`httpware` is a thin opinionated wrapper around `httpx2`. It re-exports `httpx2.Request`/`httpx2.Response`, adds a middleware chain composed at client construction, supports opt-in typed response decoding (pydantic and msgspec are both extras), and raises a status-keyed exception tree automatically on 4xx/5xx. It also ships a small resilience suite — `Retry` middleware with a Finagle-style `RetryBudget`, plus a `Bulkhead` concurrency limiter — under `httpware.middleware.resilience`.
+`httpware` is a thin opinionated wrapper around `httpx2`. It re-exports `httpx2.Request`/`httpx2.Response`, adds a middleware chain composed at client construction, supports opt-in typed response decoding (pydantic and msgspec are both extras), and raises a status-keyed exception tree automatically on 4xx/5xx. It also ships a small resilience suite — `AsyncRetry` middleware with a Finagle-style `RetryBudget`, plus an `AsyncBulkhead` concurrency limiter — under `httpware.middleware.resilience`.
 
 > **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0.
 
@@ -54,7 +54,32 @@ pip install httpware[all]           # everything declared above (pydantic, msgsp
 
 ## Quickstart
 
-> Requires: `pip install httpware[pydantic]`
+**Async usage:**
+
+```python
+import asyncio
+
+from httpware import AsyncClient
+
+async def main() -> None:
+    async with AsyncClient(base_url="https://example.test") as client:
+        response = await client.get("/users/42")
+        print(response.json())
+
+asyncio.run(main())
+```
+
+**Sync usage:**
+
+```python
+from httpware import Client
+
+with Client(base_url="https://example.test") as client:
+    response = client.get("/users/42")
+    print(response.json())
+```
+
+Typed decoding via `response_model=` works in both worlds — requires `pip install httpware[pydantic]`:
 
 ```python
 from httpware import AsyncClient
@@ -74,23 +99,25 @@ async def main() -> None:
 
 ### With resilience middleware
 
-Compose resilience middleware at construction; `Bulkhead` goes outside `Retry` so one slot covers all retry attempts.
+Compose resilience middleware at construction; `AsyncBulkhead` goes outside `AsyncRetry` so one slot covers all retry attempts.
 
 ```python
-from httpware import AsyncClient, Bulkhead, Retry
+from httpware import AsyncClient, AsyncBulkhead, AsyncRetry
 
 
 async def main() -> None:
     async with AsyncClient(
         base_url="https://api.example.com",
         middleware=[
-            Bulkhead(max_concurrent=10),  # cap total in-flight
-            Retry(),                       # default: 3 attempts, full-jitter backoff
+            AsyncBulkhead(max_concurrent=10),  # cap total in-flight
+            AsyncRetry(),                       # default: 3 attempts, full-jitter backoff
         ],
     ) as client:
         user = await client.get("/users/1", response_model=User)
 ```
 
+Need a custom middleware (auth, tracing, request-ID propagation, etc.)? See the [Middleware guide](docs/middleware.md).
+
 ### Streaming responses
 
 For large responses or server-sent events, stream the body chunk-by-chunk. `stream()` is an async context manager:
@@ -108,7 +135,7 @@ async def main() -> None:
 
 `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.)
+It does NOT pass through the middleware chain: `AsyncRetry`, `AsyncBulkhead`, and any custom middleware are bypassed. (AsyncRetry separately refuses to retry any request — stream or non-stream — whose body was an async-iterable, since streams can't replay across attempts.)
 
 ## Errors
 
@@ -116,7 +143,7 @@ All 4xx/5xx responses raise typed exceptions automatically: `NotFoundError`, `Se
 
 ## Observability
 
-`Retry` and `Bulkhead` emit operational events via two channels — stdlib `logging` records (always on) and OpenTelemetry span events (when `opentelemetry-api` is installed).
+`AsyncRetry` and `AsyncBulkhead` emit operational events via two channels — stdlib `logging` records (always on) and OpenTelemetry span events (when `opentelemetry-api` is installed).
 
 Logger names (`httpware.retry`, `httpware.bulkhead`) and event names (`retry.giving_up`, `retry.budget_refused`, `retry.streaming_refused`, `bulkhead.rejected`) are the stable public contract.
 

{httpware-0.6.0 → httpware-0.8.0}/README.md

@@ -7,7 +7,7 @@
 
 **Async HTTP client framework for Python.**
 
-`httpware` is a thin opinionated wrapper around `httpx2`. It re-exports `httpx2.Request`/`httpx2.Response`, adds a middleware chain composed at client construction, supports opt-in typed response decoding (pydantic and msgspec are both extras), and raises a status-keyed exception tree automatically on 4xx/5xx. It also ships a small resilience suite — `Retry` middleware with a Finagle-style `RetryBudget`, plus a `Bulkhead` concurrency limiter — under `httpware.middleware.resilience`.
+`httpware` is a thin opinionated wrapper around `httpx2`. It re-exports `httpx2.Request`/`httpx2.Response`, adds a middleware chain composed at client construction, supports opt-in typed response decoding (pydantic and msgspec are both extras), and raises a status-keyed exception tree automatically on 4xx/5xx. It also ships a small resilience suite — `AsyncRetry` middleware with a Finagle-style `RetryBudget`, plus an `AsyncBulkhead` concurrency limiter — under `httpware.middleware.resilience`.
 
 > **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0.
 
@@ -24,7 +24,32 @@ pip install httpware[all]           # everything declared above (pydantic, msgsp
 
 ## Quickstart
 
-> Requires: `pip install httpware[pydantic]`
+**Async usage:**
+
+```python
+import asyncio
+
+from httpware import AsyncClient
+
+async def main() -> None:
+    async with AsyncClient(base_url="https://example.test") as client:
+        response = await client.get("/users/42")
+        print(response.json())
+
+asyncio.run(main())
+```
+
+**Sync usage:**
+
+```python
+from httpware import Client
+
+with Client(base_url="https://example.test") as client:
+    response = client.get("/users/42")
+    print(response.json())
+```
+
+Typed decoding via `response_model=` works in both worlds — requires `pip install httpware[pydantic]`:
 
 ```python
 from httpware import AsyncClient
@@ -44,23 +69,25 @@ async def main() -> None:
 
 ### With resilience middleware
 
-Compose resilience middleware at construction; `Bulkhead` goes outside `Retry` so one slot covers all retry attempts.
+Compose resilience middleware at construction; `AsyncBulkhead` goes outside `AsyncRetry` so one slot covers all retry attempts.
 
 ```python
-from httpware import AsyncClient, Bulkhead, Retry
+from httpware import AsyncClient, AsyncBulkhead, AsyncRetry
 
 
 async def main() -> None:
     async with AsyncClient(
         base_url="https://api.example.com",
         middleware=[
-            Bulkhead(max_concurrent=10),  # cap total in-flight
-            Retry(),                       # default: 3 attempts, full-jitter backoff
+            AsyncBulkhead(max_concurrent=10),  # cap total in-flight
+            AsyncRetry(),                       # default: 3 attempts, full-jitter backoff
         ],
     ) as client:
         user = await client.get("/users/1", response_model=User)
 ```
 
+Need a custom middleware (auth, tracing, request-ID propagation, etc.)? See the [Middleware guide](docs/middleware.md).
+
 ### Streaming responses
 
 For large responses or server-sent events, stream the body chunk-by-chunk. `stream()` is an async context manager:
@@ -78,7 +105,7 @@ async def main() -> None:
 
 `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.)
+It does NOT pass through the middleware chain: `AsyncRetry`, `AsyncBulkhead`, and any custom middleware are bypassed. (AsyncRetry separately refuses to retry any request — stream or non-stream — whose body was an async-iterable, since streams can't replay across attempts.)
 
 ## Errors
 
@@ -86,7 +113,7 @@ All 4xx/5xx responses raise typed exceptions automatically: `NotFoundError`, `Se
 
 ## Observability
 
-`Retry` and `Bulkhead` emit operational events via two channels — stdlib `logging` records (always on) and OpenTelemetry span events (when `opentelemetry-api` is installed).
+`AsyncRetry` and `AsyncBulkhead` emit operational events via two channels — stdlib `logging` records (always on) and OpenTelemetry span events (when `opentelemetry-api` is installed).
 
 Logger names (`httpware.retry`, `httpware.bulkhead`) and event names (`retry.giving_up`, `retry.budget_refused`, `retry.streaming_refused`, `bulkhead.rejected`) are the stable public contract.
 

{httpware-0.6.0 → httpware-0.8.0}/pyproject.toml

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

{httpware-0.6.0 → httpware-0.8.0}/src/httpware/__init__.py

@@ -1,6 +1,6 @@
-"""httpware — thin async HTTP client wrapper over httpx2."""
+"""httpware — thin async + sync HTTP client wrapper over httpx2."""
 
-from httpware.client import AsyncClient
+from httpware.client import AsyncClient, Client
 from httpware.decoders import ResponseDecoder
 from httpware.errors import (
     STATUS_TO_EXCEPTION,
@@ -23,16 +23,32 @@ from httpware.errors import (
     UnauthorizedError,
     UnprocessableEntityError,
 )
-from httpware.middleware import Middleware, Next, after_response, before_request, on_error
-from httpware.middleware.resilience import Bulkhead, Retry, RetryBudget
+from httpware.middleware import (
+    AsyncMiddleware,
+    AsyncNext,
+    Middleware,
+    Next,
+    after_response,
+    async_after_response,
+    async_before_request,
+    async_on_error,
+    before_request,
+    on_error,
+)
+from httpware.middleware.resilience import AsyncBulkhead, AsyncRetry, Bulkhead, Retry, RetryBudget
 
 
 __all__ = [
     "STATUS_TO_EXCEPTION",
+    "AsyncBulkhead",
     "AsyncClient",
+    "AsyncMiddleware",
+    "AsyncNext",
+    "AsyncRetry",
     "BadRequestError",
     "Bulkhead",
     "BulkheadFullError",
+    "Client",
     "ClientError",
     "ClientStatusError",
     "ConflictError",
@@ -55,6 +71,9 @@ __all__ = [
     "UnauthorizedError",
     "UnprocessableEntityError",
     "after_response",
+    "async_after_response",
+    "async_before_request",
+    "async_on_error",
     "before_request",
     "on_error",
 ]

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

@@ -0,0 +1,28 @@
+"""httpx2 -> httpware exception mapping.
+
+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).
+"""
+
+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

httpware-0.8.0/src/httpware/_internal/status.py

@@ -0,0 +1,47 @@
+"""Status-code dispatch + streaming-body detection.
+
+Shared by Client and AsyncClient. The STREAMING_BODY_MARKER is the public
+extensions key both Retry and AsyncRetry read; renaming it is breaking.
+"""
+
+from http import HTTPStatus
+
+import httpx2
+
+from httpware.errors import STATUS_TO_EXCEPTION, ClientStatusError, ServerStatusError
+
+
+STREAMING_BODY_MARKER = "httpware.streaming_body"
+"""Set on ``httpx2.Request.extensions`` when content/data/files is a non-replayable
+iterable (async-iterable for AsyncClient, sync iterator/generator for Client).
+Retry / AsyncRetry read this marker to refuse retrying a streamed-body request
+(the consumed iterator cannot replay across attempts)."""
+
+
+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)
+
+
+def _is_streaming_body_async(value: object) -> 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__")
+
+
+def _is_streaming_body_sync(value: object) -> bool:
+    """Return True if value is a sync iterable body that cannot be safely replayed for retry."""
+    if value is None:
+        return False
+    if isinstance(value, (bytes, bytearray, memoryview, str, dict, list, tuple)):
+        return False
+    return hasattr(value, "__iter__")