httpware 0.8.6__tar.gz → 0.9.1__tar.gz

{httpware-0.8.6 → httpware-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: httpware
-Version: 0.8.6
+Version: 0.9.1
 Summary: Resilience-first async HTTP client framework for Python
 Keywords: http,async,client,resilience,retry,circuit-breaker,middleware,httpx,pydantic
 Author: Artur Shiriev
@@ -21,7 +21,7 @@ Requires-Dist: opentelemetry-api>=1.20 ; extra == 'otel'
 Requires-Dist: pydantic>=2.0,<3.0 ; extra == 'pydantic'
 Requires-Python: >=3.11, <4
 Project-URL: repository, https://github.com/modern-python/httpware
-Project-URL: docs, https://httpware.readthedocs.io
+Project-URL: docs, https://httpware.modern-python.org
 Provides-Extra: all
 Provides-Extra: msgspec
 Provides-Extra: otel
@@ -45,12 +45,13 @@ Description-Content-Type: text/markdown
 
 ```bash
 pip install httpware                # core only — no decoder
-pip install httpware[pydantic]      # + PydanticDecoder (the default-decoder path)
-pip install httpware[msgspec]       # + MsgspecDecoder
+pip install httpware[pydantic]      # + PydanticDecoder — handles BaseModel + dataclasses + primitives + generics
+pip install httpware[msgspec]       # + MsgspecDecoder — handles Struct + dataclasses + primitives + generics
+pip install httpware[pydantic,msgspec]   # both extras — both decoders register; BaseModel routes to pydantic, Struct to msgspec
 pip install httpware[all]           # everything declared above (pydantic, msgspec, otel)
 ```
 
-`AsyncClient()` with no `decoder=` argument defaults to constructing a `PydanticDecoder`; that path requires the `pydantic` extra and raises `ImportError` at `AsyncClient.__init__` if it is missing.
+`AsyncClient()` resolves `decoders=None` against installed extras: pydantic if installed (first), msgspec if installed (second), or an empty tuple if neither. `AsyncClient()` never raises on missing extras — failure is deferred to the first `response_model=` call, where `MissingDecoderError` fires *before* the HTTP request if no registered decoder claims the model.
 
 ## Quickstart
 
@@ -79,7 +80,7 @@ with Client(base_url="https://example.test") as client:
     print(response.json())
 ```
 
-Typed decoding via `response_model=` works in both worlds — requires `pip install httpware[pydantic]`. Decode failures (malformed body, schema mismatch) raise `httpware.DecodeError`, a `ClientError` subclass — so `except httpware.ClientError` covers them alongside transport and status errors.
+Typed decoding via `response_model=` works in both worlds — install either `pip install httpware[pydantic]` or `pip install httpware[msgspec]` (or both; pydantic is tried first when both are present). Decode failures (malformed body, schema mismatch) raise `httpware.DecodeError`, a `ClientError` subclass — so `except httpware.ClientError` covers them alongside transport and status errors.
 
 ```python
 from httpware import AsyncClient
@@ -118,7 +119,7 @@ async def main() -> None:
         user = await client.get("/users/1", response_model=User)
 ```
 
-Need a custom middleware (auth, tracing, request-ID propagation, etc.)? See the [Middleware guide](docs/middleware.md).
+Need a custom middleware (auth, tracing, request-ID propagation, etc.)? See the [Middleware guide](https://httpware.modern-python.org/middleware/).
 
 ### Streaming responses
 
@@ -165,11 +166,13 @@ pip install httpware[otel]
 
 When installed, `_emit_event` calls `trace.get_current_span().add_event(name, attributes=...)` automatically. We never create our own spans; for HTTP-level tracing install `opentelemetry-instrumentation-httpx` separately.
 
+## 📚 [Documentation](https://httpware.modern-python.org)
+
 ## 🗒️ [Release notes](https://github.com/modern-python/httpware/releases)
 
 ## 📦 [PyPI](https://pypi.org/project/httpware)
 
-## 📝 [License](./LICENSE)
+## 📝 [License](https://github.com/modern-python/httpware/blob/main/LICENSE)
 
 ## Part of `modern-python`
 

{httpware-0.8.6 → httpware-0.9.1}/README.md

@@ -15,12 +15,13 @@
 
 ```bash
 pip install httpware                # core only — no decoder
-pip install httpware[pydantic]      # + PydanticDecoder (the default-decoder path)
-pip install httpware[msgspec]       # + MsgspecDecoder
+pip install httpware[pydantic]      # + PydanticDecoder — handles BaseModel + dataclasses + primitives + generics
+pip install httpware[msgspec]       # + MsgspecDecoder — handles Struct + dataclasses + primitives + generics
+pip install httpware[pydantic,msgspec]   # both extras — both decoders register; BaseModel routes to pydantic, Struct to msgspec
 pip install httpware[all]           # everything declared above (pydantic, msgspec, otel)
 ```
 
-`AsyncClient()` with no `decoder=` argument defaults to constructing a `PydanticDecoder`; that path requires the `pydantic` extra and raises `ImportError` at `AsyncClient.__init__` if it is missing.
+`AsyncClient()` resolves `decoders=None` against installed extras: pydantic if installed (first), msgspec if installed (second), or an empty tuple if neither. `AsyncClient()` never raises on missing extras — failure is deferred to the first `response_model=` call, where `MissingDecoderError` fires *before* the HTTP request if no registered decoder claims the model.
 
 ## Quickstart
 
@@ -49,7 +50,7 @@ with Client(base_url="https://example.test") as client:
     print(response.json())
 ```
 
-Typed decoding via `response_model=` works in both worlds — requires `pip install httpware[pydantic]`. Decode failures (malformed body, schema mismatch) raise `httpware.DecodeError`, a `ClientError` subclass — so `except httpware.ClientError` covers them alongside transport and status errors.
+Typed decoding via `response_model=` works in both worlds — install either `pip install httpware[pydantic]` or `pip install httpware[msgspec]` (or both; pydantic is tried first when both are present). Decode failures (malformed body, schema mismatch) raise `httpware.DecodeError`, a `ClientError` subclass — so `except httpware.ClientError` covers them alongside transport and status errors.
 
 ```python
 from httpware import AsyncClient
@@ -88,7 +89,7 @@ async def main() -> None:
         user = await client.get("/users/1", response_model=User)
 ```
 
-Need a custom middleware (auth, tracing, request-ID propagation, etc.)? See the [Middleware guide](docs/middleware.md).
+Need a custom middleware (auth, tracing, request-ID propagation, etc.)? See the [Middleware guide](https://httpware.modern-python.org/middleware/).
 
 ### Streaming responses
 
@@ -135,11 +136,13 @@ pip install httpware[otel]
 
 When installed, `_emit_event` calls `trace.get_current_span().add_event(name, attributes=...)` automatically. We never create our own spans; for HTTP-level tracing install `opentelemetry-instrumentation-httpx` separately.
 
+## 📚 [Documentation](https://httpware.modern-python.org)
+
 ## 🗒️ [Release notes](https://github.com/modern-python/httpware/releases)
 
 ## 📦 [PyPI](https://pypi.org/project/httpware)
 
-## 📝 [License](./LICENSE)
+## 📝 [License](https://github.com/modern-python/httpware/blob/main/LICENSE)
 
 ## Part of `modern-python`
 

{httpware-0.8.6 → httpware-0.9.1}/pyproject.toml

@@ -26,7 +26,7 @@ classifiers = [
     "Topic :: Internet :: WWW/HTTP",
     "Framework :: AsyncIO",
 ]
-version = "0.8.6"
+version = "0.9.1"
 dependencies = [
     "httpx2>=2.0.0,<3.0",
 ]
@@ -39,7 +39,7 @@ all = ["httpware[pydantic,msgspec,otel]"]
 
 [project.urls]
 repository = "https://github.com/modern-python/httpware"
-docs = "https://httpware.readthedocs.io"
+docs = "https://httpware.modern-python.org"
 
 [build-system]
 requires = ["uv_build>=0.11,<1.0"]

{httpware-0.8.6 → httpware-0.9.1}/src/httpware/__init__.py

@@ -12,6 +12,7 @@ from httpware.errors import (
     DecodeError,
     ForbiddenError,
     InternalServerError,
+    MissingDecoderError,
     NetworkError,
     NotFoundError,
     RateLimitedError,
@@ -57,6 +58,7 @@ __all__ = [
     "ForbiddenError",
     "InternalServerError",
     "Middleware",
+    "MissingDecoderError",
     "NetworkError",
     "Next",
     "NotFoundError",

{httpware-0.8.6 → httpware-0.9.1}/src/httpware/client.py

@@ -16,7 +16,7 @@ from httpware._internal.status import (
     _raise_on_status_error,
 )
 from httpware.decoders import ResponseDecoder
-from httpware.errors import DecodeError, TransportError
+from httpware.errors import DecodeError, MissingDecoderError, TransportError
 from httpware.middleware import AsyncMiddleware, AsyncNext, Middleware, Next
 from httpware.middleware.chain import compose, compose_async
 
@@ -30,19 +30,26 @@ _HTTPX2_CLIENT_CONFLICT_MESSAGE = (
     f"{_FORWARDED_KWARG_NAMES}; configure the httpx2 client you pass instead."
 )
 
-_DEFAULT_DECODER_MISSING_MESSAGE = (
-    "decoder=None defaults to PydanticDecoder, which requires the "
-    "'pydantic' extra. Either install it (`pip install httpware[pydantic]`) or "
-    "pass an explicit decoder=..."
-)
 
+def _build_default_decoders() -> tuple[ResponseDecoder, ...]:
+    """Construct the default decoder tuple based on installed extras.
+
+    Pydantic-first when both extras are present; either-only when only one is
+    installed; empty tuple when neither is installed. Imports the concrete
+    decoder modules lazily so missing extras never trip `find_spec`-guarded
+    import paths. Called by `AsyncClient.__init__` and `Client.__init__` when
+    `decoders=None` (the default).
+    """
+    decoders: list[ResponseDecoder] = []
+    if import_checker.is_pydantic_installed:
+        from httpware.decoders.pydantic import PydanticDecoder  # noqa: PLC0415 — lazy by design (Seam C)
 
-def _default_pydantic_decoder() -> ResponseDecoder:
-    if not import_checker.is_pydantic_installed:
-        raise ImportError(_DEFAULT_DECODER_MISSING_MESSAGE)
-    from httpware.decoders.pydantic import PydanticDecoder  # noqa: PLC0415 — lazy by design
+        decoders.append(PydanticDecoder())
+    if import_checker.is_msgspec_installed:
+        from httpware.decoders.msgspec import MsgspecDecoder  # noqa: PLC0415 — lazy by design (Seam C)
 
-    return PydanticDecoder()
+        decoders.append(MsgspecDecoder())
+    return tuple(decoders)
 
 
 @contextlib.asynccontextmanager
@@ -72,7 +79,7 @@ class AsyncClient:
 
     _httpx2_client: httpx2.AsyncClient
     _owns_client: bool
-    _decoder: ResponseDecoder
+    _decoders: tuple[ResponseDecoder, ...]
     _user_middleware: tuple[AsyncMiddleware, ...]
     _dispatch: AsyncNext
 
@@ -87,7 +94,7 @@ class AsyncClient:
         limits: httpx2.Limits | None = None,
         auth: httpx2.Auth | None = None,
         httpx2_client: httpx2.AsyncClient | None = None,
-        decoder: ResponseDecoder | None = None,
+        decoders: Sequence[ResponseDecoder] | None = None,
         middleware: Sequence[AsyncMiddleware] = (),
     ) -> None:
         if httpx2_client is not None:
@@ -123,10 +130,17 @@ class AsyncClient:
             self._httpx2_client = httpx2.AsyncClient(**kwargs)
             self._owns_client = True
 
-        self._decoder = decoder if decoder is not None else _default_pydantic_decoder()
+        self._decoders = tuple(decoders) if decoders is not None else _build_default_decoders()
         self._user_middleware = tuple(middleware)
         self._dispatch = compose_async(self._user_middleware, self._terminal)
 
+    def _dispatch_decoder(self, model: type) -> ResponseDecoder | None:
+        """Walk `_decoders` and return the first decoder claiming `model`, or None."""
+        for decoder in self._decoders:
+            if decoder.can_decode(model):
+                return decoder
+        return None
+
     async def _terminal(self, request: httpx2.Request) -> httpx2.Response:
         try:
             async with _httpx2_exception_mapper():
@@ -151,11 +165,19 @@ class AsyncClient:
         response_model: type[T] | None = None,
     ) -> httpx2.Response | T:
         """Send `request` through the middleware chain. Decode if `response_model` is set."""
-        response = await self._dispatch(request)
         if response_model is None:
-            return response
+            return await self._dispatch(request)
+
+        decoder = self._dispatch_decoder(response_model)
+        if decoder is None:
+            raise MissingDecoderError(
+                model=response_model,
+                registered_names=tuple(type(d).__name__ for d in self._decoders),
+            )
+
+        response = await self._dispatch(request)
         try:
-            return self._decoder.decode(response.content, response_model)
+            return decoder.decode(response.content, response_model)
         except Exception as exc:
             raise DecodeError(response=response, model=response_model, original=exc) from exc
 
@@ -174,9 +196,16 @@ class AsyncClient:
         Not for streaming responses — decodes ``response.content``, which
         requires the body to be fully read. Use ``stream()`` for streaming.
         """
+        decoder = self._dispatch_decoder(response_model)
+        if decoder is None:
+            raise MissingDecoderError(
+                model=response_model,
+                registered_names=tuple(type(d).__name__ for d in self._decoders),
+            )
+
         response = await self._dispatch(request)
         try:
-            decoded = self._decoder.decode(response.content, response_model)
+            decoded = decoder.decode(response.content, response_model)
         except Exception as exc:
             raise DecodeError(response=response, model=response_model, original=exc) from exc
         return response, decoded
@@ -790,7 +819,7 @@ class Client:
 
     _httpx2_client: httpx2.Client
     _owns_client: bool
-    _decoder: ResponseDecoder
+    _decoders: tuple[ResponseDecoder, ...]
     _user_middleware: tuple[Middleware, ...]
     _dispatch: Next
 
@@ -805,7 +834,7 @@ class Client:
         limits: httpx2.Limits | None = None,
         auth: httpx2.Auth | None = None,
         httpx2_client: httpx2.Client | None = None,
-        decoder: ResponseDecoder | None = None,
+        decoders: Sequence[ResponseDecoder] | None = None,
         middleware: Sequence[Middleware] = (),
     ) -> None:
         if httpx2_client is not None:
@@ -841,10 +870,17 @@ class Client:
             self._httpx2_client = httpx2.Client(**kwargs)
             self._owns_client = True
 
-        self._decoder = decoder if decoder is not None else _default_pydantic_decoder()
+        self._decoders = tuple(decoders) if decoders is not None else _build_default_decoders()
         self._user_middleware = tuple(middleware)
         self._dispatch = compose(self._user_middleware, self._terminal)
 
+    def _dispatch_decoder(self, model: type) -> ResponseDecoder | None:
+        """Walk `_decoders` and return the first decoder claiming `model`, or None."""
+        for decoder in self._decoders:
+            if decoder.can_decode(model):
+                return decoder
+        return None
+
     def _terminal(self, request: httpx2.Request) -> httpx2.Response:
         try:
             with _httpx2_exception_mapper_sync():
@@ -893,11 +929,19 @@ class Client:
         response_model: type[T] | None = None,
     ) -> httpx2.Response | T:
         """Send `request` through the middleware chain. Decode if `response_model` is set."""
-        response = self._dispatch(request)
         if response_model is None:
-            return response
+            return self._dispatch(request)
+
+        decoder = self._dispatch_decoder(response_model)
+        if decoder is None:
+            raise MissingDecoderError(
+                model=response_model,
+                registered_names=tuple(type(d).__name__ for d in self._decoders),
+            )
+
+        response = self._dispatch(request)
         try:
-            return self._decoder.decode(response.content, response_model)
+            return decoder.decode(response.content, response_model)
         except Exception as exc:
             raise DecodeError(response=response, model=response_model, original=exc) from exc
 
@@ -916,9 +960,16 @@ class Client:
         Not for streaming responses — decodes ``response.content``, which
         requires the body to be fully read. Use ``stream()`` for streaming.
         """
+        decoder = self._dispatch_decoder(response_model)
+        if decoder is None:
+            raise MissingDecoderError(
+                model=response_model,
+                registered_names=tuple(type(d).__name__ for d in self._decoders),
+            )
+
         response = self._dispatch(request)
         try:
-            decoded = self._decoder.decode(response.content, response_model)
+            decoded = decoder.decode(response.content, response_model)
         except Exception as exc:
             raise DecodeError(response=response, model=response_model, original=exc) from exc
         return response, decoded

httpware-0.9.1/src/httpware/decoders/__init__.py

@@ -0,0 +1,42 @@
+"""ResponseDecoder protocol — the Client/AsyncClient ↔ ResponseDecoder seam (Seam B)."""
+
+from typing import Protocol, TypeVar, runtime_checkable
+
+
+T = TypeVar("T")
+
+
+@runtime_checkable
+class ResponseDecoder(Protocol):
+    """Structural protocol every response-body decoder satisfies."""
+
+    def can_decode(self, model: type) -> bool:
+        """Return True iff this decoder claims responsibility for `model`.
+
+        The client walks its `_decoders` tuple in order and picks the first
+        decoder whose `can_decode` returns True. Implementations should claim
+        every model type they can actually handle — broad is correct, because
+        list ordering encodes the caller's preference for shared shapes.
+        Native types of another library (e.g. `PydanticDecoder` vs
+        `msgspec.Struct`) MUST be rejected.
+
+        `can_decode` MUST NOT raise. It runs at dispatch time — before the HTTP
+        call and outside the `DecodeError` wrap that protects `decode` — so an
+        exception here escapes the `ClientError` contract rather than being
+        translated. A decoder that cannot determine support for `model` must
+        return False (decline), not raise; the built-in decoders treat any
+        probe failure as False.
+        """
+        ...
+
+    def decode(self, content: bytes, model: type[T]) -> T:
+        """Decode `content` (raw response bytes) into an instance of `model`.
+
+        Any exception raised by `decode` is wrapped by `Client.send` /
+        `AsyncClient.send` into `httpware.DecodeError`; implementers do not
+        need to raise `DecodeError` directly.
+        """
+        ...
+
+
+__all__ = ["ResponseDecoder"]

httpware-0.9.1/src/httpware/decoders/msgspec.py

@@ -0,0 +1,116 @@
+"""MsgspecDecoder — opt-in ResponseDecoder backed by a per-instance msgspec.json.Decoder cache."""
+
+import typing
+from typing import TypeVar
+
+from httpware._internal import import_checker
+
+
+if import_checker.is_msgspec_installed:
+    import msgspec
+
+
+MISSING_DEPENDENCY_MESSAGE = "MsgspecDecoder requires the 'msgspec' extra. Install with: pip install httpware[msgspec]"
+
+T = TypeVar("T")
+
+
+def _contains_custom_type(info: "msgspec.inspect.Type") -> bool:
+    """Return True if `info` is a CustomType or nests one in its parameters.
+
+    Walks generic-container parameterization (list/dict/set/tuple/union element
+    types) by visiting any attribute that is itself a `msgspec.inspect.Type` or a
+    tuple of them. It deliberately does NOT descend into `StructType`/dataclass
+    fields: those expose `fields` as `Field` objects (not `Type`), so the walk
+    stops at the boundary of a type msgspec natively owns. That boundary is what
+    makes the walk both correct (a Struct is a valid target) and safe against
+    infinite recursion on self-referential struct definitions.
+    """
+    if isinstance(info, msgspec.inspect.CustomType):
+        return True
+    for name in dir(info):
+        if name.startswith("_"):
+            continue
+        value = getattr(info, name, None)
+        if isinstance(value, msgspec.inspect.Type):
+            if _contains_custom_type(value):
+                return True
+        elif (
+            isinstance(value, tuple)
+            and value
+            and all(isinstance(item, msgspec.inspect.Type) for item in value)
+            and any(_contains_custom_type(item) for item in value)
+        ):
+            return True
+    return False
+
+
+class MsgspecDecoder:
+    """Decode raw response bytes via a per-instance cached `msgspec.json.Decoder(model)`.
+
+    Requires the `msgspec` extra: `pip install httpware[msgspec]`. Importing
+    this module without the extra works (the `msgspec` import is guarded by a
+    `find_spec` check), but instantiating the decoder raises `ImportError`.
+    """
+
+    _msgspec_decoders: dict[type, "msgspec.json.Decoder[typing.Any]"]
+    _can_decode_results: dict[type, bool]
+
+    def __init__(self) -> None:
+        if not import_checker.is_msgspec_installed:
+            raise ImportError(MISSING_DEPENDENCY_MESSAGE)
+        self._msgspec_decoders = {}
+        self._can_decode_results = {}
+
+    def _get_msgspec_decoder(self, model: type[T]) -> "msgspec.json.Decoder[T]":
+        decoder = self._msgspec_decoders.get(model)
+        if decoder is None:
+            decoder = msgspec.json.Decoder(model)
+            self._msgspec_decoders[model] = decoder
+        return decoder
+
+    def can_decode(self, model: type) -> bool:
+        """Return True iff msgspec natively understands `model` end-to-end.
+
+        The verdict is memoized per `model`: the probe below (an uncached
+        `type_info` call plus a recursive tree walk) runs once per type, not on
+        every dispatch. Unhashable models skip the cache and probe fresh.
+        """
+        try:
+            cached = self._can_decode_results.get(model)
+        except TypeError:  # unhashable model — can't memoize, probe fresh
+            return self._probe_can_decode(model)
+        if cached is not None:
+            return cached
+        result = self._probe_can_decode(model)
+        self._can_decode_results[model] = result
+        return result
+
+    def _probe_can_decode(self, model: type) -> bool:
+        """Decide whether msgspec natively decodes `model` (the uncached path).
+
+        msgspec builds a Decoder for almost any class via a generic CustomType
+        fallback; the Decoder constructor does NOT raise on unsupported types
+        (e.g. pydantic.BaseModel, or a container parameterized by one). We walk
+        msgspec.inspect.type_info and reject if a CustomType appears anywhere in
+        the type tree, so MissingDecoderError fires before a request is sent.
+        """
+        try:
+            info = msgspec.inspect.type_info(model)
+        except Exception:  # noqa: BLE001 — can_decode is a probe; any failure means no
+            return False
+        if _contains_custom_type(info):
+            return False
+        try:
+            self._get_msgspec_decoder(model)
+        except Exception:  # noqa: BLE001 — can_decode is a probe; any failure means no
+            return False
+        return True
+
+    def decode(self, content: bytes, model: type[T]) -> T:
+        """Validate `content` as JSON against `model` in a single parse pass."""
+        try:
+            decoder = self._get_msgspec_decoder(model)
+        except TypeError:
+            decoder = msgspec.json.Decoder(model)
+        return decoder.decode(content)

httpware-0.9.1/src/httpware/decoders/pydantic.py

@@ -0,0 +1,81 @@
+"""PydanticDecoder — ResponseDecoder backed by per-instance TypeAdapter cache.
+
+Requires the `pydantic` extra: `pip install httpware[pydantic]`. Constructing
+`PydanticDecoder()` directly when pydantic is not installed raises ImportError.
+The default-decoder path in `client.py:_build_default_decoders()` skips this
+class entirely when `is_pydantic_installed` is False, so `AsyncClient()` does
+not trip the ImportError when the user is not using `response_model=`.
+"""
+
+import typing
+from typing import TypeVar
+
+from pydantic import TypeAdapter
+
+from httpware._internal import import_checker
+
+
+MISSING_DEPENDENCY_MESSAGE = (
+    "PydanticDecoder requires the 'pydantic' extra. Install with: pip install httpware[pydantic]"
+)
+
+T = TypeVar("T")
+
+
+class PydanticDecoder:
+    """Decode raw response bytes into `model` via a per-instance cached `pydantic.TypeAdapter`."""
+
+    _adapters: dict[type, TypeAdapter[typing.Any]]
+    _can_decode_results: dict[type, bool]
+
+    def __init__(self) -> None:
+        if not import_checker.is_pydantic_installed:
+            raise ImportError(MISSING_DEPENDENCY_MESSAGE)
+        self._adapters = {}
+        self._can_decode_results = {}
+
+    def _get_adapter(self, model: type[T]) -> "TypeAdapter[T]":
+        adapter = self._adapters.get(model)
+        if adapter is None:
+            adapter = TypeAdapter(model)
+            self._adapters[model] = adapter
+        return adapter
+
+    def can_decode(self, model: type) -> bool:
+        """Return True iff pydantic can build a schema for `model`.
+
+        The verdict is memoized per `model` so a rejection (which costs a
+        `PydanticSchemaGenerationError` round-trip) is not re-probed on every
+        dispatch. Unhashable models skip the cache and probe fresh.
+        """
+        try:
+            cached = self._can_decode_results.get(model)
+        except TypeError:  # unhashable model — can't memoize, probe fresh
+            return self._probe_can_decode(model)
+        if cached is not None:
+            return cached
+        result = self._probe_can_decode(model)
+        self._can_decode_results[model] = result
+        return result
+
+    def _probe_can_decode(self, model: type) -> bool:
+        """Decide whether pydantic can build a schema for `model` (uncached).
+
+        Probes via `_get_adapter`; subsequent calls (including `decode`) reuse
+        the cached `TypeAdapter`. Rejects `msgspec.Struct` subclasses —
+        pydantic raises `PydanticSchemaGenerationError` (a `TypeError`) when
+        building a schema for them.
+        """
+        try:
+            self._get_adapter(model)
+        except Exception:  # noqa: BLE001 — can_decode is a probe; any failure means no
+            return False
+        return True
+
+    def decode(self, content: bytes, model: type[T]) -> T:
+        """Validate `content` as JSON against `model` in a single parse pass."""
+        try:
+            adapter = self._get_adapter(model)
+        except TypeError:
+            adapter = TypeAdapter(model)
+        return adapter.validate_json(content)

{httpware-0.8.6 → httpware-0.9.1}/src/httpware/errors.py

@@ -254,3 +254,43 @@ class DecodeError(ClientError):
             _reconstruct_decode_error,
             (type(self), self.response, self.model, self.original),
         )
+
+
+def _missing_decoder_summary(model: type, registered_names: tuple[str, ...]) -> str:
+    if not registered_names:
+        hint = (
+            "no decoders registered. Install `pip install httpware[pydantic]` "
+            "or `pip install httpware[msgspec]`, or pass decoders=[...] explicitly."
+        )
+    else:
+        joined = " + ".join(registered_names)
+        hint = f"registered decoders ({joined}) all rejected it. Pass a custom decoder via decoders=[...]."
+    return f"no decoder for response_model={model!r}: {hint}"
+
+
+def _reconstruct_missing_decoder(
+    cls: "type[MissingDecoderError]",
+    model: type,
+    registered_names: tuple[str, ...],
+) -> "MissingDecoderError":
+    return cls(model=model, registered_names=registered_names)
+
+
+class MissingDecoderError(ClientError):
+    """Raised when response_model= is set but no registered decoder claims the model.
+
+    Fires at .send() entry, BEFORE the HTTP call — no point sending a request
+    whose response cannot be decoded. Distinct from DecodeError, which means
+    the decoder ran and the payload was malformed.
+    """
+
+    model: type
+    registered_names: tuple[str, ...]
+
+    def __init__(self, *, model: type, registered_names: tuple[str, ...]) -> None:
+        self.model = model
+        self.registered_names = registered_names
+        super().__init__(_missing_decoder_summary(model, registered_names))
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        return (_reconstruct_missing_decoder, (type(self), self.model, self.registered_names))

httpware-0.8.6/src/httpware/decoders/__init__.py

@@ -1,23 +0,0 @@
-"""ResponseDecoder protocol — the Client/AsyncClient ↔ ResponseDecoder seam (Seam B)."""
-
-from typing import Protocol, TypeVar, runtime_checkable
-
-
-T = TypeVar("T")
-
-
-@runtime_checkable
-class ResponseDecoder(Protocol):
-    """Structural protocol every response-body decoder satisfies."""
-
-    def decode(self, content: bytes, model: type[T]) -> T:
-        """Decode `content` (raw response bytes) into an instance of `model`.
-
-        Any exception raised by `decode` is wrapped by `Client.send` /
-        `AsyncClient.send` into `httpware.DecodeError`; implementers do not
-        need to raise `DecodeError` directly.
-        """
-        ...
-
-
-__all__ = ["ResponseDecoder"]

httpware-0.8.6/src/httpware/decoders/msgspec.py

@@ -1,32 +0,0 @@
-"""MsgspecDecoder — opt-in ResponseDecoder backed by msgspec.json.decode."""
-
-from typing import TypeVar
-
-from httpware._internal import import_checker
-
-
-if import_checker.is_msgspec_installed:
-    import msgspec
-
-
-MISSING_DEPENDENCY_MESSAGE = "MsgspecDecoder requires the 'msgspec' extra. Install with: pip install httpware[msgspec]"
-
-T = TypeVar("T")
-
-
-class MsgspecDecoder:
-    """Decode raw response bytes via `msgspec.json.decode(content, type=model)`.
-
-    Requires the `msgspec` extra: `pip install httpware[msgspec]`. Importing
-    this module without the extra works (the `msgspec` import is guarded by a
-    `find_spec` check), but instantiating the decoder raises `ImportError` with
-    the install hint.
-    """
-
-    def __init__(self) -> None:
-        if not import_checker.is_msgspec_installed:
-            raise ImportError(MISSING_DEPENDENCY_MESSAGE)
-
-    def decode(self, content: bytes, model: type[T]) -> T:
-        """Validate `content` as JSON against `model` in a single parse pass."""
-        return msgspec.json.decode(content, type=model)

httpware-0.8.6/src/httpware/decoders/pydantic.py

@@ -1,45 +0,0 @@
-"""PydanticDecoder — module-level cached TypeAdapter adapter for ResponseDecoder.
-
-Requires the `pydantic` extra: `pip install httpware[pydantic]`. The optional-extras
-gate is enforced upstream — `client.py:_default_pydantic_decoder()` raises
-ImportError when pydantic is absent, so this module is never imported in that
-path. Tests simulating "pydantic not installed" patch
-`import_checker.is_pydantic_installed=False` at runtime, after this module is
-already loaded; `PydanticDecoder.__init__` then raises ImportError with the
-install hint.
-"""
-
-import functools
-from typing import TypeVar
-
-from pydantic import TypeAdapter
-
-from httpware._internal import import_checker
-
-
-MISSING_DEPENDENCY_MESSAGE = (
-    "PydanticDecoder requires the 'pydantic' extra. Install with: pip install httpware[pydantic]"
-)
-
-T = TypeVar("T")
-
-
-@functools.lru_cache(maxsize=1024)
-def _get_adapter(model: type[T]) -> "TypeAdapter[T]":
-    return TypeAdapter(model)
-
-
-class PydanticDecoder:
-    """Decode raw response bytes into `model` via a cached `pydantic.TypeAdapter`."""
-
-    def __init__(self) -> None:
-        if not import_checker.is_pydantic_installed:
-            raise ImportError(MISSING_DEPENDENCY_MESSAGE)
-
-    def decode(self, content: bytes, model: type[T]) -> T:
-        """Validate `content` as JSON against `model` in a single parse pass."""
-        try:
-            adapter = _get_adapter(model)
-        except TypeError:
-            adapter = TypeAdapter(model)
-        return adapter.validate_json(content)