Skip to content

Commit 0b349b2

Browse files
authored
refactor(errors): collapse per-exception reconstruct/reduce boilerplate
Collapses 6 hand-duplicated _reconstruct_X + __reduce__ pairs in errors.py (RetryBudgetExhaustedError, BulkheadFullError, CircuitOpenError, DecodeError, MissingDecoderError, ResponseTooLargeError) into one shared _KeywordReduceMixin + _reconstruct_kwonly function. Deliberately not applied to ClientError itself, which would silently break pickling for TransportError/NetworkError/TimeoutError. StatusError's own reduce mechanism stays untouched. No test changes — the 6 existing pickle round-trip tests already exercise the shared mixin and verify unpickling. Design: planning/changes/2026-07-13.03-errors-keyword-reduce-mixin.md
1 parent 7705fc8 commit 0b349b2

3 files changed

Lines changed: 183 additions & 85 deletions

File tree

‎architecture/errors.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@ The error-mapping table (what `httpx2` exception maps to which `httpware` except
1818

1919
The "no `__init__` override" rule scopes only to `StatusError` subclasses. Non-status `ClientError` subclasses — `DecodeError`, `MissingDecoderError`, `BulkheadFullError`, `RetryBudgetExhaustedError`, `CircuitOpenError`, `ResponseTooLargeError` — deliberately define `__init__` with keyword-only fields.
2020

21+
These six non-status `ClientError` subclasses inherit `__reduce__` from `_KeywordReduceMixin`, which pickles via `self.__dict__` and reconstructs via `cls(**kwargs)`. This requires `self.__dict__` to exactly mirror the `__init__` keyword parameters: an attribute stored beyond those parameters raises `TypeError` on unpickle (unexpected keyword argument), and a keyword parameter `__init__` doesn't assign to `self` is silently dropped if it has a default (unpickle reverts to it) or raises `TypeError` if it doesn't.
22+
2123
`ResponseTooLargeError` is raised when `max_response_body_bytes` is set and a response body would exceed the cap — status-agnostic (a `200` can trip it), counting **decoded** bytes. It fires from the non-streaming terminal (`send()`) and from `stream()`'s internal error pre-read; user-driven `stream()` iteration is never capped. The `reason` field discriminates the two trip modes: `"declared"` (the declared `Content-Length` already exceeds the cap, rejected before any byte is read — `content_length` holds it) and `"streamed"` (the decoded body crossed the cap mid-read, the chunked or compression-bomb case, where the true size is unknown by design). It is a non-status `ClientError`; it does not carry a `StatusError`-style positional `response` and is not in `STATUS_TO_EXCEPTION`. Because it is neither a `StatusError`, `NetworkError`, nor `TimeoutError`, it is not retried and does not count toward the circuit breaker.
2224

2325
## Security: request headers are reachable via `exc.response.request`
Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
---
2+
summary: Collapse the 6 hand-duplicated reconstruct-function + __reduce__ pairs in errors.py into one shared _KeywordReduceMixin.
3+
---
4+
5+
# Design: Collapse errors.py's per-exception reconstruct/reduce boilerplate
6+
7+
## Summary
8+
9+
Six non-status `ClientError` subclasses (`RetryBudgetExhaustedError`,
10+
`BulkheadFullError`, `CircuitOpenError`, `DecodeError`,
11+
`MissingDecoderError`, `ResponseTooLargeError`) each hand-repeat a
12+
module-level `_reconstruct_X` function plus a `__reduce__` method, purely
13+
because their keyword-only `__init__` signatures are incompatible with
14+
`BaseException`'s default `__reduce__` (`cls(*self.args)`). This change
15+
replaces all six pairs with one shared `_KeywordReduceMixin`, added to
16+
each of the six classes' bases, plus one shared `_reconstruct_kwonly`
17+
function. No behavior change.
18+
19+
## Motivation
20+
21+
- The six `_reconstruct_X`/`__reduce__` pairs (`errors.py:139-145+171-175`,
22+
`178-183+200-204`, `207-211+232-234`, `236-242+271-275`,
23+
`290-295+314-315`, `318-325+366-370`) are structurally identical —
24+
only field names/counts differ. ~25-30 lines repeated six times for one
25+
mechanism.
26+
- **Verified precondition:** for every one of the six classes, the
27+
instance `__dict__` after `__init__` contains *exactly* the keyword-only
28+
`__init__` parameters, nothing derived or extra — confirmed by reading
29+
each `__init__` body. This makes a fully generic
30+
`self.__dict__`-based reconstruction (`cls(**kwargs)`) behaviorally
31+
identical to each class's current bespoke reduce.
32+
- **Deletion test:** delete the shared mixin and all six classes lose
33+
picklability identically — one concern wearing six costumes, not six
34+
independent concerns.
35+
36+
## Non-goals
37+
38+
- No behavior change. Pickling output, `__cause__`/message reconstruction,
39+
and every existing pickle-round-trip test in `tests/test_errors.py`
40+
stay green unchanged — no test file edits in this change.
41+
- **Not touching `ClientError` itself.** A blanket `self.__dict__`-based
42+
`__reduce__` on the root `ClientError` was considered and rejected:
43+
`TransportError`/`NetworkError`/`TimeoutError` have no custom `__init__`
44+
(plain `Exception(message)` construction — the message lives in
45+
`self.args`, and `self.__dict__` is empty for them). A root-level
46+
generic `__reduce__` would silently break their pickling by
47+
reconstructing them with no arguments. The mixin is applied only to the
48+
six classes whose `__dict__`-mirrors-`__init__` precondition actually
49+
holds.
50+
- **Not touching `StatusError`.** Its `_reconstruct_status_error` +
51+
`__reduce__` pair is a different, single, already-shared mechanism
52+
(positional `response` arg, one function serving every `StatusError`
53+
subclass via inheritance) — already fine, out of scope.
54+
- **Not adding new tests.** The six existing pickle-round-trip tests
55+
already exercise the shared mixin directly (each round-trips through
56+
the real `__reduce__` → `_reconstruct_kwonly` → `cls(**kwargs)` path)
57+
across varied field-counts (1 field for `CircuitOpenError`, up to 4 for
58+
`ResponseTooLargeError`). A synthetic dedicated mixin test would only
59+
re-prove what six real classes already prove.
60+
61+
## Design
62+
63+
### 1. `_KeywordReduceMixin` + `_reconstruct_kwonly`
64+
65+
Added to `errors.py`, placed immediately before `RetryBudgetExhaustedError`
66+
(replacing where `_reconstruct_budget_exhausted` currently starts the
67+
block of six classes):
68+
69+
```python
70+
def _reconstruct_kwonly(cls: type, kwargs: dict[str, Any]) -> Any:
71+
return cls(**kwargs)
72+
73+
74+
class _KeywordReduceMixin:
75+
"""Shared __reduce__ for ClientError subclasses whose __init__ is
76+
keyword-only and whose instance __dict__ exactly mirrors it.
77+
78+
Do not add this mixin to a class that stores any attribute beyond its
79+
__init__'s keyword parameters — reconstruction replays self.__dict__
80+
as keyword arguments, so an extra/derived attribute would either be
81+
silently dropped or raise a TypeError on unpickle.
82+
"""
83+
84+
def __reduce__(self) -> tuple[Any, ...]:
85+
return (_reconstruct_kwonly, (type(self), self.__dict__))
86+
```
87+
88+
### 2. Each of the six classes
89+
90+
Add `_KeywordReduceMixin` as the first base, remove the class's own
91+
`_reconstruct_X` function and `__reduce__` method. `__init__` bodies are
92+
otherwise unchanged. Example (`BulkheadFullError`):
93+
94+
```python
95+
class BulkheadFullError(_KeywordReduceMixin, ClientError):
96+
"""Raised when ``acquire_timeout`` elapses before an AsyncBulkhead slot becomes available.
97+
98+
Carries the configured caps for caller logging/alerting.
99+
"""
100+
101+
max_concurrent: int
102+
acquire_timeout: float | None
103+
104+
def __init__(self, *, max_concurrent: int, acquire_timeout: float | None) -> None:
105+
self.max_concurrent = max_concurrent
106+
self.acquire_timeout = acquire_timeout
107+
super().__init__(f"bulkhead full (max_concurrent={max_concurrent}, acquire_timeout={acquire_timeout})")
108+
```
109+
110+
(`_reconstruct_bulkhead_full` and `BulkheadFullError.__reduce__` deleted
111+
entirely.) The same transformation applies to `RetryBudgetExhaustedError`,
112+
`CircuitOpenError`, `DecodeError`, `MissingDecoderError`, and
113+
`ResponseTooLargeError` — mixin first in the bases tuple, `_reconstruct_X`
114+
function and `__reduce__` method deleted, `__init__` body unchanged.
115+
116+
### 3. Documentation
117+
118+
Add one sentence to `architecture/errors.md`, next to the existing
119+
`__init__`-divergence rule, so a future contributor adding a 7th kwonly
120+
`ClientError` subclass sees the constraint where they're already reading:
121+
122+
> Non-status `ClientError` subclasses with keyword-only `__init__` fields
123+
> inherit `__reduce__` from `_KeywordReduceMixin`, which pickles via
124+
> `self.__dict__`. This requires `self.__dict__` to exactly mirror the
125+
> `__init__` keyword parameters — do not store any additional derived
126+
> attribute on these classes without also updating `__init__`'s
127+
> parameters, or pickling will silently drop it.
128+
129+
## Testing
130+
131+
- **Parity net:** all six existing pickle-round-trip tests in
132+
`tests/test_errors.py` (`test_retry_budget_exhausted_error_pickleable`,
133+
`test_bulkhead_full_error_pickleable`, `test_decode_error_pickleable`,
134+
`test_missing_decoder_error_pickle_roundtrip`,
135+
`test_circuit_open_error_pickleable_with_float`/`_with_none`,
136+
`test_response_too_large_error_pickle_round_trip`) stay green with zero
137+
edits — byte-identical behavior is the bar.
138+
- `just lint && just test` both clean; 100% coverage maintained (the
139+
mixin's `__reduce__` and `_reconstruct_kwonly` are exercised by the six
140+
existing tests, so no coverage gap opens).
141+
142+
## Risk
143+
144+
- **A future kwonly subclass violates the mixin's precondition** (i.e.
145+
stores a derived attribute beyond its `__init__` params) — the
146+
documented risk this change explicitly calls out in both the mixin's
147+
own docstring and `architecture/errors.md`. *Mitigation:* the docstring
148+
and doc line are the guardrail; no automated check is added (matching
149+
this codebase's existing pattern of review-only invariants for
150+
errors.py, per `architecture/overview.md`'s enforcement table).
151+
- **MRO/inheritance concern** (unlikely × low): adding `_KeywordReduceMixin`
152+
as an additional base could theoretically interact with exception
153+
matching (`except ClientError:`) or `isinstance` checks. *Mitigation:*
154+
`_KeywordReduceMixin` inherits only from `object`; `ClientError` remains
155+
in every affected class's bases, so `isinstance`/`except` behavior is
156+
unchanged. The existing test suite's exception-type assertions
157+
(`test_errors.py`, `test_client_construction.py`, etc.) cover this net.

‎src/httpware/errors.py‎

Lines changed: 24 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -136,16 +136,27 @@ class ServiceUnavailableError(ServerStatusError):
136136
}
137137

138138

139-
def _reconstruct_budget_exhausted(
140-
cls: "type[RetryBudgetExhaustedError]",
141-
last_response: httpx2.Response | None,
142-
last_exception: BaseException | None,
143-
attempts: int,
144-
) -> "RetryBudgetExhaustedError":
145-
return cls(last_response=last_response, last_exception=last_exception, attempts=attempts)
139+
def _reconstruct_kwonly(cls: type, kwargs: dict[str, Any]) -> Any: # noqa: ANN401
140+
return cls(**kwargs)
146141

147142

148-
class RetryBudgetExhaustedError(ClientError):
143+
class _KeywordReduceMixin:
144+
"""Shared __reduce__ for keyword-only ClientError subclasses.
145+
146+
For subclasses whose __init__ is keyword-only and whose instance
147+
__dict__ exactly mirrors it. Reconstruction replays self.__dict__ as
148+
keyword arguments (cls(**kwargs)): an attribute stored beyond
149+
__init__'s keyword parameters raises TypeError on unpickle (unexpected
150+
keyword argument); a keyword parameter __init__ doesn't assign to self
151+
is silently dropped if it has a default (unpickle reverts to it) or
152+
raises TypeError if it doesn't (missing required argument).
153+
"""
154+
155+
def __reduce__(self) -> tuple[Any, ...]:
156+
return (_reconstruct_kwonly, (type(self), self.__dict__))
157+
158+
159+
class RetryBudgetExhaustedError(_KeywordReduceMixin, ClientError):
149160
"""Raised when a retry was needed but the RetryBudget refused to permit it.
150161
151162
Carries the last response and/or exception observed before the budget refused,
@@ -168,22 +179,8 @@ def __init__(
168179
self.attempts = attempts
169180
super().__init__(f"retry budget exhausted after {attempts} attempt(s)")
170181

171-
def __reduce__(self) -> tuple[Any, ...]:
172-
return (
173-
_reconstruct_budget_exhausted,
174-
(type(self), self.last_response, self.last_exception, self.attempts),
175-
)
176-
177-
178-
def _reconstruct_bulkhead_full(
179-
cls: "type[BulkheadFullError]",
180-
max_concurrent: int,
181-
acquire_timeout: float | None,
182-
) -> "BulkheadFullError":
183-
return cls(max_concurrent=max_concurrent, acquire_timeout=acquire_timeout)
184182

185-
186-
class BulkheadFullError(ClientError):
183+
class BulkheadFullError(_KeywordReduceMixin, ClientError):
187184
"""Raised when ``acquire_timeout`` elapses before an AsyncBulkhead slot becomes available.
188185
189186
Carries the configured caps for caller logging/alerting.
@@ -197,21 +194,8 @@ def __init__(self, *, max_concurrent: int, acquire_timeout: float | None) -> Non
197194
self.acquire_timeout = acquire_timeout
198195
super().__init__(f"bulkhead full (max_concurrent={max_concurrent}, acquire_timeout={acquire_timeout})")
199196

200-
def __reduce__(self) -> tuple[Any, ...]:
201-
return (
202-
_reconstruct_bulkhead_full,
203-
(type(self), self.max_concurrent, self.acquire_timeout),
204-
)
205-
206-
207-
def _reconstruct_circuit_open(
208-
cls: "type[CircuitOpenError]",
209-
retry_after: float | None,
210-
) -> "CircuitOpenError":
211-
return cls(retry_after=retry_after)
212-
213197

214-
class CircuitOpenError(ClientError):
198+
class CircuitOpenError(_KeywordReduceMixin, ClientError):
215199
"""Raised when a CircuitBreaker refuses a request because the circuit is not closed.
216200
217201
Fires when the circuit is OPEN, or when it is HALF_OPEN and the single probe
@@ -229,20 +213,8 @@ def __init__(self, *, retry_after: float | None) -> None:
229213
else:
230214
super().__init__(f"circuit open (retry_after={retry_after:.3f}s)")
231215

232-
def __reduce__(self) -> tuple[Any, ...]:
233-
return (_reconstruct_circuit_open, (type(self), self.retry_after))
234-
235-
236-
def _reconstruct_decode_error(
237-
cls: "type[DecodeError]",
238-
response: httpx2.Response,
239-
model: type,
240-
original: BaseException,
241-
) -> "DecodeError":
242-
return cls(response=response, model=model, original=original)
243-
244216

245-
class DecodeError(ClientError):
217+
class DecodeError(_KeywordReduceMixin, ClientError):
246218
"""Raised when the active ResponseDecoder failed to decode response.content.
247219
248220
The HTTP call itself succeeded — status was 2xx/3xx and the transport
@@ -268,12 +240,6 @@ def __init__(
268240
self.original = original
269241
super().__init__(f"failed to decode response into {model.__name__}: {original}")
270242

271-
def __reduce__(self) -> tuple[Any, ...]:
272-
return (
273-
_reconstruct_decode_error,
274-
(type(self), self.response, self.model, self.original),
275-
)
276-
277243

278244
def _missing_decoder_summary(model: type, registered_names: tuple[str, ...]) -> str:
279245
if not registered_names:
@@ -287,15 +253,7 @@ def _missing_decoder_summary(model: type, registered_names: tuple[str, ...]) ->
287253
return f"no decoder for response_model={model!r}: {hint}"
288254

289255

290-
def _reconstruct_missing_decoder(
291-
cls: "type[MissingDecoderError]",
292-
model: type,
293-
registered_names: tuple[str, ...],
294-
) -> "MissingDecoderError":
295-
return cls(model=model, registered_names=registered_names)
296-
297-
298-
class MissingDecoderError(ClientError):
256+
class MissingDecoderError(_KeywordReduceMixin, ClientError):
299257
"""Raised when response_model= is set but no registered decoder claims the model.
300258
301259
Fires at .send() entry, BEFORE the HTTP call — no point sending a request
@@ -311,21 +269,8 @@ def __init__(self, *, model: type, registered_names: tuple[str, ...]) -> None:
311269
self.registered_names = registered_names
312270
super().__init__(_missing_decoder_summary(model, registered_names))
313271

314-
def __reduce__(self) -> tuple[Any, ...]:
315-
return (_reconstruct_missing_decoder, (type(self), self.model, self.registered_names))
316-
317-
318-
def _reconstruct_response_too_large(
319-
cls: "type[ResponseTooLargeError]",
320-
status_code: int,
321-
limit: int,
322-
content_length: int | None,
323-
reason: 'Literal["declared", "streamed"]',
324-
) -> "ResponseTooLargeError":
325-
return cls(status_code=status_code, limit=limit, content_length=content_length, reason=reason)
326272

327-
328-
class ResponseTooLargeError(ClientError):
273+
class ResponseTooLargeError(_KeywordReduceMixin, ClientError):
329274
"""Raised when a response body exceeds the client's max_response_body_bytes cap.
330275
331276
Status-agnostic: fires on any non-streaming send() and on stream()'s internal
@@ -362,9 +307,3 @@ def __init__(
362307
else:
363308
detail = f"decoded body exceeded max_response_body_bytes={limit}"
364309
super().__init__(f"response body too large: status={status_code} {detail}")
365-
366-
def __reduce__(self) -> tuple[Any, ...]:
367-
return (
368-
_reconstruct_response_too_large,
369-
(type(self), self.status_code, self.limit, self.content_length, self.reason),
370-
)

0 commit comments

Comments
 (0)