httpware 0.8.2__tar.gz → 0.8.4__tar.gz

{httpware-0.8.2 → httpware-0.8.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: httpware
-Version: 0.8.2
+Version: 0.8.4
 Summary: Resilience-first async HTTP client framework for Python
 Keywords: http,async,client,resilience,retry,circuit-breaker,middleware,httpx,pydantic
 Author: Artur Shiriev
@@ -35,9 +35,9 @@ Description-Content-Type: text/markdown
 [![Python versions](https://img.shields.io/pypi/pyversions/httpware.svg)](https://pypi.org/project/httpware/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Async HTTP client framework for Python.**
+**A Python HTTP client framework with sync and async clients for building resilient service clients.**
 
-`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`.
+`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`/`Retry` middleware with a Finagle-style `RetryBudget`, plus an `AsyncBulkhead`/`Bulkhead` concurrency limiter — under `httpware.middleware.resilience`.
 
 > **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0.
 
@@ -101,6 +101,8 @@ async def main() -> None:
 
 Compose resilience middleware at construction; `AsyncBulkhead` goes outside `AsyncRetry` so one slot covers all retry attempts.
 
+The sync `Client` accepts identical `middleware=[...]`; swap `AsyncClient` → `Client` and `AsyncRetry` → `Retry` for the sync version.
+
 ```python
 from httpware import AsyncClient, AsyncBulkhead, AsyncRetry
 
@@ -143,7 +145,7 @@ All 4xx/5xx responses raise typed exceptions automatically: `NotFoundError`, `Se
 
 ## Observability
 
-`AsyncRetry` and `AsyncBulkhead` emit operational events via two channels — stdlib `logging` records (always on) and OpenTelemetry span events (when `opentelemetry-api` is installed).
+`AsyncRetry`/`Retry` and `AsyncBulkhead`/`Bulkhead` emit operational events via two channels — stdlib `logging` records (always on) and OpenTelemetry span events (when `opentelemetry-api` is installed). Event names and payloads are identical across sync and async; dashboards built against one class apply unchanged to the other.
 
 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.8.2 → httpware-0.8.4}/README.md

@@ -5,9 +5,9 @@
 [![Python versions](https://img.shields.io/pypi/pyversions/httpware.svg)](https://pypi.org/project/httpware/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Async HTTP client framework for Python.**
+**A Python HTTP client framework with sync and async clients for building resilient service clients.**
 
-`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`.
+`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`/`Retry` middleware with a Finagle-style `RetryBudget`, plus an `AsyncBulkhead`/`Bulkhead` concurrency limiter — under `httpware.middleware.resilience`.
 
 > **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0.
 
@@ -71,6 +71,8 @@ async def main() -> None:
 
 Compose resilience middleware at construction; `AsyncBulkhead` goes outside `AsyncRetry` so one slot covers all retry attempts.
 
+The sync `Client` accepts identical `middleware=[...]`; swap `AsyncClient` → `Client` and `AsyncRetry` → `Retry` for the sync version.
+
 ```python
 from httpware import AsyncClient, AsyncBulkhead, AsyncRetry
 
@@ -113,7 +115,7 @@ All 4xx/5xx responses raise typed exceptions automatically: `NotFoundError`, `Se
 
 ## Observability
 
-`AsyncRetry` and `AsyncBulkhead` emit operational events via two channels — stdlib `logging` records (always on) and OpenTelemetry span events (when `opentelemetry-api` is installed).
+`AsyncRetry`/`Retry` and `AsyncBulkhead`/`Bulkhead` emit operational events via two channels — stdlib `logging` records (always on) and OpenTelemetry span events (when `opentelemetry-api` is installed). Event names and payloads are identical across sync and async; dashboards built against one class apply unchanged to the other.
 
 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.8.2 → httpware-0.8.4}/pyproject.toml

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

httpware-0.8.4/src/httpware/_internal/import_checker.py

@@ -0,0 +1,26 @@
+"""Detect optional extras without importing them. Used by adapter modules to gate hard imports."""
+
+from importlib.metadata import PackageNotFoundError, distribution
+from importlib.util import find_spec
+
+
+def _is_distribution_installed(name: str) -> bool:
+    """Probe the package registry for a distribution by name. No sys.modules side effects."""
+    try:
+        distribution(name)
+    except PackageNotFoundError:
+        return False
+    return True
+
+
+is_msgspec_installed = find_spec("msgspec") is not None
+is_pydantic_installed = find_spec("pydantic") is not None
+# opentelemetry/ is a PEP 420 namespace package — instrumentation packages create the
+# directory even without opentelemetry-api. find_spec("opentelemetry") therefore returns
+# non-None regardless of whether the api package is present, and
+# find_spec("opentelemetry.trace") populates sys.modules with the namespace parent as a
+# CPython side-effect, breaking the isolation guarantee.
+# importlib.metadata.distribution probes the package registry instead: it returns the
+# distribution when opentelemetry-api is installed and raises PackageNotFoundError when
+# it is absent, with no sys.modules side effects.
+is_otel_installed = _is_distribution_installed("opentelemetry-api")

{httpware-0.8.2 → httpware-0.8.4}/src/httpware/_internal/observability.py

@@ -29,7 +29,9 @@ def _emit_event(
        ``trace.get_current_span().add_event(event_name, attributes=attributes)``.
        When no tracer is active, ``get_current_span()`` returns a ``NonRecordingSpan``
        whose ``add_event`` is a documented no-op — so the call is unconditional
-       behind the install gate.
+       behind the install gate. If the install gate is wrong (the namespace exists
+       but the api package is missing or broken), the lazy import raises
+       ``ImportError``; we degrade silently to log-only emission.
 
     The lazy ``from opentelemetry import trace`` inside the if-block preserves
     the optional-extras isolation invariant: ``import httpware`` must not pull
@@ -37,6 +39,10 @@ def _emit_event(
     """
     logger.log(level, message, extra=attributes)
     if import_checker.is_otel_installed:
-        from opentelemetry import trace  # noqa: PLC0415 — lazy by design (optional-extras isolation)
-
+        try:
+            from opentelemetry import trace  # noqa: PLC0415 — lazy by design (optional-extras isolation)
+        except ImportError:
+            # opentelemetry namespace exists but the api package is broken or missing —
+            # degrade to log-only emission. The structured log record above has already fired.
+            return
         trace.get_current_span().add_event(event_name, attributes=attributes)

{httpware-0.8.2 → httpware-0.8.4}/src/httpware/client.py

@@ -132,7 +132,7 @@ class AsyncClient:
             async with _httpx2_exception_mapper():
                 response = await self._httpx2_client.send(request)
         except RuntimeError as exc:
-            if "closed" in str(exc):
+            if self._httpx2_client.is_closed:
                 raise TransportError(str(exc)) from exc
             raise
         _raise_on_status_error(response)
@@ -850,7 +850,7 @@ class Client:
             with _httpx2_exception_mapper_sync():
                 response = self._httpx2_client.send(request)
         except RuntimeError as exc:
-            if "closed" in str(exc):
+            if self._httpx2_client.is_closed:
                 raise TransportError(str(exc)) from exc
             raise
         _raise_on_status_error(response)

{httpware-0.8.2 → httpware-0.8.4}/src/httpware/decoders/__init__.py

@@ -1,4 +1,4 @@
-"""ResponseDecoder protocol — the AsyncClient ↔ ResponseDecoder seam (Seam 3)."""
+"""ResponseDecoder protocol — the Client/AsyncClient ↔ ResponseDecoder seam (Seam B)."""
 
 from typing import Protocol, TypeVar, runtime_checkable
 

{httpware-0.8.2 → httpware-0.8.4}/src/httpware/middleware/resilience/budget.py

@@ -8,6 +8,7 @@ coroutines on one event loop, and across (sync Client, AsyncClient) pairs
 in the same process.
 """
 
+import math
 import threading
 import time
 from collections import deque
@@ -64,7 +65,7 @@ class RetryBudget:
         with self._lock:
             self._purge(now)
             floor = int(self._min_retries_per_sec * self._ttl)
-            ceiling = int(len(self._deposits) * self._percent_can_retry) + floor
+            ceiling = math.ceil(len(self._deposits) * self._percent_can_retry) + floor
             if len(self._withdrawn) >= ceiling:
                 return False
             self._withdrawn.append(now)

{httpware-0.8.2 → httpware-0.8.4}/src/httpware/middleware/resilience/retry.py

@@ -47,6 +47,9 @@ 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"
+_RETRY_AFTER_EXCEEDS_MAX_DELAY_NOTE = (
+    "httpware: Retry-After ({retry_after}s) exceeded max_delay ({max_delay}s); giving up"
+)
 
 _LOGGER = logging.getLogger("httpware.retry")
 
@@ -100,23 +103,19 @@ class AsyncRetry:
         last_exc: BaseException | None = None
         last_response: httpx2.Response | None = None
 
+        self.budget.deposit()
         for attempt in range(self.max_attempts):
             is_last = attempt + 1 >= self.max_attempts
-            self.budget.deposit()
             try:
                 return await next(request)
             except StatusError as exc:
                 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
@@ -185,8 +184,19 @@ class AsyncRetry:
                 if header is not None:
                     retry_after = _parse_retry_after(header)
 
+            if retry_after is not None and retry_after > self.max_delay:
+                if last_exc is None:  # pragma: no cover — retry_after requires last_response which requires last_exc
+                    msg = "AsyncRetry: retry_after path reached with no last_exc"
+                    raise AssertionError(msg)
+                last_exc.add_note(
+                    _RETRY_AFTER_EXCEEDS_MAX_DELAY_NOTE.format(
+                        retry_after=retry_after,
+                        max_delay=self.max_delay,
+                    ),
+                )
+                raise last_exc
             if retry_after is not None:
-                delay = min(retry_after, self.max_delay)
+                delay = retry_after
             else:
                 delay = full_jitter_delay(
                     attempt,
@@ -231,23 +241,19 @@ class Retry:
         last_exc: BaseException | None = None
         last_response: httpx2.Response | None = None
 
+        self.budget.deposit()
         for attempt in range(self.max_attempts):
             is_last = attempt + 1 >= self.max_attempts
-            self.budget.deposit()
             try:
                 return next(request)
             except StatusError as exc:
                 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
@@ -316,8 +322,19 @@ class Retry:
                 if header is not None:
                     retry_after = _parse_retry_after(header)
 
+            if retry_after is not None and retry_after > self.max_delay:
+                if last_exc is None:  # pragma: no cover — retry_after requires last_response which requires last_exc
+                    msg = "Retry: retry_after path reached with no last_exc"
+                    raise AssertionError(msg)
+                last_exc.add_note(
+                    _RETRY_AFTER_EXCEEDS_MAX_DELAY_NOTE.format(
+                        retry_after=retry_after,
+                        max_delay=self.max_delay,
+                    ),
+                )
+                raise last_exc
             if retry_after is not None:
-                delay = min(retry_after, self.max_delay)
+                delay = retry_after
             else:
                 delay = full_jitter_delay(
                     attempt,

httpware-0.8.2/src/httpware/_internal/import_checker.py

@@ -1,8 +0,0 @@
-"""Detect optional extras without importing them. Used by adapter modules to gate hard imports."""
-
-from importlib.util import find_spec
-
-
-is_msgspec_installed = find_spec("msgspec") is not None
-is_pydantic_installed = find_spec("pydantic") is not None
-is_otel_installed = find_spec("opentelemetry") is not None