clientwright 0.1.0__py3-none-any.whl

clientwright/adapters/aiohttp/normalize.py

@@ -0,0 +1,64 @@
+"""Async normalizer: the whole aiohttp-specific contract for the async engine."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+from ...core.contracts.message import RequestView, ResponseView
+from ...core.engine.base import default_response_outcome
+from ...core.model import ConnMetrics, FailureKind, Outcome
+from ._imports import aiohttp
+from .classify import classify_error
+from .trace import current_conn_metrics
+from .views import AiohttpRequestView, AiohttpResponseView
+
+
+class AsyncAiohttpNormalizer:
+    def wrap_request(self, native: Any) -> AiohttpRequestView:
+        return AiohttpRequestView(native)
+
+    def wrap_response(self, native: Any) -> AiohttpResponseView:
+        return AiohttpResponseView(native)
+
+    def classify_error(self, exc: BaseException) -> FailureKind:
+        return classify_error(exc)
+
+    def classify_response(self, response: ResponseView) -> Outcome:
+        return default_response_outcome(response)
+
+    async def freeze(self, request: RequestView) -> bool:
+        """Bytes-backed payloads replay for free; streams and files do not."""
+        body = request.native.body
+        if body is None:
+            return True
+        if isinstance(body, (bytes, bytearray, memoryview)):
+            return True
+        if isinstance(body, aiohttp.payload.BytesPayload):
+            return not bool(getattr(body, "consumed", False))
+        return False
+
+    async def rewind(self, request: RequestView) -> None:
+        # BytesPayload re-emits its full content on every send; nothing to do.
+        return None
+
+    async def discard(self, response: ResponseView) -> None:
+        """MANDATORY before a repeat - otherwise the connection never returns to the pool."""
+        try:
+            result = response.native.release()
+            if inspect.isawaitable(result):
+                await result
+        except Exception:
+            return None
+
+    def wrap_stream(self, response: ResponseView, on_done: Callable[[Outcome, float], None]) -> None:
+        # The middleware returns at headers; the body streams outside the seam.
+        # Declared in capabilities (note "body_duration"), not silently skipped.
+        return None
+
+    def conn_metrics(self, response: ResponseView) -> ConnMetrics | None:
+        return current_conn_metrics()
+
+
+__all__ = ["AsyncAiohttpNormalizer"]

clientwright/adapters/aiohttp/options.py

@@ -0,0 +1,16 @@
+"""Per-call options channel for aiohttp.
+
+aiohttp has no analogue of ``httpx.Request.extensions``: nothing the caller
+passes to ``session.get(...)`` reaches a middleware. The route template and
+idempotency override therefore travel through the shared core ContextVar
+channel; this module re-exports it under the adapter's public path.
+
+    with call_options(route="/users/{id}", idempotent=True):
+        await session.post(f"/users/{user_id}")
+"""
+
+from __future__ import annotations
+
+from ...core.options import CallOptions, call_options, current_call_options
+
+__all__ = ["CallOptions", "call_options", "current_call_options"]

clientwright/adapters/aiohttp/trace.py

@@ -0,0 +1,109 @@
+"""TraceConfig: the observability that survives a bypassed middleware.
+
+Per-request ``middlewares=()`` REPLACES session middlewares - the official
+cookbook even teaches the pattern - but ``trace_configs`` cannot be overridden
+per request. Two things therefore live here and only here:
+
+- the ``uninstrumented_calls_total`` sentinel: a request that starts while the
+  engine middleware is NOT on the stack has bypassed every policy and metric;
+- connection-level timings (DNS, connect, pool wait, connection reuse) that no
+  middleware can see.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from contextvars import ContextVar
+from dataclasses import dataclass
+from types import SimpleNamespace
+from typing import Any
+
+from ...core.model import ConnMetrics
+from ...core.telemetry.emitter import ClientTelemetry
+from ._imports import aiohttp
+
+# True while the engine middleware is running in this task; TraceConfig reads
+# it to detect requests that bypassed the seam.
+ENGINE_ACTIVE: ContextVar[bool] = ContextVar("clientwright_aiohttp_engine_active", default=False)
+
+
+@dataclass(slots=True)
+class _ConnTrace:
+    dns_started: float | None = None
+    dns: float | None = None
+    connect_started: float | None = None
+    connect: float | None = None
+    queued_started: float | None = None
+    pool_wait: float | None = None
+    reused: bool | None = None
+
+
+# Trace callbacks run in the requesting task, so a plain ContextVar correlates
+# them with the response the normalizer later reads conn metrics for.
+_CONN_TRACE: ContextVar[_ConnTrace | None] = ContextVar("clientwright_aiohttp_conn_trace", default=None)
+
+
+def current_conn_metrics() -> ConnMetrics | None:
+    trace = _CONN_TRACE.get()
+    if trace is None:
+        return None
+    return ConnMetrics(dns=trace.dns, connect=trace.connect, pool_wait=trace.pool_wait, reused=trace.reused)
+
+
+def build_trace_config(telemetry: ClientTelemetry, clock: Callable[[], float]) -> aiohttp.TraceConfig:
+    trace_config = aiohttp.TraceConfig()
+
+    async def on_request_start(session: aiohttp.ClientSession, ctx: SimpleNamespace, params: Any) -> None:
+        if not ENGINE_ACTIVE.get():
+            telemetry.uninstrumented_call()
+        _CONN_TRACE.set(_ConnTrace())
+
+    async def on_dns_start(session: aiohttp.ClientSession, ctx: SimpleNamespace, params: Any) -> None:
+        trace = _CONN_TRACE.get()
+        if trace is not None:
+            trace.dns_started = clock()
+
+    async def on_dns_end(session: aiohttp.ClientSession, ctx: SimpleNamespace, params: Any) -> None:
+        trace = _CONN_TRACE.get()
+        if trace is not None and trace.dns_started is not None:
+            trace.dns = clock() - trace.dns_started
+
+    async def on_connect_start(session: aiohttp.ClientSession, ctx: SimpleNamespace, params: Any) -> None:
+        trace = _CONN_TRACE.get()
+        if trace is not None:
+            trace.connect_started = clock()
+
+    async def on_connect_end(session: aiohttp.ClientSession, ctx: SimpleNamespace, params: Any) -> None:
+        trace = _CONN_TRACE.get()
+        if trace is not None:
+            trace.reused = False
+            if trace.connect_started is not None:
+                trace.connect = clock() - trace.connect_started
+
+    async def on_reuseconn(session: aiohttp.ClientSession, ctx: SimpleNamespace, params: Any) -> None:
+        trace = _CONN_TRACE.get()
+        if trace is not None:
+            trace.reused = True
+
+    async def on_queued_start(session: aiohttp.ClientSession, ctx: SimpleNamespace, params: Any) -> None:
+        trace = _CONN_TRACE.get()
+        if trace is not None:
+            trace.queued_started = clock()
+
+    async def on_queued_end(session: aiohttp.ClientSession, ctx: SimpleNamespace, params: Any) -> None:
+        trace = _CONN_TRACE.get()
+        if trace is not None and trace.queued_started is not None:
+            trace.pool_wait = clock() - trace.queued_started
+
+    trace_config.on_request_start.append(on_request_start)
+    trace_config.on_dns_resolvehost_start.append(on_dns_start)
+    trace_config.on_dns_resolvehost_end.append(on_dns_end)
+    trace_config.on_connection_create_start.append(on_connect_start)
+    trace_config.on_connection_create_end.append(on_connect_end)
+    trace_config.on_connection_reuseconn.append(on_reuseconn)
+    trace_config.on_connection_queued_start.append(on_queued_start)
+    trace_config.on_connection_queued_end.append(on_queued_end)
+    return trace_config
+
+
+__all__ = ["ENGINE_ACTIVE", "build_trace_config", "current_conn_metrics"]

clientwright/adapters/aiohttp/views.py

@@ -0,0 +1,108 @@
+"""RequestView/ResponseView implementations over aiohttp objects."""
+
+from __future__ import annotations
+
+from collections.abc import MutableMapping
+from typing import cast
+
+from ...core.model import IDEMPOTENT_METHODS, RequestInfo, ResolvedTimeouts, origin_of
+from ._imports import URL, aiohttp
+from .options import current_call_options
+
+_BODY_HEADERS = ("Content-Length", "Content-Type", "Transfer-Encoding")
+
+
+def _host_header(url: URL) -> str:
+    host = url.host or ""
+    if url.explicit_port is None or url.is_default_port():
+        return host
+    return f"{host}:{url.explicit_port}"
+
+
+class AiohttpRequestView:
+    __slots__ = ("_options", "_request", "pending_empty_body")
+
+    def __init__(self, request: aiohttp.ClientRequest) -> None:
+        self._request = request
+        # Snapshot ONCE: the view lives for the whole logical call, while the
+        # caller's context may have moved on by the time a retry fires.
+        self._options = current_call_options()
+        # Bodies can only be replaced with an await (update_body); a sync
+        # retarget marks the drop and the middleware applies it before send.
+        self.pending_empty_body = False
+
+    @property
+    def native(self) -> aiohttp.ClientRequest:
+        return self._request
+
+    @property
+    def info(self) -> RequestInfo:
+        request = self._request
+        method = request.method
+        url = str(request.url)
+        options = self._options
+        route = options.route if options is not None else None
+        if options is not None and options.idempotent is not None:
+            idempotent = options.idempotent
+        else:
+            idempotent = method in IDEMPOTENT_METHODS
+        return RequestInfo(method=method, origin=origin_of(url), url=url, route=route, idempotent=idempotent)
+
+    @property
+    def headers(self) -> MutableMapping[str, str]:
+        return cast(MutableMapping[str, str], self._request.headers)
+
+    def caller_timeouts(self) -> ResolvedTimeouts | None:
+        # Per-request timeout= exists in aiohttp but is consumed by _request
+        # before the middleware runs; there is no channel to observe it here.
+        return None
+
+    def apply_timeouts(self, timeouts: ResolvedTimeouts) -> None:
+        # Phase timeouts are fixed at session level (ClientRequest.timeout is
+        # read-only); the engine's own asyncio.timeout enforces the attempt
+        # ceiling, which is the knob that actually varies per attempt.
+        return None
+
+    def retarget(self, url: str, *, method: str | None = None, drop_body: bool = False) -> None:
+        request = self._request
+        target = URL(url)
+        request.url = target
+        # aiohttp builds each ClientResponse from original_url; without this the
+        # final response (and its cookies) would be attributed to the
+        # pre-redirect URL.
+        request.original_url = target
+        # Host was computed at construction time; a retargeted request must
+        # not present the old host to the new server.
+        request.headers["Host"] = _host_header(target)
+        if method is not None:
+            request.method = method
+        if drop_body:
+            for name in _BODY_HEADERS:
+                request.headers.pop(name, None)
+            self.pending_empty_body = True
+
+
+class AiohttpResponseView:
+    __slots__ = ("_response",)
+
+    def __init__(self, response: aiohttp.ClientResponse) -> None:
+        self._response = response
+
+    @property
+    def native(self) -> aiohttp.ClientResponse:
+        return self._response
+
+    @property
+    def status_code(self) -> int:
+        return self._response.status
+
+    def header(self, name: str) -> str | None:
+        value = self._response.headers.get(name)
+        return value if isinstance(value, str) else None
+
+    @property
+    def location(self) -> str | None:
+        return self.header("Location")
+
+
+__all__ = ["AiohttpRequestView", "AiohttpResponseView"]

clientwright/adapters/httpx/__init__.py

@@ -0,0 +1,45 @@
+"""httpx adapter (``[httpx]`` extra): real httpx clients, engine underneath.
+
+Names resolve lazily (see ``clientwright.adapters._lazy``): importing this
+package never imports httpx, so the capabilities matrix stays extras-free.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .._lazy import lazy_attribute
+
+if TYPE_CHECKING:
+    from .adapter import HttpxAdapter as HttpxAdapter
+    from .capabilities import CAPABILITIES as CAPABILITIES
+    from .errors import HttpxCircuitOpenError as HttpxCircuitOpenError
+    from .errors import HttpxDeadlineExceededError as HttpxDeadlineExceededError
+    from .errors import HttpxTooManyRedirectsError as HttpxTooManyRedirectsError
+    from .views import IDEMPOTENT_EXTENSION as IDEMPOTENT_EXTENSION
+    from .views import ROUTE_EXTENSION as ROUTE_EXTENSION
+
+_EXPORTS = {
+    "CAPABILITIES": "capabilities",
+    "HttpxAdapter": "adapter",
+    "HttpxCircuitOpenError": "errors",
+    "HttpxDeadlineExceededError": "errors",
+    "HttpxTooManyRedirectsError": "errors",
+    "IDEMPOTENT_EXTENSION": "views",
+    "ROUTE_EXTENSION": "views",
+}
+
+
+def __getattr__(name: str) -> Any:
+    return lazy_attribute(__name__, globals(), _EXPORTS, name)
+
+
+__all__ = [
+    "CAPABILITIES",
+    "IDEMPOTENT_EXTENSION",
+    "ROUTE_EXTENSION",
+    "HttpxAdapter",
+    "HttpxCircuitOpenError",
+    "HttpxDeadlineExceededError",
+    "HttpxTooManyRedirectsError",
+]

clientwright/adapters/httpx/_imports.py

@@ -0,0 +1,17 @@
+"""Lazy import guard for the optional httpx stack.
+
+Importing this module fails with a friendly message when the ``httpx`` extra is
+not installed, so ``import clientwright`` never pays the cost (or the failure).
+Every httpx submodule imports its third-party symbols from here.
+"""
+
+from __future__ import annotations
+
+_INSTALL_HINT = "httpx support requires clientwright[httpx]; install it."
+
+try:
+    import httpx
+except ImportError as exc:  # pragma: no cover - exercised only without the extra
+    raise ImportError(_INSTALL_HINT) from exc
+
+__all__ = ["httpx"]

clientwright/adapters/httpx/adapter.py

@@ -0,0 +1,39 @@
+"""The httpx adapter: the shared family builder bound to the httpx SDK.
+
+Constructor traps the shared builder dodges (verified against httpx 0.28):
+- ``Client(transport=...)`` silently ignores ``verify``/``http2``/``limits`` -
+  everything pool/TLS-related therefore goes into the TRANSPORT constructor;
+- a custom transport disables env-proxy support - when asked, proxies are
+  parsed from the environment into engine-wrapped routing.
+"""
+
+from __future__ import annotations
+
+from .._httpx_shared import FamilyAdapter
+from ._imports import httpx
+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 = "httpx"
+    capabilities = CAPABILITIES
+    sdk = httpx
+    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/httpx/capabilities.py

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

clientwright/adapters/httpx/classify.py

@@ -0,0 +1,14 @@
+"""httpx 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 httpx
+
+
+def classify_error(exc: BaseException) -> FailureKind:
+    return classify_family_error(httpx, exc)
+
+
+__all__ = ["classify_error"]

clientwright/adapters/httpx/errors.py

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

clientwright/adapters/httpx/normalize.py

@@ -0,0 +1,27 @@
+"""Async normalizer binding: shared family logic over the httpx SDK."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from .._httpx_shared import AsyncFamilyNormalizer, AsyncTimedStreamMixin
+from ._imports import httpx
+from .views import HttpxRequestView
+
+
+class _TimedAsyncStream(AsyncTimedStreamMixin, httpx.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=httpx,
+            request_view=lambda native: HttpxRequestView(native, default_timeout),
+            timed_stream=_TimedAsyncStream,
+        )
+
+
+__all__ = ["AsyncHttpxNormalizer"]

clientwright/adapters/httpx/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 httpx
+from .views import HttpxRequestView
+
+
+class _TimedSyncStream(SyncTimedStreamMixin, httpx.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=httpx,
+            request_view=lambda native: HttpxRequestView(native, default_timeout),
+            timed_stream=_TimedSyncStream,
+        )
+
+
+__all__ = ["SyncHttpxNormalizer"]

clientwright/adapters/httpx/transport.py

@@ -0,0 +1,40 @@
+"""Engine-driven httpx transports: shared mixin logic bound to httpx bases.
+
+The seam sits UNDER the public API: the returned client is a genuine
+``httpx.AsyncClient`` / ``httpx.Client`` and every request that flows through
+it - including one sent via a raw ``client.send`` - passes the engine.
+"""
+
+from __future__ import annotations
+
+from .._httpx_shared import (
+    AsyncEngineTransportMixin,
+    AsyncProxyRouterMixin,
+    SyncEngineTransportMixin,
+    SyncProxyRouterMixin,
+)
+from ._imports import httpx
+
+
+class AsyncEngineTransport(AsyncEngineTransportMixin, httpx.AsyncBaseTransport):
+    pass
+
+
+class SyncEngineTransport(SyncEngineTransportMixin, httpx.BaseTransport):
+    pass
+
+
+class AsyncProxyRouterTransport(AsyncProxyRouterMixin, httpx.AsyncBaseTransport):
+    pass
+
+
+class SyncProxyRouterTransport(SyncProxyRouterMixin, httpx.BaseTransport):
+    pass
+
+
+__all__ = [
+    "AsyncEngineTransport",
+    "AsyncProxyRouterTransport",
+    "SyncEngineTransport",
+    "SyncProxyRouterTransport",
+]

clientwright/adapters/httpx/views.py

@@ -0,0 +1,46 @@
+"""RequestView/ResponseView bindings over httpx objects.
+
+The logic lives in ``adapters/_httpx_shared``; this module binds it to the
+httpx SDK. The request class is shared by the sync and async clients, so one
+pair of views serves both normalizers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator
+
+from .._httpx_shared import IDEMPOTENT_EXTENSION, ROUTE_EXTENSION, FamilyRequestView, FamilyResponseView
+from ._imports import httpx
+
+
+class _ReplayStream(httpx.SyncByteStream, httpx.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: httpx.Request, default_timeout: dict[str, float | None]) -> None:
+        super().__init__(request, default_timeout, sdk=httpx, replay_stream=_ReplayStream)
+
+
+class HttpxResponseView(FamilyResponseView):
+    __slots__ = ()
+
+
+__all__ = [
+    "IDEMPOTENT_EXTENSION",
+    "ROUTE_EXTENSION",
+    "HttpxRequestView",
+    "HttpxResponseView",
+    "_ReplayStream",
+]

clientwright/adapters/httpx2/__init__.py

@@ -0,0 +1,46 @@
+"""httpx2 adapter (``[httpx2]`` extra): real httpx2 clients, engine underneath.
+
+Names resolve lazily (see ``clientwright.adapters._lazy``): importing this
+package never imports httpx2, so the capabilities matrix stays extras-free.
+Public names are deliberately IDENTICAL to the httpx adapter's.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .._lazy import lazy_attribute
+
+if TYPE_CHECKING:
+    from .adapter import HttpxAdapter as HttpxAdapter
+    from .capabilities import CAPABILITIES as CAPABILITIES
+    from .errors import HttpxCircuitOpenError as HttpxCircuitOpenError
+    from .errors import HttpxDeadlineExceededError as HttpxDeadlineExceededError
+    from .errors import HttpxTooManyRedirectsError as HttpxTooManyRedirectsError
+    from .views import IDEMPOTENT_EXTENSION as IDEMPOTENT_EXTENSION
+    from .views import ROUTE_EXTENSION as ROUTE_EXTENSION
+
+_EXPORTS = {
+    "CAPABILITIES": "capabilities",
+    "HttpxAdapter": "adapter",
+    "HttpxCircuitOpenError": "errors",
+    "HttpxDeadlineExceededError": "errors",
+    "HttpxTooManyRedirectsError": "errors",
+    "IDEMPOTENT_EXTENSION": "views",
+    "ROUTE_EXTENSION": "views",
+}
+
+
+def __getattr__(name: str) -> Any:
+    return lazy_attribute(__name__, globals(), _EXPORTS, name)
+
+
+__all__ = [
+    "CAPABILITIES",
+    "IDEMPOTENT_EXTENSION",
+    "ROUTE_EXTENSION",
+    "HttpxAdapter",
+    "HttpxCircuitOpenError",
+    "HttpxDeadlineExceededError",
+    "HttpxTooManyRedirectsError",
+]

clientwright/adapters/httpx2/_imports.py

@@ -0,0 +1,18 @@
+"""Lazy import guard for the optional httpx2 stack.
+
+httpx2 is the httpx successor maintained by Pydantic Services Inc.: a separate
+distribution and import namespace with the same API surface. Importing this
+module fails with a friendly message when the ``httpx2`` extra is not
+installed. Every httpx2 submodule imports its third-party symbols from here.
+"""
+
+from __future__ import annotations
+
+_INSTALL_HINT = "httpx2 support requires clientwright[httpx2]; install it."
+
+try:
+    import httpx2
+except ImportError as exc:  # pragma: no cover - exercised only without the extra
+    raise ImportError(_INSTALL_HINT) from exc
+
+__all__ = ["httpx2"]