clientwright 0.1.0__py3-none-any.whl

clientwright/adapters/requests/adapter.py

@@ -0,0 +1,206 @@
+"""The requests adapter: builds real Session objects with the engine underneath.
+
+The seam is a mounted ``HTTPAdapter`` subclass whose ``send()`` runs the
+engine; the returned object is a genuine ``requests.Session``. Two constraints
+this builder honors (verified against requests 2.32):
+
+- requests has NO session-level timeout default - a bare ``session.get()``
+  hangs forever; the engine sends every attempt with its planned
+  ``(connect, read)`` tuple, closing that hole;
+- native retries execute INSIDE ``conn.urlopen``, invisible to metrics and the
+  breaker - they are pinned to ``Retry(0, read=False)`` and the engine owns
+  the loop.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from ...core.capabilities import Capability
+from ...core.config import ClientConfig, is_set, resolve
+from ...core.contracts.adapter import AdapterDeps
+from ...core.contracts.message import RequestView
+from ...core.engine.suppress import is_suppressed, suppressed
+from ...core.engine.sync import SyncAttemptEngine
+from ...core.errors import UnsupportedCapabilityError
+from ...core.model import ResolvedTimeouts
+from ...core.native import validate_native
+from ...core.plan import CallPlan, ClientHandle, ClientRuntime, compile_plan, register_handle
+from ...core.telemetry.emitter import ClientTelemetry
+from ._imports import HTTPAdapter, requests, urllib3
+from .capabilities import CAPABILITIES
+from .errors import translate_call_error
+from .normalize import SyncRequestsNormalizer
+from .views import CALLER_TIMEOUT_ATTRIBUTE, RequestsRequestView
+
+# requests has no timeout defaults at all: an UNSET phase stays unbounded and
+# only the engine's total deadline clamps it.
+_NATIVE_TIMEOUT_DEFAULTS = ResolvedTimeouts()
+
+_SESSION_ATTRS = frozenset({"headers", "cookies", "auth", "params", "hooks", "stream", "trust_env"})
+
+_RESERVED_SESSION_KEYS: Mapping[str, str] = {
+    "verify": "use ClientConfig.tls",
+    "cert": "use ClientConfig.tls.cert",
+    "proxies": "use ClientConfig.proxy",
+    "max_redirects": "use ClientConfig.max_redirects",
+    "adapters": "the mounted adapters belong to clientwright",
+}
+
+_RESERVED_ADAPTER_KEYS: Mapping[str, str] = {
+    "max_retries": "retries belong to clientwright; use ClientConfig.retry",
+    "pool_connections": "use ClientConfig.pool",
+    "pool_maxsize": "use ClientConfig.pool.max_connections_per_host",
+    "pool_block": "use ClientConfig.pool.max_connections_per_host",
+}
+
+
+class EngineHTTPAdapter(HTTPAdapter):
+    """HTTPAdapter whose send() is one engine-driven logical call."""
+
+    def __init__(self, engine: SyncAttemptEngine, **kwargs: Any) -> None:
+        kwargs.setdefault("max_retries", urllib3.util.Retry(0, read=False))
+        super().__init__(**kwargs)
+        self._engine = engine
+
+    def send(
+        self,
+        request: requests.PreparedRequest,
+        stream: bool = False,
+        timeout: Any = None,
+        verify: bool | str = True,
+        cert: Any = None,
+        proxies: Any = None,
+    ) -> requests.Response:
+        if is_suppressed():
+            # An outer clientwright layer owns instrumentation for this call.
+            return super().send(request, stream=stream, timeout=timeout, verify=verify, cert=cert, proxies=proxies)
+        setattr(request, CALLER_TIMEOUT_ATTRIBUTE, timeout)
+
+        def send_view(view: RequestView) -> requests.Response:
+            planned = view.planned if isinstance(view, RequestsRequestView) else None
+            attempt_timeout = (planned.connect, planned.read) if planned is not None else timeout
+            with suppressed():
+                return super(EngineHTTPAdapter, self).send(
+                    view.native, stream=stream, timeout=attempt_timeout, verify=verify, cert=cert, proxies=proxies
+                )
+
+        response = self._engine.run(request, send_view)
+        assert isinstance(response, requests.Response)
+        return response
+
+
+class RequestsAdapter:
+    name = "requests"
+    capabilities = CAPABILITIES
+    native_slots = frozenset({"session", "adapter"})
+    reserved_keys: Mapping[str, Mapping[str, str]] = {
+        "session": _RESERVED_SESSION_KEYS,
+        "adapter": _RESERVED_ADAPTER_KEYS,
+    }
+    allowed_keys: Mapping[str, frozenset[str] | None] = {"session": _SESSION_ATTRS, "adapter": None}
+
+    def _validated_native(self, config: ClientConfig) -> dict[str, dict[str, Any]]:
+        return validate_native(
+            config.native,
+            slots=self.native_slots,
+            reserved=self.reserved_keys,
+            allowed=self.allowed_keys,
+            signature_targets={"adapter": HTTPAdapter},
+            config_conflicts={},
+        )
+
+    def _compile(self, config: ClientConfig) -> CallPlan:
+        applied = {Capability.TIMEOUT_CONNECT, Capability.TIMEOUT_READ, Capability.REDIRECTS_OWNABLE}
+        if resolve(config.pool.max_connections_per_host, None) is not None:
+            applied.add(Capability.POOL_LIMIT_PER_HOST)
+        if config.proxy is not None:
+            applied.add(Capability.PROXY)
+        emulated = {Capability.TIMEOUT_TOTAL}
+        dropped: dict[Capability, str] = {}
+        if is_set(config.timeout.attempt) and resolve(config.timeout.attempt, None) is not None:
+            dropped[Capability.TIMEOUT_ATTEMPT] = (
+                "sync engine cannot cancel a blocked attempt; only phase timeouts and the soft total apply"
+            )
+        if is_set(config.timeout.write) and resolve(config.timeout.write, None) is not None:
+            dropped[Capability.TIMEOUT_WRITE] = "requests has no write timeout"
+        if is_set(config.timeout.pool_acquire) and resolve(config.timeout.pool_acquire, None) is not None:
+            dropped[Capability.TIMEOUT_POOL] = "HTTPAdapter.send never forwards pool_timeout to urllib3"
+        if resolve(config.pool.http2, False):
+            dropped[Capability.HTTP2] = "requests speaks HTTP/1.1 only"
+        plan = compile_plan(
+            config,
+            CAPABILITIES,
+            native_timeout_defaults=_NATIVE_TIMEOUT_DEFAULTS,
+            applied_natively=frozenset(applied),
+            emulated=frozenset(emulated),
+            dropped=dropped,
+        )
+        plan.report.enforce(config.on_unsupported)
+        return plan
+
+    def build_sync(self, config: ClientConfig, deps: AdapterDeps) -> ClientHandle[Any]:
+        if config.base_url is not None:
+            raise UnsupportedCapabilityError("requests has no base_url; pass absolute URLs (or use the httpx adapter)")
+        native = self._validated_native(config)
+        telemetry = ClientTelemetry(
+            service=config.service_name,
+            adapter=self.name,
+            seam=CAPABILITIES.seam,
+            config=config.observability,
+            metrics=deps.metrics,
+            tracer=deps.tracer,
+        )
+        runtime = deps.runtime or ClientRuntime.for_config(
+            config, clock=deps.clock, circuit_listener=telemetry.circuit_state_changed
+        )
+        plan = self._compile(config)
+        engine = SyncAttemptEngine(
+            plan=plan,
+            runtime=runtime,
+            telemetry=telemetry,
+            normalizer=SyncRequestsNormalizer(),
+            deps=deps,
+            translate=translate_call_error,
+        )
+        per_host = resolve(config.pool.max_connections_per_host, None)
+        adapter_kwargs: dict[str, Any] = {
+            "pool_maxsize": per_host if per_host is not None else resolve(config.pool.max_connections, 10) or 10,
+            "pool_block": per_host is not None,
+        }
+        adapter_kwargs.update(native.get("adapter", {}))
+        engine_adapter = EngineHTTPAdapter(engine, **adapter_kwargs)
+        session = requests.Session()
+        session.mount("http://", engine_adapter)
+        session.mount("https://", engine_adapter)
+        session.verify = config.tls.ca_bundle if config.tls.ca_bundle is not None else config.tls.verify
+        cert = config.tls.cert
+        if isinstance(cert, tuple) and len(cert) == 3:
+            raise UnsupportedCapabilityError("requests does not support a client cert with a key password")
+        session.cert = cert
+        session.max_redirects = config.max_redirects
+        if config.proxy is not None and config.proxy.url is not None:
+            session.proxies.update({"http": config.proxy.url, "https": config.proxy.url})
+        # config.proxy.from_env needs nothing: requests reads env proxies natively.
+        for attr, value in native.get("session", {}).items():
+            setattr(session, attr, value)
+        handle: ClientHandle[Any] = ClientHandle(
+            client=session,
+            adapter=self.name,
+            capabilities=CAPABILITIES,
+            report=plan.report,
+            runtime=runtime,
+            plan=plan,
+            close=session.close,
+        )
+        register_handle(session, handle)
+        return handle
+
+    def build_async(self, config: ClientConfig, deps: AdapterDeps) -> ClientHandle[Any]:
+        raise UnsupportedCapabilityError(
+            "requests is sync-only: there is no async client to build; use build_sync (or the httpx/aiohttp adapters)"
+        )
+
+
+__all__ = ["EngineHTTPAdapter", "RequestsAdapter"]

clientwright/adapters/requests/capabilities.py

@@ -0,0 +1,80 @@
+"""requests capability declaration. Zero-dependency: never imports requests."""
+
+from __future__ import annotations
+
+from ...core.capabilities import (
+    AdapterCapabilities,
+    Capability,
+    DurationBoundary,
+    SeamGranularity,
+    Support,
+)
+from ...core.model import FailureKind
+
+CAPABILITIES = AdapterCapabilities(
+    adapter="requests",
+    seam="http_adapter",
+    granularity=SeamGranularity.HOP,
+    boundary=DurationBoundary.HEADERS,
+    support={
+        Capability.TIMEOUT_TOTAL: Support.EMULATED,
+        Capability.TIMEOUT_ATTEMPT: Support.ABSENT,
+        Capability.TIMEOUT_CONNECT: Support.NATIVE,
+        Capability.TIMEOUT_READ: Support.NATIVE,
+        Capability.TIMEOUT_WRITE: Support.ABSENT,
+        Capability.TIMEOUT_POOL: Support.ABSENT,
+        Capability.DEADLINE_HARD: Support.ABSENT,
+        Capability.POOL_LIMIT_TOTAL: Support.ABSENT,
+        Capability.POOL_LIMIT_PER_HOST: Support.NATIVE,
+        Capability.KEEPALIVE: Support.DEGRADED,
+        Capability.POOL_METRICS: Support.ABSENT,
+        Capability.CONN_METRICS: Support.ABSENT,
+        Capability.REDIRECTS_OWNABLE: Support.NATIVE,
+        Capability.NATIVE_RETRY_DISABLEABLE: Support.NATIVE,
+        Capability.PER_CALL_OPTIONS: Support.EMULATED,
+        Capability.RETROFIT: Support.ABSENT,
+        Capability.EXACT_NATIVE_TYPE: Support.NATIVE,
+        Capability.BALANCER: Support.ABSENT,
+        Capability.HTTP2: Support.ABSENT,
+        Capability.HTTP3: Support.ABSENT,
+        Capability.PROXY: Support.NATIVE,
+    },
+    emits=frozenset(
+        {
+            FailureKind.CONNECT_TIMEOUT,
+            FailureKind.READ_TIMEOUT,
+            FailureKind.TOTAL_TIMEOUT,
+            FailureKind.CONNECT_ERROR,
+            FailureKind.DNS_ERROR,
+            FailureKind.TLS_ERROR,
+            FailureKind.DISCONNECTED,
+            FailureKind.BODY_ERROR,
+            FailureKind.STATUS,
+            FailureKind.CIRCUIT_OPEN,
+            FailureKind.UNKNOWN,
+        }
+    ),
+    collapses={
+        FailureKind.POOL_TIMEOUT: FailureKind.CONNECT_TIMEOUT,
+        FailureKind.PROTOCOL_ERROR: FailureKind.DISCONNECTED,
+        FailureKind.WRITE_TIMEOUT: FailureKind.TOTAL_TIMEOUT,
+    },
+    notes={
+        "sync_only": "requests has no async client; build_async raises.",
+        "no_session_timeout": (
+            "requests has NO session-level timeout default - a bare session.get() hangs forever. The engine "
+            "closes that hole: every attempt is sent with the planned (connect, read) tuple."
+        ),
+        "timeout_pool": "HTTPAdapter.send never forwards pool_timeout; a saturated blocking pool waits inside connect.",
+        "pool_limits": (
+            "requests pools are per-host (pool_maxsize); there is no global cap - pool_connections is an LRU of "
+            "host pools, not a limit."
+        ),
+        "keepalive": "Connections stay alive per urllib3 defaults; expiry and keep-alive count are not controllable.",
+        "base_url": "requests has no base_url; the build rejects a config that sets one.",
+        "per_call_options": "No request extensions; route/idempotency travel via the call_options() context manager.",
+        "protocol_error": "requests folds protocol violations into ConnectionError; they surface as disconnected.",
+    },
+)
+
+__all__ = ["CAPABILITIES"]

clientwright/adapters/requests/classify.py

@@ -0,0 +1,62 @@
+"""requests exception -> FailureKind classification.
+
+requests rewrites most urllib3 failures into its own hierarchy and folds
+protocol violations into ConnectionError; the cause chain is inspected to tell
+a DNS failure or a mid-stream disconnect from a refused connection.
+"""
+
+from __future__ import annotations
+
+import http.client
+import ssl
+
+from ...core.model import FailureKind
+from ._imports import requests, urllib3
+
+
+def _cause_chain(exc: BaseException) -> list[BaseException]:
+    seen: set[int] = set()
+    chain: list[BaseException] = []
+    current: BaseException | None = exc
+    while current is not None and id(current) not in seen:
+        seen.add(id(current))
+        chain.append(current)
+        for nested in getattr(current, "args", ()):
+            if isinstance(nested, BaseException) and id(nested) not in seen:
+                chain.append(nested)
+        current = current.__cause__ or current.__context__
+    return chain
+
+
+def _classify_connection_error(exc: requests.exceptions.ConnectionError) -> FailureKind:
+    for cause in _cause_chain(exc):
+        if isinstance(cause, urllib3.exceptions.NameResolutionError):
+            return FailureKind.DNS_ERROR
+        if isinstance(cause, (urllib3.exceptions.ProtocolError, http.client.RemoteDisconnected, ConnectionResetError)):
+            return FailureKind.DISCONNECTED
+        if isinstance(cause, (ssl.SSLError, ssl.CertificateError)):
+            return FailureKind.TLS_ERROR
+    return FailureKind.CONNECT_ERROR
+
+
+def classify_error(exc: BaseException) -> FailureKind:
+    if isinstance(exc, requests.exceptions.ConnectTimeout):
+        return FailureKind.CONNECT_TIMEOUT
+    if isinstance(exc, requests.exceptions.ReadTimeout):
+        return FailureKind.READ_TIMEOUT
+    if isinstance(exc, requests.exceptions.Timeout):
+        return FailureKind.TOTAL_TIMEOUT
+    if isinstance(exc, requests.exceptions.SSLError):
+        return FailureKind.TLS_ERROR
+    if isinstance(exc, requests.exceptions.ProxyError):
+        return FailureKind.CONNECT_ERROR
+    if isinstance(exc, (requests.exceptions.ChunkedEncodingError, requests.exceptions.ContentDecodingError)):
+        return FailureKind.BODY_ERROR
+    if isinstance(exc, requests.exceptions.ConnectionError):
+        return _classify_connection_error(exc)
+    if isinstance(exc, TimeoutError):
+        return FailureKind.TOTAL_TIMEOUT
+    return FailureKind.UNKNOWN
+
+
+__all__ = ["classify_error"]

clientwright/adapters/requests/errors.py

@@ -0,0 +1,40 @@
+"""Kernel errors dual-inherited into the requests family.
+
+A user's ``except requests.RequestException`` (or ``except requests.Timeout``)
+keeps working when clientwright raises on its own authority.
+"""
+
+from __future__ import annotations
+
+from ...core.errors import CallError, CircuitOpenError, DeadlineExceededError, TooManyRedirectsError
+from ._imports import requests
+
+
+class RequestsCircuitOpenError(CircuitOpenError, requests.RequestException):
+    """Circuit open, catchable as requests.RequestException."""
+
+
+class RequestsDeadlineExceededError(DeadlineExceededError, requests.Timeout):
+    """Total deadline exhausted, catchable as requests.Timeout."""
+
+
+class RequestsTooManyRedirectsError(TooManyRedirectsError, requests.TooManyRedirects):
+    """Owned redirect limit exceeded, catchable as requests.TooManyRedirects."""
+
+
+def translate_call_error(error: CallError) -> BaseException:
+    if isinstance(error, CircuitOpenError):
+        return RequestsCircuitOpenError(error.key, error.retry_after)
+    if isinstance(error, DeadlineExceededError):
+        return RequestsDeadlineExceededError(error.total)
+    if isinstance(error, TooManyRedirectsError):
+        return RequestsTooManyRedirectsError(error.hops)
+    return error
+
+
+__all__ = [
+    "RequestsCircuitOpenError",
+    "RequestsDeadlineExceededError",
+    "RequestsTooManyRedirectsError",
+    "translate_call_error",
+]

clientwright/adapters/requests/normalize.py

@@ -0,0 +1,63 @@
+"""Sync normalizer: the whole requests-specific contract for the sync engine."""
+
+from __future__ import annotations
+
+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 requests
+from .classify import classify_error
+from .views import RequestsRequestView, RequestsResponseView
+
+
+class SyncRequestsNormalizer:
+    def wrap_request(self, native: Any) -> RequestsRequestView:
+        return RequestsRequestView(native)
+
+    def wrap_response(self, native: Any) -> RequestsResponseView:
+        return RequestsResponseView(native)
+
+    def classify_error(self, exc: BaseException) -> FailureKind:
+        return classify_error(exc)
+
+    def classify_response(self, response: ResponseView) -> Outcome:
+        return default_response_outcome(response)
+
+    def freeze(self, request: RequestView) -> bool:
+        """Bytes and strings replay for free; seekable streams rewind, the rest do not."""
+        body = request.native.body
+        if body is None or isinstance(body, (bytes, str)):
+            return True
+        position = getattr(request.native, "_body_position", None)
+        return isinstance(position, int)
+
+    def rewind(self, request: RequestView) -> None:
+        body = request.native.body
+        if body is None or isinstance(body, (bytes, str)):
+            return None
+        try:
+            requests.utils.rewind_body(request.native)
+        except requests.exceptions.UnrewindableBodyError:  # pragma: no cover - freeze() gated this
+            return None
+        return None
+
+    def discard(self, response: ResponseView) -> None:
+        """MANDATORY before a repeat - otherwise the connection never returns to the pool."""
+        try:
+            response.native.close()
+        except Exception:
+            return None
+
+    def wrap_stream(self, response: ResponseView, on_done: Callable[[Outcome, float], None]) -> None:
+        # Session.send consumes the body ABOVE this seam (unless stream=True);
+        # body read is not instrumented. Declared in capabilities.
+        return None
+
+    def conn_metrics(self, response: ResponseView) -> ConnMetrics | None:
+        return None
+
+
+__all__ = ["SyncRequestsNormalizer"]

clientwright/adapters/requests/views.py

@@ -0,0 +1,121 @@
+"""RequestView/ResponseView implementations over requests objects.
+
+The caller's per-request ``timeout=`` is not stored on the PreparedRequest;
+the engine adapter receives it as a ``send()`` argument and parks it on the
+request object before wrapping, which is where the view picks it up.
+"""
+
+from __future__ import annotations
+
+from collections.abc import MutableMapping
+from typing import cast
+from urllib.parse import urlsplit
+
+from ...core.model import IDEMPOTENT_METHODS, RequestInfo, ResolvedTimeouts, origin_of
+from ...core.options import current_call_options
+from ._imports import requests
+
+# Attribute the engine adapter sets on the PreparedRequest before wrapping.
+CALLER_TIMEOUT_ATTRIBUTE = "_clientwright_caller_timeout"
+
+_BODY_HEADERS = ("Content-Length", "Content-Type", "Transfer-Encoding")
+
+
+def caller_timeouts_from(timeout: object) -> ResolvedTimeouts | None:
+    """Translate requests' ``timeout=`` forms: float, or (connect, read)."""
+    if timeout is None:
+        return None
+    if isinstance(timeout, (int, float)):
+        value = float(timeout)
+        return ResolvedTimeouts(connect=value, read=value)
+    if isinstance(timeout, tuple) and len(timeout) == 2:
+        connect, read = timeout
+        return ResolvedTimeouts(
+            connect=float(connect) if connect is not None else None,
+            read=float(read) if read is not None else None,
+        )
+    return None
+
+
+class RequestsRequestView:
+    __slots__ = ("_caller", "_options", "_request", "planned")
+
+    def __init__(self, request: requests.PreparedRequest) -> None:
+        self._request = request
+        self._options = current_call_options()
+        self._caller = caller_timeouts_from(getattr(request, CALLER_TIMEOUT_ATTRIBUTE, None))
+        # The engine's per-attempt plan; the send callback translates it into
+        # the (connect, read) tuple HTTPAdapter.send accepts.
+        self.planned: ResolvedTimeouts | None = None
+
+    @property
+    def native(self) -> requests.PreparedRequest:
+        return self._request
+
+    @property
+    def info(self) -> RequestInfo:
+        request = self._request
+        method = request.method or "GET"
+        url = request.url or ""
+        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:
+        return self._caller
+
+    def apply_timeouts(self, timeouts: ResolvedTimeouts) -> None:
+        self.planned = timeouts
+
+    def retarget(self, url: str, *, method: str | None = None, drop_body: bool = False) -> None:
+        request = self._request
+        request.url = url
+        # requests never sets a Host header itself (http.client derives it from
+        # the URL), but a caller-set one must not leak to the new host.
+        if "Host" in request.headers:
+            request.headers["Host"] = urlsplit(url).netloc
+        if method is not None:
+            request.method = method
+        if drop_body:
+            for name in _BODY_HEADERS:
+                request.headers.pop(name, None)
+            request.body = None
+
+
+class RequestsResponseView:
+    __slots__ = ("_response",)
+
+    def __init__(self, response: requests.Response) -> None:
+        self._response = response
+
+    @property
+    def native(self) -> requests.Response:
+        return self._response
+
+    @property
+    def status_code(self) -> int:
+        return self._response.status_code
+
+    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__ = [
+    "CALLER_TIMEOUT_ATTRIBUTE",
+    "RequestsRequestView",
+    "RequestsResponseView",
+    "caller_timeouts_from",
+]

clientwright/adapters/urllib3/__init__.py

@@ -0,0 +1,48 @@
+"""urllib3 adapter (``[urllib3]`` extra): real PoolManager, engine underneath.
+
+SDK-backed names resolve lazily (see ``clientwright.adapters._lazy``): importing
+this package never imports urllib3, 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 Urllib3Adapter as Urllib3Adapter
+    from .adapter import translate_retry as translate_retry
+    from .capabilities import CAPABILITIES as CAPABILITIES
+    from .errors import Urllib3CircuitOpenError as Urllib3CircuitOpenError
+    from .errors import Urllib3DeadlineExceededError as Urllib3DeadlineExceededError
+    from .errors import Urllib3TooManyRedirectsError as Urllib3TooManyRedirectsError
+
+_EXPORTS = {
+    "CAPABILITIES": "capabilities",
+    "Urllib3Adapter": "adapter",
+    "Urllib3CircuitOpenError": "errors",
+    "Urllib3DeadlineExceededError": "errors",
+    "Urllib3TooManyRedirectsError": "errors",
+    "translate_retry": "adapter",
+}
+
+
+def __getattr__(name: str) -> Any:
+    return lazy_attribute(__name__, globals(), _EXPORTS, name)
+
+
+__all__ = [
+    "CAPABILITIES",
+    "CallOptions",
+    "Urllib3Adapter",
+    "Urllib3CircuitOpenError",
+    "Urllib3DeadlineExceededError",
+    "Urllib3TooManyRedirectsError",
+    "call_options",
+    "translate_retry",
+]

clientwright/adapters/urllib3/_imports.py

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