feat(client)!: sync Client takes decoders=[...] with type-dispatched routing

Author: lesnik512

src/httpware/client.py

@@ -30,20 +30,6 @@
     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 _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
-
-    return PydanticDecoder()
-
 
 def _build_default_decoders() -> tuple[ResponseDecoder, ...]:
     """Construct the default decoder tuple based on installed extras.
@@ -833,7 +819,7 @@ class Client:
 
     _httpx2_client: httpx2.Client
     _owns_client: bool
-    _decoder: ResponseDecoder
+    _decoders: tuple[ResponseDecoder, ...]
     _user_middleware: tuple[Middleware, ...]
     _dispatch: Next
 
@@ -848,7 +834,7 @@ def __init__(  # noqa: PLR0913 — wide constructor is the cost of a single-call
         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:
@@ -884,10 +870,17 @@ def __init__(  # noqa: PLR0913 — wide constructor is the cost of a single-call
             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():
@@ -936,11 +929,19 @@ def send(
         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
 
@@ -959,9 +960,16 @@ def send_with_response(
         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

src/httpware/decoders/pydantic.py

@@ -1,12 +1,10 @@
 """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.
+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 functools

tests/test_client_send_with_response_sync.py

@@ -6,7 +6,7 @@
 import pydantic
 import pytest
 
-from httpware import Client, ClientError, DecodeError, NotFoundError
+from httpware import Client, ClientError, DecodeError, MissingDecoderError, NotFoundError
 from httpware.middleware import before_request
 
 
@@ -128,3 +128,22 @@ def handler(request: httpx2.Request) -> httpx2.Response:
     response, _ = client.send_with_response(request, response_model=_User)
     assert recorded[0].headers.get("x-test") == "ok"
     assert response.request.headers.get("x-test") == "ok"
+
+
+def test_sync_send_with_response_raises_missing_decoder_before_http_call() -> None:
+    def handler(_: httpx2.Request) -> httpx2.Response:  # pragma: no cover
+        pytest.fail("transport should not be invoked when MissingDecoderError fires")
+
+    transport = httpx2.MockTransport(handler)
+    client = Client(
+        httpx2_client=httpx2.Client(transport=transport),
+        decoders=[],
+    )
+
+    class _Foo:
+        pass
+
+    request = client.build_request("GET", "https://example.test/x")
+    with pytest.raises(MissingDecoderError):
+        client.send_with_response(request, response_model=_Foo)
+    client.close()

tests/test_client_sync.py

@@ -8,7 +8,7 @@
 
 from httpware import Client, NotFoundError
 from httpware.decoders.pydantic import PydanticDecoder
-from httpware.errors import TransportError
+from httpware.errors import MissingDecoderError, TransportError
 
 
 # ---------- Construction ----------
@@ -59,22 +59,49 @@ def test_caller_owned_client_with_forwarded_kwargs_is_typeerror(kwargs: dict) ->
     caller.close()
 
 
-def test_default_decoder_is_pydantic_decoder() -> None:
+def test_default_decoders_includes_pydantic_when_installed() -> None:
     client = Client()
-    assert isinstance(client._decoder, PydanticDecoder)  # noqa: SLF001
+    assert any(isinstance(d, PydanticDecoder) for d in client._decoders)  # noqa: SLF001
     client.close()
 
 
-def test_explicit_decoder_is_honored() -> None:
+def test_explicit_decoders_is_honored() -> None:
     class _Stub:
         def can_decode(self, model: type) -> bool:  # noqa: ARG002  # pragma: no cover
             return True
 
         def decode(self, content: bytes, model: type) -> object:  # noqa: ARG002  # pragma: no cover
             return None
 
-    client = Client(decoder=_Stub())
-    assert isinstance(client._decoder, _Stub)  # noqa: SLF001
+    stub = _Stub()
+    client = Client(decoders=[stub])
+    assert client._decoders == (stub,)  # noqa: SLF001
+    client.close()
+
+
+def test_empty_decoders_is_honored() -> None:
+    client = Client(decoders=[])
+    assert client._decoders == ()  # noqa: SLF001
+    client.close()
+
+
+def test_sync_missing_decoder_raised_before_http_call() -> None:
+    def handler(_: httpx2.Request) -> httpx2.Response:  # pragma: no cover
+        pytest.fail("transport should not be invoked when MissingDecoderError fires")
+
+    transport = httpx2.MockTransport(handler)
+    client = Client(
+        httpx2_client=httpx2.Client(transport=transport),
+        decoders=[],
+    )
+
+    class _Foo:
+        pass
+
+    with pytest.raises(MissingDecoderError) as exc_info:
+        client.get("https://example.test/x", response_model=_Foo)
+    assert exc_info.value.model is _Foo
+    assert exc_info.value.registered_names == ()
     client.close()
 
 

tests/test_optional_extras_pydantic_missing.py

@@ -39,12 +39,12 @@ def test_async_client_no_pydantic_constructs_without_raising() -> None:
     assert all(not isinstance(d, PydanticDecoder) for d in client._decoders)  # noqa: SLF001
 
 
-def test_sync_client_default_decoder_raises_when_pydantic_missing() -> None:
-    with (
-        patch("httpware._internal.import_checker.is_pydantic_installed", False),
-        pytest.raises(ImportError, match=r"httpware\[pydantic\]"),
-    ):
-        Client()
+def test_sync_client_no_pydantic_constructs_without_raising() -> None:
+    """Client() with pydantic missing must not raise — lazy default policy."""
+    with patch("httpware._internal.import_checker.is_pydantic_installed", False):
+        client = Client()
+    assert all(not isinstance(d, PydanticDecoder) for d in client._decoders)  # noqa: SLF001
+    client.close()
 
 
 def test_async_client_accepts_explicit_decoders_without_pydantic() -> None:
@@ -55,9 +55,9 @@ def test_async_client_accepts_explicit_decoders_without_pydantic() -> None:
     assert client._decoders == (fake,)  # noqa: SLF001
 
 
-def test_sync_client_accepts_explicit_decoder_without_pydantic() -> None:
-    """Sync mirror: explicit decoder= escapes the fail-fast AND is wired for sync Client too."""
+def test_sync_client_accepts_explicit_decoders_without_pydantic() -> None:
     fake = _FakeDecoder()
     with patch("httpware._internal.import_checker.is_pydantic_installed", False):
-        client = Client(decoder=fake)
-    assert client._decoder is fake  # noqa: SLF001 — wired the explicit decoder, not a default
+        client = Client(decoders=[fake])
+    assert client._decoders == (fake,)  # noqa: SLF001
+    client.close()