clientwright 0.1.0__py3-none-any.whl

clientwright/adapters/httpx2/adapter.py

@@ -0,0 +1,37 @@
+"""The httpx2 adapter: the shared family builder bound to the httpx2 SDK.
+
+The class keeps the httpx adapter's name (``HttpxAdapter``) on purpose:
+public names in the paired adapters are identical, so migrating a service is
+one extra and one import path. The registry name is ``"httpx2"``.
+"""
+
+from __future__ import annotations
+
+from .._httpx_shared import FamilyAdapter
+from ._imports import httpx2
+from .capabilities import CAPABILITIES
+from .errors import translate_call_error
+from .normalize import AsyncHttpxNormalizer
+from .normalize_sync import SyncHttpxNormalizer
+from .transport import (
+    AsyncEngineTransport,
+    AsyncProxyRouterTransport,
+    SyncEngineTransport,
+    SyncProxyRouterTransport,
+)
+
+
+class HttpxAdapter(FamilyAdapter):
+    name = "httpx2"
+    capabilities = CAPABILITIES
+    sdk = httpx2
+    async_normalizer = AsyncHttpxNormalizer
+    sync_normalizer = SyncHttpxNormalizer
+    async_engine_transport = AsyncEngineTransport
+    sync_engine_transport = SyncEngineTransport
+    async_proxy_router = AsyncProxyRouterTransport
+    sync_proxy_router = SyncProxyRouterTransport
+    translate = staticmethod(translate_call_error)
+
+
+__all__ = ["HttpxAdapter"]

clientwright/adapters/httpx2/capabilities.py

@@ -0,0 +1,9 @@
+"""httpx2 capability declaration. Zero-dependency: never imports httpx2."""
+
+from __future__ import annotations
+
+from .._httpx_shared import capabilities_for
+
+CAPABILITIES = capabilities_for("httpx2")
+
+__all__ = ["CAPABILITIES"]

clientwright/adapters/httpx2/classify.py

@@ -0,0 +1,14 @@
+"""httpx2 exception -> FailureKind classification (shared family logic)."""
+
+from __future__ import annotations
+
+from ...core.model import FailureKind
+from .._httpx_shared import classify_family_error
+from ._imports import httpx2
+
+
+def classify_error(exc: BaseException) -> FailureKind:
+    return classify_family_error(httpx2, exc)
+
+
+__all__ = ["classify_error"]

clientwright/adapters/httpx2/errors.py

@@ -0,0 +1,36 @@
+"""Kernel errors dual-inherited into the httpx2 family.
+
+A user's ``except httpx2.HTTPError`` (or ``except httpx2.TimeoutException``)
+keeps working when clientwright raises on its own authority. Class names
+mirror the httpx adapter on purpose.
+"""
+
+from __future__ import annotations
+
+from ...core.errors import CircuitOpenError, DeadlineExceededError, TooManyRedirectsError
+from .._httpx_shared import make_error_translator
+from ._imports import httpx2
+
+
+class HttpxCircuitOpenError(CircuitOpenError, httpx2.HTTPError):
+    """Circuit open, catchable as httpx2.HTTPError."""
+
+
+class HttpxDeadlineExceededError(DeadlineExceededError, httpx2.TimeoutException):
+    """Total deadline exhausted, catchable as httpx2.TimeoutException."""
+
+
+class HttpxTooManyRedirectsError(TooManyRedirectsError, httpx2.TooManyRedirects):
+    """Owned redirect limit exceeded, catchable as httpx2.TooManyRedirects."""
+
+
+translate_call_error = make_error_translator(
+    HttpxCircuitOpenError, HttpxDeadlineExceededError, HttpxTooManyRedirectsError
+)
+
+__all__ = [
+    "HttpxCircuitOpenError",
+    "HttpxDeadlineExceededError",
+    "HttpxTooManyRedirectsError",
+    "translate_call_error",
+]

clientwright/adapters/httpx2/normalize.py

@@ -0,0 +1,27 @@
+"""Async normalizer binding: shared family logic over the httpx2 SDK."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from .._httpx_shared import AsyncFamilyNormalizer, AsyncTimedStreamMixin
+from ._imports import httpx2
+from .views import HttpxRequestView
+
+
+class _TimedAsyncStream(AsyncTimedStreamMixin, httpx2.AsyncByteStream):
+    """Times body consumption and reports read failures exactly once."""
+
+
+class AsyncHttpxNormalizer(AsyncFamilyNormalizer):
+    def __init__(self, default_timeout: dict[str, float | None], clock: Callable[[], float]) -> None:
+        super().__init__(
+            default_timeout,
+            clock,
+            sdk=httpx2,
+            request_view=lambda native: HttpxRequestView(native, default_timeout),
+            timed_stream=_TimedAsyncStream,
+        )
+
+
+__all__ = ["AsyncHttpxNormalizer"]

clientwright/adapters/httpx2/normalize_sync.py

@@ -0,0 +1,27 @@
+"""Sync normalizer binding: same contract, blocking body operations."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from .._httpx_shared import SyncFamilyNormalizer, SyncTimedStreamMixin
+from ._imports import httpx2
+from .views import HttpxRequestView
+
+
+class _TimedSyncStream(SyncTimedStreamMixin, httpx2.SyncByteStream):
+    """Times body consumption and reports read failures exactly once."""
+
+
+class SyncHttpxNormalizer(SyncFamilyNormalizer):
+    def __init__(self, default_timeout: dict[str, float | None], clock: Callable[[], float]) -> None:
+        super().__init__(
+            default_timeout,
+            clock,
+            sdk=httpx2,
+            request_view=lambda native: HttpxRequestView(native, default_timeout),
+            timed_stream=_TimedSyncStream,
+        )
+
+
+__all__ = ["SyncHttpxNormalizer"]

clientwright/adapters/httpx2/transport.py

@@ -0,0 +1,35 @@
+"""Engine-driven httpx2 transports: shared mixin logic bound to httpx2 bases."""
+
+from __future__ import annotations
+
+from .._httpx_shared import (
+    AsyncEngineTransportMixin,
+    AsyncProxyRouterMixin,
+    SyncEngineTransportMixin,
+    SyncProxyRouterMixin,
+)
+from ._imports import httpx2
+
+
+class AsyncEngineTransport(AsyncEngineTransportMixin, httpx2.AsyncBaseTransport):
+    pass
+
+
+class SyncEngineTransport(SyncEngineTransportMixin, httpx2.BaseTransport):
+    pass
+
+
+class AsyncProxyRouterTransport(AsyncProxyRouterMixin, httpx2.AsyncBaseTransport):
+    pass
+
+
+class SyncProxyRouterTransport(SyncProxyRouterMixin, httpx2.BaseTransport):
+    pass
+
+
+__all__ = [
+    "AsyncEngineTransport",
+    "AsyncProxyRouterTransport",
+    "SyncEngineTransport",
+    "SyncProxyRouterTransport",
+]

clientwright/adapters/httpx2/views.py

@@ -0,0 +1,45 @@
+"""RequestView/ResponseView bindings over httpx2 objects.
+
+Same names as the httpx adapter on purpose: migrating a service is one extra
+and one import path.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator
+
+from .._httpx_shared import IDEMPOTENT_EXTENSION, ROUTE_EXTENSION, FamilyRequestView, FamilyResponseView
+from ._imports import httpx2
+
+
+class _ReplayStream(httpx2.SyncByteStream, httpx2.AsyncByteStream):
+    """A byte stream that can be iterated any number of times."""
+
+    def __init__(self, content: bytes) -> None:
+        self._content = content
+
+    def __iter__(self) -> Iterator[bytes]:
+        yield self._content
+
+    async def __aiter__(self) -> AsyncIterator[bytes]:
+        yield self._content
+
+
+class HttpxRequestView(FamilyRequestView):
+    __slots__ = ()
+
+    def __init__(self, request: httpx2.Request, default_timeout: dict[str, float | None]) -> None:
+        super().__init__(request, default_timeout, sdk=httpx2, replay_stream=_ReplayStream)
+
+
+class HttpxResponseView(FamilyResponseView):
+    __slots__ = ()
+
+
+__all__ = [
+    "IDEMPOTENT_EXTENSION",
+    "ROUTE_EXTENSION",
+    "HttpxRequestView",
+    "HttpxResponseView",
+    "_ReplayStream",
+]

clientwright/adapters/observability/__init__.py

@@ -0,0 +1,26 @@
+"""Observability backends behind extras; the core records via protocols only.
+
+Attribute access is lazy so this package imports cleanly with no extras
+installed; touching a backend without its extra raises the backend's own
+install-hint ImportError.
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from .._lazy import lazy_attribute
+
+if TYPE_CHECKING:
+    from ._metrics.prometheus import PrometheusClientMetrics as PrometheusClientMetrics
+    from ._tracing.otel import OpenTelemetryTracer as OpenTelemetryTracer
+
+_EXPORTS = {
+    "OpenTelemetryTracer": "_tracing.otel",
+    "PrometheusClientMetrics": "_metrics.prometheus",
+}
+
+
+def __getattr__(name: str) -> Any:
+    return lazy_attribute(__name__, globals(), _EXPORTS, name)
+
+
+__all__ = ["OpenTelemetryTracer", "PrometheusClientMetrics"]

clientwright/adapters/observability/_metrics/__init__.py

@@ -0,0 +1 @@
+"""Metrics backends."""

clientwright/adapters/observability/_metrics/prometheus.py

@@ -0,0 +1,200 @@
+"""Prometheus backend for the frozen ``http_client_*`` metric families.
+
+Instances are cached per (prefix, registry): repeated construction returns the
+same object instead of raising Prometheus duplicate-registration errors - the
+same guarantee the legacy ``MetricsMeta`` singleton gave.
+"""
+
+from __future__ import annotations
+
+import re
+import threading
+import weakref
+from typing import Any
+
+try:
+    from prometheus_client import REGISTRY, Counter, Gauge, Histogram
+    from prometheus_client.registry import CollectorRegistry
+except ImportError as exc:  # pragma: no cover - exercised only without the extra
+    raise ImportError("Prometheus metrics require clientwright[metrics]; install it.") from exc
+
+from ....core.telemetry import names
+
+_PREFIX_PATTERN = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+
+# Keyed by the registry OBJECT (weakly): id() of a dead registry can be
+# recycled, which would hand back a sink bound to the wrong registry.
+_INSTANCES: weakref.WeakKeyDictionary[CollectorRegistry, dict[str | None, PrometheusClientMetrics]] = (
+    weakref.WeakKeyDictionary()
+)
+_INSTANCES_LOCK = threading.Lock()
+
+
+def _metric_name(name: str, prefix: str | None) -> str:
+    if prefix is None:
+        return name
+    if not _PREFIX_PATTERN.match(prefix):
+        raise ValueError(f"Invalid metric prefix {prefix!r}: must match {_PREFIX_PATTERN.pattern}")
+    return f"{prefix}_{name}"
+
+
+class PrometheusClientMetrics:
+    """ClientMetricsProtocol backend over prometheus-client."""
+
+    def __new__(
+        cls,
+        prefix: str | None = None,
+        registry: CollectorRegistry = REGISTRY,
+        buckets: tuple[float, ...] = names.DEFAULT_BUCKETS,
+    ) -> PrometheusClientMetrics:
+        with _INSTANCES_LOCK:
+            per_registry = _INSTANCES.get(registry)
+            if per_registry is None:
+                per_registry = {}
+                _INSTANCES[registry] = per_registry
+            instance = per_registry.get(prefix)
+            if instance is None:
+                instance = super().__new__(cls)
+                instance._init(prefix, registry, buckets)
+                per_registry[prefix] = instance
+            return instance
+
+    def _init(self, prefix: str | None, registry: CollectorRegistry, buckets: tuple[float, ...]) -> None:
+        self._requests_total = Counter(
+            _metric_name(names.REQUESTS_TOTAL, prefix),
+            "Total number of outbound HTTP client calls",
+            names.LABELS_CALL,
+            registry=registry,
+        )
+        self._request_duration = Histogram(
+            _metric_name(names.REQUEST_DURATION, prefix),
+            "HTTP client call duration in seconds (boundary declared per adapter)",
+            names.LABELS_DURATION,
+            registry=registry,
+            buckets=list(buckets),
+        )
+        self._body_duration = Histogram(
+            _metric_name(names.BODY_DURATION, prefix),
+            "HTTP client response body read duration in seconds",
+            names.LABELS_DURATION,
+            registry=registry,
+            buckets=list(buckets),
+        )
+        self._attempts_total = Counter(
+            _metric_name(names.ATTEMPTS_TOTAL, prefix),
+            "Total number of physical attempts",
+            names.LABELS_ATTEMPT,
+            registry=registry,
+        )
+        self._attempt_duration = Histogram(
+            _metric_name(names.ATTEMPT_DURATION, prefix),
+            "Physical attempt duration in seconds",
+            names.LABELS_ATTEMPT,
+            registry=registry,
+            buckets=list(buckets),
+        )
+        self._inflight = Gauge(
+            _metric_name(names.INFLIGHT, prefix),
+            "Number of in-flight HTTP client calls",
+            names.LABELS_INFLIGHT,
+            registry=registry,
+        )
+        self._circuit_state = Gauge(
+            _metric_name(names.CIRCUIT_STATE, prefix),
+            "Circuit state per key: 0 closed, 1 half-open, 2 open",
+            names.LABELS_CIRCUIT,
+            registry=registry,
+        )
+        self._redirect_hops = Counter(
+            _metric_name(names.REDIRECT_HOPS_TOTAL, prefix),
+            "Redirect hops followed by the engine",
+            names.LABELS_SEAM,
+            registry=registry,
+        )
+        self._retry_skipped = Counter(
+            _metric_name(names.RETRY_SKIPPED_TOTAL, prefix),
+            "Retries the policy wanted but could not perform",
+            names.LABELS_RETRY_SKIPPED,
+            registry=registry,
+        )
+        self._uninstrumented = Counter(
+            _metric_name(names.UNINSTRUMENTED_CALLS_TOTAL, prefix),
+            "Calls that bypassed the instrumentation seam",
+            names.LABELS_SEAM,
+            registry=registry,
+        )
+
+    _STATE_VALUES = {"closed": 0, "half_open": 1, "open": 2}
+
+    def record_call(
+        self,
+        *,
+        service: str,
+        adapter: str,
+        seam: str,
+        method: str,
+        origin: str,
+        route: str,
+        status: str,
+        outcome: str,
+        duration: float,
+    ) -> None:
+        self._requests_total.labels(service, adapter, seam, method, origin, route, status, outcome).inc()
+        self._request_duration.labels(service, adapter, seam, method, origin, route).observe(duration)
+
+    def record_body_duration(
+        self,
+        *,
+        service: str,
+        adapter: str,
+        seam: str,
+        method: str,
+        origin: str,
+        route: str,
+        duration: float,
+    ) -> None:
+        self._body_duration.labels(service, adapter, seam, method, origin, route).observe(duration)
+
+    def record_attempt(
+        self,
+        *,
+        service: str,
+        adapter: str,
+        seam: str,
+        method: str,
+        origin: str,
+        outcome: str,
+        duration: float,
+    ) -> None:
+        self._attempts_total.labels(service, adapter, seam, method, origin, outcome).inc()
+        self._attempt_duration.labels(service, adapter, seam, method, origin, outcome).observe(duration)
+
+    def inflight_delta(self, *, service: str, adapter: str, seam: str, origin: str, delta: int) -> None:
+        gauge = self._inflight.labels(service, adapter, seam, origin)
+        if delta > 0:
+            gauge.inc(float(delta))
+        elif delta < 0:
+            gauge.dec(float(abs(delta)))
+
+    def record_circuit_state(self, *, service: str, adapter: str, key: str, state: str) -> None:
+        self._circuit_state.labels(service, adapter, key).set(self._STATE_VALUES.get(state, 0))
+
+    def record_redirect_hop(self, *, service: str, adapter: str, seam: str) -> None:
+        self._redirect_hops.labels(service, adapter, seam).inc()
+
+    def record_retry_skipped(self, *, service: str, adapter: str, seam: str, reason: str) -> None:
+        self._retry_skipped.labels(service, adapter, seam, reason).inc()
+
+    def record_uninstrumented_call(self, *, service: str, adapter: str, seam: str) -> None:
+        self._uninstrumented.labels(service, adapter, seam).inc()
+
+
+def get_client_metrics(
+    prefix: str | None = None,
+    registry: Any = REGISTRY,
+    buckets: tuple[float, ...] | None = None,
+) -> PrometheusClientMetrics:
+    return PrometheusClientMetrics(prefix, registry, buckets or names.DEFAULT_BUCKETS)
+
+
+__all__ = ["PrometheusClientMetrics", "get_client_metrics"]

clientwright/adapters/observability/_tracing/__init__.py

@@ -0,0 +1,3 @@
+"""Tracing backends behind the ``[tracing]`` extra."""
+
+__all__: list[str] = []

clientwright/adapters/observability/_tracing/otel.py

@@ -0,0 +1,61 @@
+"""OpenTelemetry backend for the SDK-free tracer protocol.
+
+The client span is attached to the ambient context for its lifetime, so
+``inject_context`` propagates THIS span to the server (not merely the parent),
+and any spans the server links to point at the client call. Attach and detach
+happen in the same task: the engine opens the span and ends it in a finally
+block without crossing task boundaries.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, MutableMapping
+
+try:
+    from opentelemetry import context as otel_context
+    from opentelemetry import propagate, trace
+    from opentelemetry.trace import SpanKind, Status, StatusCode, set_span_in_context
+except ImportError as exc:  # pragma: no cover - exercised only without the extra
+    raise ImportError("OpenTelemetry tracing requires clientwright[tracing]; install it.") from exc
+
+
+class OpenTelemetrySpan:
+    """SpanProtocol backend over an OTel span attached to the current context."""
+
+    __slots__ = ("_span", "_token")
+
+    def __init__(self, span: trace.Span, token: object) -> None:
+        self._span = span
+        self._token = token
+
+    def set_attribute(self, key: str, value: str | int | float | bool) -> None:
+        self._span.set_attribute(key, value)
+
+    def record_failure(self, description: str) -> None:
+        self._span.set_status(Status(StatusCode.ERROR, description))
+
+    def end(self) -> None:
+        try:
+            otel_context.detach(self._token)  # type: ignore[arg-type]
+        finally:
+            self._span.end()
+
+
+class OpenTelemetryTracer:
+    """TracerProtocol backend over opentelemetry-api."""
+
+    __slots__ = ("_tracer",)
+
+    def __init__(self, tracer_provider: trace.TracerProvider | None = None) -> None:
+        self._tracer = trace.get_tracer("clientwright", tracer_provider=tracer_provider)
+
+    def start_span(self, name: str, *, attributes: Mapping[str, str | int | float | bool]) -> OpenTelemetrySpan:
+        span = self._tracer.start_span(name, kind=SpanKind.CLIENT, attributes=dict(attributes))
+        token = otel_context.attach(set_span_in_context(span))
+        return OpenTelemetrySpan(span, token)
+
+    def inject_context(self, headers: MutableMapping[str, str]) -> None:
+        propagate.inject(headers)
+
+
+__all__ = ["OpenTelemetrySpan", "OpenTelemetryTracer"]

clientwright/adapters/requests/__init__.py

@@ -0,0 +1,45 @@
+"""requests adapter (``[requests]`` extra): real Session, engine underneath.
+
+SDK-backed names resolve lazily (see ``clientwright.adapters._lazy``): importing
+this package never imports requests, so the capabilities matrix stays
+extras-free. The per-call channel comes from the zero-dependency core and is
+therefore eager.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ...core.options import CallOptions as CallOptions
+from ...core.options import call_options as call_options
+from .._lazy import lazy_attribute
+
+if TYPE_CHECKING:
+    from .adapter import RequestsAdapter as RequestsAdapter
+    from .capabilities import CAPABILITIES as CAPABILITIES
+    from .errors import RequestsCircuitOpenError as RequestsCircuitOpenError
+    from .errors import RequestsDeadlineExceededError as RequestsDeadlineExceededError
+    from .errors import RequestsTooManyRedirectsError as RequestsTooManyRedirectsError
+
+_EXPORTS = {
+    "CAPABILITIES": "capabilities",
+    "RequestsAdapter": "adapter",
+    "RequestsCircuitOpenError": "errors",
+    "RequestsDeadlineExceededError": "errors",
+    "RequestsTooManyRedirectsError": "errors",
+}
+
+
+def __getattr__(name: str) -> Any:
+    return lazy_attribute(__name__, globals(), _EXPORTS, name)
+
+
+__all__ = [
+    "CAPABILITIES",
+    "CallOptions",
+    "RequestsAdapter",
+    "RequestsCircuitOpenError",
+    "RequestsDeadlineExceededError",
+    "RequestsTooManyRedirectsError",
+    "call_options",
+]

clientwright/adapters/requests/_imports.py

@@ -0,0 +1,21 @@
+"""Lazy import guard for the optional requests stack.
+
+Importing this module fails with a friendly message when the ``requests``
+extra is not installed. Every requests submodule imports its third-party
+symbols from here. urllib3 is re-exported too: requests depends on it, and the
+classifier needs the underlying exception types to tell a mid-stream
+disconnect from a refused connection.
+"""
+
+from __future__ import annotations
+
+_INSTALL_HINT = "requests support requires clientwright[requests]; install it."
+
+try:
+    import requests
+    import urllib3
+    from requests.adapters import HTTPAdapter
+except ImportError as exc:  # pragma: no cover - exercised only without the extra
+    raise ImportError(_INSTALL_HINT) from exc
+
+__all__ = ["HTTPAdapter", "requests", "urllib3"]