httpware 0.5.0__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: httpware
-Version: 0.5.0
+Version: 0.7.0
 Summary: Resilience-first async HTTP client framework for Python
 Keywords: http,async,client,resilience,retry,circuit-breaker,middleware,httpx,pydantic
 Author: Artur Shiriev
@@ -15,14 +15,16 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Framework :: AsyncIO
 Requires-Dist: httpx2>=2.0.0,<3.0
-Requires-Dist: httpware[pydantic,msgspec] ; extra == 'all'
+Requires-Dist: httpware[pydantic,msgspec,otel] ; extra == 'all'
 Requires-Dist: msgspec>=0.18 ; extra == 'msgspec'
+Requires-Dist: opentelemetry-api>=1.20 ; extra == 'otel'
 Requires-Dist: pydantic>=2.0,<3.0 ; extra == 'pydantic'
 Requires-Python: >=3.11, <4
 Project-URL: repository, https://github.com/modern-python/httpware
 Project-URL: docs, https://httpware.readthedocs.io
 Provides-Extra: all
 Provides-Extra: msgspec
+Provides-Extra: otel
 Provides-Extra: pydantic
 Description-Content-Type: text/markdown
 
@@ -37,7 +39,7 @@ Description-Content-Type: text/markdown
 
 `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`.
 
-> **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0. Streaming and observability are not yet shipped.
+> **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0.
 
 ## Install
 
@@ -45,7 +47,7 @@ Description-Content-Type: text/markdown
 pip install httpware                # core only — no decoder
 pip install httpware[pydantic]      # + PydanticDecoder (the default-decoder path)
 pip install httpware[msgspec]       # + MsgspecDecoder
-pip install httpware[all]           # everything declared above (pydantic, msgspec)
+pip install httpware[all]           # everything declared above (pydantic, msgspec, otel)
 ```
 
 `AsyncClient()` with no `decoder=` argument defaults to constructing a `PydanticDecoder`; that path requires the `pydantic` extra and raises `ImportError` at `AsyncClient.__init__` if it is missing.
@@ -89,6 +91,8 @@ async def main() -> None:
         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:
@@ -112,6 +116,28 @@ It does NOT pass through the middleware chain: `Retry`, `Bulkhead`, and any cust
 
 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`.
 
+## Observability
+
+`Retry` and `Bulkhead` 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.
+
+```python
+import logging
+
+# Enable visibility into retry / bulkhead operational events
+logging.getLogger("httpware.retry").setLevel(logging.WARNING)
+logging.getLogger("httpware.bulkhead").setLevel(logging.WARNING)
+```
+
+For OTel attribute enrichment on the active span — install the extra:
+
+```bash
+pip install httpware[otel]
+```
+
+When installed, `_emit_event` calls `trace.get_current_span().add_event(name, attributes=...)` automatically. We never create our own spans; for HTTP-level tracing install `opentelemetry-instrumentation-httpx` separately.
+
 ## 🗒️ [Release notes](https://github.com/modern-python/httpware/releases)
 
 ## 📦 [PyPI](https://pypi.org/project/httpware)

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

@@ -9,7 +9,7 @@
 
 `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`.
 
-> **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0. Streaming and observability are not yet shipped.
+> **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0.
 
 ## Install
 
@@ -17,7 +17,7 @@
 pip install httpware                # core only — no decoder
 pip install httpware[pydantic]      # + PydanticDecoder (the default-decoder path)
 pip install httpware[msgspec]       # + MsgspecDecoder
-pip install httpware[all]           # everything declared above (pydantic, msgspec)
+pip install httpware[all]           # everything declared above (pydantic, msgspec, otel)
 ```
 
 `AsyncClient()` with no `decoder=` argument defaults to constructing a `PydanticDecoder`; that path requires the `pydantic` extra and raises `ImportError` at `AsyncClient.__init__` if it is missing.
@@ -61,6 +61,8 @@ async def main() -> None:
         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:
@@ -84,6 +86,28 @@ It does NOT pass through the middleware chain: `Retry`, `Bulkhead`, and any cust
 
 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`.
 
+## Observability
+
+`Retry` and `Bulkhead` 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.
+
+```python
+import logging
+
+# Enable visibility into retry / bulkhead operational events
+logging.getLogger("httpware.retry").setLevel(logging.WARNING)
+logging.getLogger("httpware.bulkhead").setLevel(logging.WARNING)
+```
+
+For OTel attribute enrichment on the active span — install the extra:
+
+```bash
+pip install httpware[otel]
+```
+
+When installed, `_emit_event` calls `trace.get_current_span().add_event(name, attributes=...)` automatically. We never create our own spans; for HTTP-level tracing install `opentelemetry-instrumentation-httpx` separately.
+
 ## 🗒️ [Release notes](https://github.com/modern-python/httpware/releases)
 
 ## 📦 [PyPI](https://pypi.org/project/httpware)

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

@@ -26,7 +26,7 @@ classifiers = [
     "Topic :: Internet :: WWW/HTTP",
     "Framework :: AsyncIO",
 ]
-version = "0.5.0"
+version = "0.7.0"
 dependencies = [
     "httpx2>=2.0.0,<3.0",
 ]
@@ -34,7 +34,8 @@ dependencies = [
 [project.optional-dependencies]
 pydantic = ["pydantic>=2.0,<3.0"]
 msgspec = ["msgspec>=0.18"]
-all = ["httpware[pydantic,msgspec]"]
+otel = ["opentelemetry-api>=1.20"]
+all = ["httpware[pydantic,msgspec,otel]"]
 
 [project.urls]
 repository = "https://github.com/modern-python/httpware"

{httpware-0.5.0 → httpware-0.7.0}/src/httpware/_internal/import_checker.py

@@ -5,3 +5,4 @@ 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

httpware-0.7.0/src/httpware/_internal/observability.py

@@ -0,0 +1,42 @@
+"""Observability emission helper — structured logging + opt-in OpenTelemetry span events.
+
+See planning/specs/2026-06-05-observability-design.md for the contract.
+
+Logger names (``httpware.retry``, ``httpware.bulkhead``) and event names
+(``retry.giving_up``, ``bulkhead.rejected``, etc.) are the public observability
+surface. They are stable: renames are breaking changes.
+"""
+
+import logging
+import typing
+
+from httpware._internal import import_checker
+
+
+def _emit_event(
+    logger: logging.Logger,
+    event_name: str,
+    *,
+    level: int,
+    message: str,
+    attributes: dict[str, typing.Any],
+) -> None:
+    """Emit one observability event to both channels.
+
+    1. Always emits a structured log record at ``level`` with ``extra=attributes``
+       (so log aggregators that index ``extra`` see structured fields).
+    2. If ``opentelemetry-api`` is installed, calls
+       ``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.
+
+    The lazy ``from opentelemetry import trace`` inside the if-block preserves
+    the optional-extras isolation invariant: ``import httpware`` must not pull
+    ``opentelemetry`` into ``sys.modules`` when the extra is absent.
+    """
+    logger.log(level, message, extra=attributes)
+    if import_checker.is_otel_installed:
+        from opentelemetry import trace  # noqa: PLC0415 — lazy by design (optional-extras isolation)
+
+        trace.get_current_span().add_event(event_name, attributes=attributes)

{httpware-0.5.0 → httpware-0.7.0}/src/httpware/middleware/resilience/bulkhead.py

@@ -12,9 +12,11 @@ AsyncClient(middleware=[shared]) calls to enforce a joint cap across clients.
 """
 
 import asyncio
+import logging
 
 import httpx2
 
+from httpware._internal.observability import _emit_event
 from httpware.errors import BulkheadFullError
 from httpware.middleware import Next
 
@@ -22,6 +24,8 @@ from httpware.middleware import Next
 _MAX_CONCURRENT_INVALID = "max_concurrent must be >= 1"
 _ACQUIRE_TIMEOUT_INVALID = "acquire_timeout must be >= 0"
 
+_LOGGER = logging.getLogger("httpware.bulkhead")
+
 
 class Bulkhead:
     """Concurrency limiter middleware backed by ``asyncio.Semaphore``.
@@ -64,6 +68,18 @@ class Bulkhead:
                 async with asyncio.timeout(self._acquire_timeout):
                     await self._sem.acquire()
         except TimeoutError as exc:
+            _emit_event(
+                _LOGGER,
+                "bulkhead.rejected",
+                level=logging.WARNING,
+                message="bulkhead rejected request — acquire_timeout exceeded",
+                attributes={
+                    "max_concurrent": self._max_concurrent,
+                    "acquire_timeout": self._acquire_timeout,
+                    "method": request.method,
+                    "url": str(request.url),
+                },
+            )
             raise BulkheadFullError(
                 max_concurrent=self._max_concurrent,
                 acquire_timeout=self._acquire_timeout,

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

@@ -11,11 +11,13 @@ import asyncio
 import builtins
 import datetime
 import email.utils
+import logging
 from collections.abc import Awaitable, Callable
 from http import HTTPStatus
 
 import httpx2
 
+from httpware._internal.observability import _emit_event
 from httpware.client import STREAMING_BODY_MARKER
 from httpware.errors import NetworkError, RetryBudgetExhaustedError, StatusError, TimeoutError  # noqa: A004
 from httpware.middleware import Next
@@ -46,6 +48,8 @@ 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"
 
+_LOGGER = logging.getLogger("httpware.retry")
+
 
 def _parse_retry_after(value: str) -> float | None:
     """Parse a Retry-After header value. Returns None on malformed input."""
@@ -138,6 +142,17 @@ class Retry:
                     msg = "Retry: streaming-body refusal reached with no last_exc"
                     raise AssertionError(msg)
                 last_exc.add_note(_STREAMING_BODY_REFUSAL_NOTE)
+                _emit_event(
+                    _LOGGER,
+                    "retry.streaming_refused",
+                    level=logging.WARNING,
+                    message="retry refused — request body is a stream that cannot replay",
+                    attributes={
+                        "method": request.method,
+                        "url": str(request.url),
+                        "last_exception_type": type(last_exc).__qualname__,
+                    },
+                )
                 raise last_exc
 
             if is_last:
@@ -145,9 +160,34 @@ class Retry:
                     msg = "Retry: last_exc unset on final attempt — unreachable"
                     raise AssertionError(msg)
                 last_exc.add_note(f"httpware: gave up after {attempt + 1} attempts")
+                _emit_event(
+                    _LOGGER,
+                    "retry.giving_up",
+                    level=logging.WARNING,
+                    message=f"retry gave up after {attempt + 1} attempts",
+                    attributes={
+                        "attempts": attempt + 1,
+                        "method": request.method,
+                        "url": str(request.url),
+                        "last_status": last_response.status_code if last_response is not None else None,
+                        "last_exception_type": type(last_exc).__qualname__,
+                    },
+                )
                 raise last_exc
 
             if not self.budget.try_withdraw():
+                _emit_event(
+                    _LOGGER,
+                    "retry.budget_refused",
+                    level=logging.WARNING,
+                    message=f"retry budget refused after {attempt + 1} attempts",
+                    attributes={
+                        "attempts": attempt + 1,
+                        "method": request.method,
+                        "url": str(request.url),
+                        "last_status": last_response.status_code if last_response is not None else None,
+                    },
+                )
                 raise RetryBudgetExhaustedError(
                     last_response=last_response,
                     last_exception=last_exc,