clientwright 0.1.0__py3-none-any.whl

clientwright/adapters/urllib3/adapter.py

@@ -0,0 +1,260 @@
+"""The urllib3 adapter: builds real PoolManager objects with the engine underneath.
+
+The seam is a per-instance ``urlopen`` injected on a GENUINE ``PoolManager``
+(``type(client) is urllib3.PoolManager`` holds - no subclass); recursive
+native calls and lower clientwright layers pass straight through via the
+suppression ContextVar.
+
+This is also the documented home of ``RetryMode.DELEGATED``: urllib3's Retry
+is the richest native implementation, so a config in DELEGATED mode is
+translated into ``urllib3.util.Retry`` and the native machinery runs the loop
+below the seam - with per-attempt metrics honestly absent.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from ...core.capabilities import Capability
+from ...core.config import ClientConfig, RetryConfig, RetryMode, 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.policy.timeout import base_timeouts
+from ...core.telemetry.emitter import ClientTelemetry
+from ._imports import Retry, Timeout, urllib3
+from .capabilities import CAPABILITIES
+from .errors import translate_call_error
+from .normalize import SyncUrllib3Normalizer
+from .views import Urllib3CallSpec, Urllib3RequestView
+
+# urllib3 defaults timeouts to socket.getdefaulttimeout() (usually unbounded).
+_NATIVE_TIMEOUT_DEFAULTS = ResolvedTimeouts()
+
+_RESERVED_MANAGER_KEYS: Mapping[str, str] = {
+    "timeout": "use ClientConfig.timeout",
+    "retries": "retries belong to clientwright; use ClientConfig.retry (mode=DELEGATED for native execution)",
+    "maxsize": "use ClientConfig.pool.max_connections_per_host",
+    "block": "use ClientConfig.pool.max_connections_per_host",
+    "cert_reqs": "use ClientConfig.tls",
+    "ca_certs": "use ClientConfig.tls.ca_bundle",
+    "cert_file": "use ClientConfig.tls.cert",
+    "key_file": "use ClientConfig.tls.cert",
+}
+
+
+def translate_retry(retry: RetryConfig, max_redirects: int) -> Retry:
+    """Express RetryConfig as urllib3.util.Retry for DELEGATED mode.
+
+    urllib3's exponential backoff base is fixed at 2; ``multiplier`` is not
+    translated (declared in the capabilities notes).
+    """
+    return Retry(
+        total=retry.max_attempts - 1,
+        redirect=max_redirects,
+        backoff_factor=retry.initial_backoff,
+        backoff_max=retry.max_backoff,
+        backoff_jitter=retry.jitter * retry.initial_backoff,
+        status_forcelist=set(retry.retryable_status),
+        allowed_methods=frozenset(retry.methods),
+        respect_retry_after_header=retry.respect_retry_after,
+        raise_on_status=False,
+        raise_on_redirect=False,
+    )
+
+
+class EngineUrlopen:
+    """The instance-injected urlopen: one call in, one engine-driven logical call out."""
+
+    __slots__ = ("_blocking", "_delegated_retry", "_engine", "_manager")
+
+    def __init__(
+        self,
+        manager: urllib3.PoolManager,
+        engine: SyncAttemptEngine,
+        delegated_retry: Retry | None,
+        blocking_pool: bool,
+    ) -> None:
+        self._manager = manager
+        self._engine = engine
+        self._delegated_retry = delegated_retry
+        self._blocking = blocking_pool
+
+    def _native_urlopen(self, method: str, url: str, **kw: Any) -> Any:
+        return type(self._manager).urlopen(self._manager, method, url, **kw)
+
+    def _send(self, view: RequestView) -> Any:
+        assert isinstance(view, Urllib3RequestView)
+        spec = view.native
+        kw = dict(spec.kw)
+        kw["headers"] = dict(spec.headers)
+        kw["body"] = spec.body
+        if self._delegated_retry is not None:
+            # Native machinery owns retries AND redirects below the seam.
+            kw["retries"] = self._delegated_retry
+            kw.setdefault("redirect", True)
+        else:
+            # The engine owns the loop: raw errors, no native retry, no native
+            # redirect following (hops re-enter through retarget()).
+            kw["retries"] = False
+            kw["redirect"] = False
+        planned = spec.planned
+        if planned is not None:
+            kw["timeout"] = Timeout(connect=planned.connect, read=planned.read)
+            if self._blocking and planned.pool_acquire is not None:
+                kw.setdefault("pool_timeout", planned.pool_acquire)
+        with suppressed():
+            return self._native_urlopen(spec.method, spec.url, **kw)
+
+    def __call__(self, method: str, url: str, redirect: bool = True, **kw: Any) -> Any:
+        if is_suppressed():
+            # A recursive native hop, or an outer clientwright layer that owns
+            # instrumentation: pass straight through.
+            return self._native_urlopen(method, url, redirect=redirect, **kw)
+        headers_arg = kw.pop("headers", None)
+        headers = dict(headers_arg) if headers_arg is not None else dict(self._manager.headers or {})
+        body = kw.pop("body", None)
+        spec = Urllib3CallSpec(method, url, headers, body, kw)
+        return self._engine.run(spec, self._send)
+
+
+class Urllib3Adapter:
+    name = "urllib3"
+    capabilities = CAPABILITIES
+    native_slots = frozenset({"manager"})
+    reserved_keys: Mapping[str, Mapping[str, str]] = {"manager": _RESERVED_MANAGER_KEYS}
+    allowed_keys: Mapping[str, frozenset[str] | None] = {"manager": 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={"manager": urllib3.HTTPConnectionPool},
+            config_conflicts={},
+        )
+
+    def _compile(self, config: ClientConfig) -> CallPlan:
+        per_host = resolve(config.pool.max_connections_per_host, None)
+        applied = {Capability.TIMEOUT_CONNECT, Capability.TIMEOUT_READ, Capability.REDIRECTS_OWNABLE}
+        if per_host is not None:
+            applied |= {Capability.POOL_LIMIT_PER_HOST, Capability.TIMEOUT_POOL}
+        if config.proxy is not None and config.proxy.url 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] = "urllib3 has no write timeout"
+        pool_acquire_set = (
+            is_set(config.timeout.pool_acquire) and resolve(config.timeout.pool_acquire, None) is not None
+        )
+        if per_host is None and pool_acquire_set:
+            dropped[Capability.TIMEOUT_POOL] = "pool_timeout needs a blocking pool; set pool.max_connections_per_host"
+        if resolve(config.pool.http2, False):
+            dropped[Capability.HTTP2] = "urllib3's HTTP/2 support is experimental and not wired here"
+        if config.proxy is not None and config.proxy.from_env:
+            dropped[Capability.PROXY] = "urllib3 does not read environment proxies; pass ProxyConfig.url"
+        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 _manager_kwargs(self, config: ClientConfig, native_manager: dict[str, Any]) -> dict[str, Any]:
+        per_host = resolve(config.pool.max_connections_per_host, None)
+        base = base_timeouts(config.timeout, _NATIVE_TIMEOUT_DEFAULTS)
+        kwargs: dict[str, Any] = {
+            "maxsize": per_host if per_host is not None else resolve(config.pool.max_connections, 10) or 10,
+            "block": per_host is not None,
+            # A defensive default for calls that bypass the engine (suppressed
+            # native hops); the engine overrides timeout per attempt anyway.
+            "timeout": Timeout(connect=base.connect, read=base.read),
+        }
+        tls = config.tls
+        if not tls.verify:
+            kwargs["cert_reqs"] = "CERT_NONE"
+        if tls.ca_bundle is not None:
+            kwargs["ca_certs"] = tls.ca_bundle
+        if tls.cert is not None:
+            if isinstance(tls.cert, str):
+                kwargs["cert_file"] = tls.cert
+            else:
+                kwargs["cert_file"] = tls.cert[0]
+                kwargs["key_file"] = tls.cert[1]
+        kwargs.update(native_manager)
+        return kwargs
+
+    def build_sync(self, config: ClientConfig, deps: AdapterDeps) -> ClientHandle[Any]:
+        if config.base_url is not None:
+            raise UnsupportedCapabilityError("urllib3 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=SyncUrllib3Normalizer(),
+            deps=deps,
+            translate=translate_call_error,
+        )
+        manager_kwargs = self._manager_kwargs(config, native.get("manager", {}))
+        manager: urllib3.PoolManager
+        if config.proxy is not None and config.proxy.url is not None:
+            manager = urllib3.ProxyManager(config.proxy.url, **manager_kwargs)
+        else:
+            manager = urllib3.PoolManager(**manager_kwargs)
+        delegated = config.retry is not None and config.retry.mode is RetryMode.DELEGATED
+        delegated_retry = (
+            translate_retry(config.retry, config.max_redirects) if delegated and config.retry is not None else None
+        )
+        per_host = resolve(config.pool.max_connections_per_host, None)
+        # The instance attribute shadows the class method for every entry point
+        # (request/request_encode_* all funnel into self.urlopen), while
+        # type(manager) stays the genuine native class.
+        manager.urlopen = EngineUrlopen(manager, engine, delegated_retry, per_host is not None)  # type: ignore[method-assign]
+        handle: ClientHandle[Any] = ClientHandle(
+            client=manager,
+            adapter=self.name,
+            capabilities=CAPABILITIES,
+            report=plan.report,
+            runtime=runtime,
+            plan=plan,
+            close=manager.clear,
+        )
+        register_handle(manager, handle)
+        return handle
+
+    def build_async(self, config: ClientConfig, deps: AdapterDeps) -> ClientHandle[Any]:
+        raise UnsupportedCapabilityError(
+            "urllib3 is sync-only: there is no async client to build; use build_sync (or the httpx/aiohttp adapters)"
+        )
+
+
+__all__ = ["EngineUrlopen", "Urllib3Adapter", "translate_retry"]

clientwright/adapters/urllib3/capabilities.py

@@ -0,0 +1,86 @@
+"""urllib3 capability declaration. Zero-dependency: never imports urllib3."""
+
+from __future__ import annotations
+
+from ...core.capabilities import (
+    AdapterCapabilities,
+    Capability,
+    DurationBoundary,
+    SeamGranularity,
+    Support,
+)
+from ...core.model import FailureKind
+
+CAPABILITIES = AdapterCapabilities(
+    adapter="urllib3",
+    seam="urlopen",
+    granularity=SeamGranularity.LOGICAL,
+    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.NATIVE,
+        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.POOL_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.PROTOCOL_ERROR: FailureKind.DISCONNECTED,
+        FailureKind.WRITE_TIMEOUT: FailureKind.TOTAL_TIMEOUT,
+    },
+    notes={
+        "sync_only": "urllib3 has no async client; build_async raises.",
+        "seam": (
+            "The engine is injected as an INSTANCE urlopen on a genuine PoolManager (type(client) is "
+            "urllib3.PoolManager); recursive native redirect hops re-enter it and pass straight through."
+        ),
+        "delegated_retries": (
+            "RetryMode.DELEGATED is the documented carve-out here: RetryConfig is translated into "
+            "urllib3.util.Retry and the native machinery runs the loop below the seam. Per-attempt metrics are "
+            "honestly absent (attempts live inside conn.urlopen); observe them via response.retries.history. "
+            "The backoff multiplier is fixed at 2 by urllib3; RetryConfig.multiplier is not translated."
+        ),
+        "timeout_pool": (
+            "The only adapter where the pool timeout is real: pool_timeout is injected per call when "
+            "max_connections_per_host makes the pool blocking."
+        ),
+        "pool_limits": "num_pools is an LRU cache of host pools, not a global cap; maxsize+block cap per host.",
+        "keepalive": "Connections are kept alive by pool defaults; expiry and keep-alive count are not controllable.",
+        "per_call_options": "No request object; route/idempotency travel via the call_options() context manager.",
+        "base_url": "urllib3 has no base_url; the build rejects a config that sets one.",
+        "proxy": "An explicit proxy builds a genuine urllib3.ProxyManager; env proxies are not read (dropped).",
+    },
+)
+
+__all__ = ["CAPABILITIES"]

clientwright/adapters/urllib3/classify.py

@@ -0,0 +1,46 @@
+"""urllib3 exception -> FailureKind classification."""
+
+from __future__ import annotations
+
+from ...core.model import FailureKind
+from ._imports import urllib3
+
+_EXC = urllib3.exceptions
+
+
+def classify_error(exc: BaseException) -> FailureKind:
+    if isinstance(exc, _EXC.MaxRetryError):
+        # Native retries exhausted (DELEGATED mode): the last real failure is
+        # the reason; classify that, not the wrapper.
+        if exc.reason is not None:
+            return classify_error(exc.reason)
+        return FailureKind.UNKNOWN
+    # urllib3 v2 subclasses NameResolutionError < NewConnectionError <
+    # ConnectTimeoutError, so the ladder MUST test most-specific first or DNS
+    # failures and refused connections masquerade as connect timeouts.
+    if isinstance(exc, _EXC.NameResolutionError):
+        return FailureKind.DNS_ERROR
+    if isinstance(exc, _EXC.NewConnectionError):
+        return FailureKind.CONNECT_ERROR
+    if isinstance(exc, _EXC.ConnectTimeoutError):
+        return FailureKind.CONNECT_TIMEOUT
+    if isinstance(exc, _EXC.ReadTimeoutError):
+        return FailureKind.READ_TIMEOUT
+    if isinstance(exc, _EXC.ProxyError):
+        return FailureKind.CONNECT_ERROR
+    if isinstance(exc, _EXC.SSLError):
+        return FailureKind.TLS_ERROR
+    if isinstance(exc, _EXC.ProtocolError):
+        return FailureKind.DISCONNECTED
+    if isinstance(exc, _EXC.DecodeError):
+        return FailureKind.BODY_ERROR
+    if isinstance(exc, _EXC.EmptyPoolError):
+        return FailureKind.POOL_TIMEOUT
+    if isinstance(exc, _EXC.PoolError):
+        return FailureKind.POOL_TIMEOUT
+    if isinstance(exc, (_EXC.TimeoutError, TimeoutError)):
+        return FailureKind.TOTAL_TIMEOUT
+    return FailureKind.UNKNOWN
+
+
+__all__ = ["classify_error"]

clientwright/adapters/urllib3/errors.py

@@ -0,0 +1,55 @@
+"""Kernel errors dual-inherited into the urllib3 family.
+
+A user's ``except urllib3.exceptions.HTTPError`` keeps working when
+clientwright raises on its own authority.
+"""
+
+from __future__ import annotations
+
+from ...core.errors import CallError, CircuitOpenError, DeadlineExceededError, TooManyRedirectsError
+from ._imports import urllib3
+
+
+class Urllib3CircuitOpenError(CircuitOpenError, urllib3.exceptions.HTTPError):
+    """Circuit open, catchable as urllib3.exceptions.HTTPError."""
+
+
+class Urllib3DeadlineExceededError(DeadlineExceededError, urllib3.exceptions.TimeoutError):
+    """Total deadline exhausted, catchable as urllib3.exceptions.TimeoutError."""
+
+
+class Urllib3TooManyRedirectsError(TooManyRedirectsError, urllib3.exceptions.MaxRetryError):
+    """Owned redirect limit exceeded, catchable as urllib3.exceptions.MaxRetryError.
+
+    ``MaxRetryError.__init__`` demands pool/url positionally, which breaks the
+    cooperative super chain - so this class initializes by hand and pins the
+    attributes urllib3's ``__str__`` machinery expects.
+    """
+
+    def __init__(self, hops: int) -> None:
+        Exception.__init__(self, f"Exceeded {hops} redirect hops")
+        self.hops = hops
+        self.pool = None  # type: ignore[assignment]
+        self.url = ""
+        self.reason = None
+
+    def __str__(self) -> str:
+        return f"Exceeded {self.hops} redirect hops"
+
+
+def translate_call_error(error: CallError) -> BaseException:
+    if isinstance(error, CircuitOpenError):
+        return Urllib3CircuitOpenError(error.key, error.retry_after)
+    if isinstance(error, DeadlineExceededError):
+        return Urllib3DeadlineExceededError(error.total)
+    if isinstance(error, TooManyRedirectsError):
+        return Urllib3TooManyRedirectsError(error.hops)
+    return error
+
+
+__all__ = [
+    "Urllib3CircuitOpenError",
+    "Urllib3DeadlineExceededError",
+    "Urllib3TooManyRedirectsError",
+    "translate_call_error",
+]

clientwright/adapters/urllib3/normalize.py

@@ -0,0 +1,51 @@
+"""Sync normalizer: the whole urllib3-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 .classify import classify_error
+from .views import Urllib3RequestView, Urllib3ResponseView
+
+
+class SyncUrllib3Normalizer:
+    def wrap_request(self, native: Any) -> Urllib3RequestView:
+        return Urllib3RequestView(native)
+
+    def wrap_response(self, native: Any) -> Urllib3ResponseView:
+        return Urllib3ResponseView(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:
+        body = request.native.body
+        return body is None or isinstance(body, (bytes, str))
+
+    def rewind(self, request: RequestView) -> None:
+        return None
+
+    def discard(self, response: ResponseView) -> None:
+        """MANDATORY before a repeat - otherwise the connection never returns to the pool."""
+        try:
+            response.native.drain_conn()
+        except Exception:
+            return None
+
+    def wrap_stream(self, response: ResponseView, on_done: Callable[[Outcome, float], None]) -> None:
+        # urlopen preloads the body by default; streaming reads happen above
+        # the seam and are not instrumented. Declared in capabilities.
+        return None
+
+    def conn_metrics(self, response: ResponseView) -> ConnMetrics | None:
+        return None
+
+
+__all__ = ["SyncUrllib3Normalizer"]

clientwright/adapters/urllib3/views.py

@@ -0,0 +1,119 @@
+"""RequestView/ResponseView implementations over urllib3 calls.
+
+urllib3 has no request object with stable identity - the seam is the
+``urlopen(method, url, **kw)`` signature. The adapter synthesizes a mutable
+call spec and the view wraps that; the send callback translates it back into
+positional/keyword arguments.
+"""
+
+from __future__ import annotations
+
+from collections.abc import MutableMapping
+from typing import Any
+
+from ...core.model import IDEMPOTENT_METHODS, RequestInfo, ResolvedTimeouts, origin_of
+from ...core.options import current_call_options
+from ._imports import Timeout
+
+
+class Urllib3CallSpec:
+    """The mutable identity of one logical urlopen call."""
+
+    __slots__ = ("body", "headers", "kw", "method", "planned", "url")
+
+    def __init__(self, method: str, url: str, headers: dict[str, str], body: Any, kw: dict[str, Any]) -> None:
+        self.method = method
+        self.url = url
+        self.headers = headers
+        self.body = body
+        self.kw = kw
+        self.planned: ResolvedTimeouts | None = None
+
+
+def caller_timeouts_from(timeout: object) -> ResolvedTimeouts | None:
+    """Translate urllib3's ``timeout=`` forms: float or urllib3.util.Timeout."""
+    if timeout is None:
+        return None
+    if isinstance(timeout, (int, float)):
+        value = float(timeout)
+        return ResolvedTimeouts(connect=value, read=value)
+    if isinstance(timeout, Timeout):
+        connect = timeout.connect_timeout
+        read = timeout.read_timeout
+        return ResolvedTimeouts(
+            connect=float(connect) if isinstance(connect, (int, float)) else None,
+            read=float(read) if isinstance(read, (int, float)) else None,
+        )
+    return None
+
+
+class Urllib3RequestView:
+    __slots__ = ("_caller", "_options", "_spec")
+
+    def __init__(self, spec: Urllib3CallSpec) -> None:
+        self._spec = spec
+        self._options = current_call_options()
+        self._caller = caller_timeouts_from(spec.kw.get("timeout"))
+
+    @property
+    def native(self) -> Urllib3CallSpec:
+        return self._spec
+
+    @property
+    def info(self) -> RequestInfo:
+        spec = self._spec
+        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 = spec.method in IDEMPOTENT_METHODS
+        return RequestInfo(
+            method=spec.method, origin=origin_of(spec.url), url=spec.url, route=route, idempotent=idempotent
+        )
+
+    @property
+    def headers(self) -> MutableMapping[str, str]:
+        return self._spec.headers
+
+    def caller_timeouts(self) -> ResolvedTimeouts | None:
+        return self._caller
+
+    def apply_timeouts(self, timeouts: ResolvedTimeouts) -> None:
+        self._spec.planned = timeouts
+
+    def retarget(self, url: str, *, method: str | None = None, drop_body: bool = False) -> None:
+        spec = self._spec
+        spec.url = url
+        if method is not None:
+            spec.method = method
+        if drop_body:
+            for name in ("Content-Length", "Content-Type", "Transfer-Encoding"):
+                spec.headers.pop(name, None)
+            spec.body = None
+
+
+class Urllib3ResponseView:
+    __slots__ = ("_response",)
+
+    def __init__(self, response: Any) -> None:
+        self._response = response
+
+    @property
+    def native(self) -> Any:
+        return self._response
+
+    @property
+    def status_code(self) -> int:
+        return int(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__ = ["Urllib3CallSpec", "Urllib3RequestView", "Urllib3ResponseView", "caller_timeouts_from"]

clientwright/contrib/__init__.py

@@ -0,0 +1,3 @@
+"""Integrations with org infrastructure, each behind its own extra."""
+
+__all__: list[str] = []