headgate 0.2.0__tar.gz → 0.3.0__tar.gz

{headgate-0.2.0 → headgate-0.3.0}/CHANGELOG.md

@@ -6,6 +6,36 @@ change the public API; such changes are listed under **Changed** and **Removed**
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-26
+
+Fixes four bugs where a call's deadline, its timeouts, the rate budget and the cache disagreed. One of them makes a
+configuration that could never work an error, so this is a minor release: see **Changed**.
+
+### Added
+
+- `headgate.ratelimit.BudgetBacklogError`, raised by `RateBudget.wait` when a call's paced turn comes after its deadline.
+
+### Changed
+
+- A timeout longer than the deadline it runs under is refused with `ValueError` on the client, a view or a call, since
+  it could never take effect ([#6](https://github.com/kelsayed17/headgate/issues/6)). Raise the deadline with it, e.g.
+  `with_options(timeout=300.0, deadline=600.0)`.
+- A body past `max_response_bytes` is no longer stored in the cache, since it is not held to be written on accept.
+
+### Fixed
+
+- A cached miss is stored only once the call's reader accepts it, so a refusal inside a 200, an undecodable body or an
+  undeclared status is no longer served from the cache for the entry's lifetime
+  ([#9](https://github.com/kelsayed17/headgate/issues/9)). A `stream()` is accepted when its head checks pass.
+- Identical concurrent GETs share one cached download again when their timeouts are longer than the time their deadline
+  leaves; the sharing key now uses the timeouts the call asked for, not the deadline-cut ones
+  ([#4](https://github.com/kelsayed17/headgate/issues/4)).
+- A call whose rate-budget turn comes after its deadline fails at once with `ClientTimeoutError` saying it was never
+  sent, with `retryable=True` and `retry_after`, instead of waiting and failing like a slow upstream; a retry that
+  cannot be sent in time ends the call with the failure it already has, and such a hedge is not sent. A deadline that
+  passes before an attempt is sent says so, and `attempts` counts only the sends made
+  ([#5](https://github.com/kelsayed17/headgate/issues/5)).
+
 ## [0.2.0] - 2026-10-25
 
 The first release published to PyPI. It reshapes the client around option objects and rebuilds every policy
@@ -185,6 +215,7 @@ Python 3.14.
 - The `headgate.msgspec` and `headgate.pydantic` codec flavors, the optional `AsyncCurlTransport` (`headgate[curl]`),
   `headgate.health` snapshots and `headgate.policy.policy_disabled()`.
 
-[Unreleased]: https://github.com/kelsayed17/headgate/compare/v0.2.0...HEAD
-[0.2.0]: https://github.com/kelsayed17/headgate/compare/f319ad8...v0.2.0
+[Unreleased]: https://github.com/kelsayed17/headgate/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/kelsayed17/headgate/compare/159a3c2...v0.3.0
+[0.2.0]: https://github.com/kelsayed17/headgate/compare/f319ad8...159a3c2
 [0.1.0]: https://github.com/kelsayed17/headgate/commit/f319ad8

{headgate-0.2.0 → headgate-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: headgate
-Version: 0.2.0
+Version: 0.3.0
 Summary: The async API-client base on httpx2: safe retries, rate budgets, per-origin breakers, credential-safe caching, typed events and declared responses.
 Project-URL: Homepage, https://github.com/kelsayed17/headgate
 Project-URL: Documentation, https://github.com/kelsayed17/headgate/tree/main/docs
@@ -37,6 +37,10 @@ Provides-Extra: pydantic
 Requires-Dist: pydantic>=2.14.1; extra == 'pydantic'
 Description-Content-Type: text/markdown
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/kelsayed17/headgate/main/docs/assets/logo.png" alt="headgate logo: a gate metering a stream of requests" width="160">
+</p>
+
 # headgate
 
 **An async API-client base for Python, built on [httpx2](https://pypi.org/project/httpx2/).** Subclass

{headgate-0.2.0 → headgate-0.3.0}/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/kelsayed17/headgate/main/docs/assets/logo.png" alt="headgate logo: a gate metering a stream of requests" width="160">
+</p>
+
 # headgate
 
 **An async API-client base for Python, built on [httpx2](https://pypi.org/project/httpx2/).** Subclass

{headgate-0.2.0 → headgate-0.3.0}/docs/caching.md

@@ -30,13 +30,18 @@ policy = TransportPolicy(cache=cache)
 - **`policy`** is a hishel `FilterPolicy`. headgate supplies three filters: `PathFragmentFilter(fragments)` (the URL path
   contains one of them), `MethodFilter(methods)` and `StatusCodeFilter(codes)`. A `FilterPolicy` stores whenever a
   request filter matches and an allowed status comes back, **even past a `no-store`**, which is the point for a
-  provider that sends no cache headers, or wrong ones. Store only 200s, so an error body never poisons the cache.
-  Body-keyed POST caching is hishel's own `FilterPolicy.use_body_key`.
+  provider that sends no cache headers, or wrong ones. Body-keyed POST caching is hishel's own
+  `FilterPolicy.use_body_key`.
+- **Stored on accept.** A response the policy allows is written to storage only once the call's `expect=` reader has
+  accepted it. A call whose reader raises stores nothing, so the cache never serves an answer the client refused:
+  a refusal inside a 200 that a `check` catches, an undecodable body, an undeclared status. A declared non-2xx
+  (`Expect(...).on(404, ...)`) is stored when the filters allow its status. A `stream()` has no reader, so passing its
+  head checks accepts it. A write that fails then is counted as a degradation; the call keeps its answer.
 - **`ttl`** is the client's default lifetime in seconds; a call's `cache_ttl=` overrides it.
 - **TTL, not revalidation.** An entry is served until its lifetime ends and is never revalidated with the origin. For
   revalidation, use [conditional reads](#conditional-reads).
 - The body is held up to `HttpOptions.max_response_bytes`, and a body past it raises `ResponseTooLargeError` as it would
-  uncached.
+  uncached. A body past the cap is not stored, not even for a `stream()`.
 
 ## Partitions
 
@@ -66,10 +71,12 @@ stored either; the request that fetched it still receives it.
 
 hishel has no request coalescing, so an identical GET arriving while the first is still being fetched would miss too.
 headgate makes it wait and gives it a copy of the first one's response (a hit, a miss or a degraded fetch). Identical
-means the same URL, every header, the same timeouts and the same retry policy. A network failure fails every waiting
-request from the one attempt, each with its own copy of the error, and each caller's retry layer then retries (and
-shares again). Only the request that fetched counts toward the [breaker](breaker.md). A body past the size cap is not
-held, so each waiting request fetches its own. POSTs are never shared.
+means the same URL, every header, the same timeouts and the same retry policy; the timeouts compared are the ones the
+call asked for, not the ones its deadline cut, so calls with different time left still share. A timeout that only the
+first request's deadline cut short is not passed on: each waiting request then fetches its own. A network failure fails
+every waiting request from the one attempt, each with its own copy of the error, and each caller's retry layer then
+retries (and shares again). Only the request that fetched counts toward the [breaker](breaker.md). A body past the size
+cap is not held, so each waiting request fetches its own. POSTs are never shared.
 
 ## Storage faults
 

{headgate-0.2.0 → headgate-0.3.0}/docs/deadlines.md

@@ -32,8 +32,15 @@ below act on it as well as the outer timer:
 - the retry layer starts no attempt or wait with less than `RetryPolicy.min_attempt_time` (0.05 s) left, and raises
   the last failure with the note `deadline exhausted` instead;
 - a rate-budget pause that would outlast the deadline raises `RateLimitError` at once rather than waiting;
+- a turn in the rate budget that comes at or after the deadline is not waited for. On the first attempt the call
+  raises `ClientTimeoutError` at once, naming it as never sent, with `attempts=0`, `retryable=True` and `retry_after`
+  the wait it was refused. On a retry, the call ends with the failure it already has, noted `deadline exhausted`, and a
+  hedge is simply not sent;
 - after a rate-budget wait the send's timeouts are cut again, to what the wait left.
 
+A deadline that passes before the request is sent (waiting for an in-flight slot, say) says so too:
+`GET item/3: deadline exceeded after 3s, before attempt 1 was sent`, with `attempts` counting only the sends made.
+
 For [`stream()`](streaming.md) the deadline bounds opening the stream (every attempt, backoff and the head checks), not
 reading it: the caller's pace of iteration decides how long the body takes. Wrap the block in `asyncio.timeout` to
 bound the whole body.
@@ -47,8 +54,18 @@ number replaces the read timeout only: `HttpOptions(timeout=60.0)` keeps the oth
 A call overrides them with `timeout=`: a `Timeouts` replaces all four, a number the read timeout alone. A view made with
 `with_options(timeout=...)` does the same for its calls. Every value must be positive.
 
+A timeout must fit the deadline it runs under, or it could never take effect: each attempt's timeouts are cut to the
+time left. So a timeout longer than that deadline is refused with `ValueError` where it is set: on the client (against
+the policy's deadline), on a view, or on a call. A bare number is checked as the read timeout, and a `Timeouts` by the
+phases set away from their defaults. Shortening the deadline instead is always allowed; cutting the timeouts is what a
+short deadline is for. To give a slow endpoint a long read timeout, raise the deadline with it:
+
+```python
+reports = client.with_options(timeout=300.0, deadline=600.0)
+```
+
 ## Choosing values
 
-- Keep `read` below the deadline, or a single slow response takes the whole call and leaves no time to retry it.
+- Keep `read` well below the deadline, or a single slow response takes the whole call and leaves no time to retry it.
 - A long export or report endpoint wants a `Route` with a longer deadline rather than a client-wide one.
 - `deadline=None` exists for calls that legitimately run unbounded (a long poll); prefer a generous number.

{headgate-0.2.0 → headgate-0.3.0}/docs/rate-budgets.md

@@ -28,7 +28,8 @@ under a `threading.Lock` and nothing in it is bound to a loop.
 
 - **Pacing** is GCRA, the virtual-scheduling form of a leaky bucket. Up to `rate.requests` requests (at least one) go
   out back to back; after that they are `period / requests` seconds apart. Waiters are served in arrival order, and a
-  waiter cancelled in the queue (its deadline passed, say) gives its turn back when nobody reserved after it.
+  waiter cancelled in the queue gives its turn back when nobody reserved after it. A call whose turn comes at or after
+  its deadline does not queue: it gives the turn back and the attempt is never sent (see [deadlines](deadlines.md)).
 - **`max_in_flight`** caps how many requests are open at once. A request holds its slot from the send until its
   response body is **closed**, not until the head arrives, since the server is still busy with a body that streams.
   Every path that drops a response closes it, so a slot cannot leak.

{headgate-0.2.0 → headgate-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "headgate"
-version = "0.2.0"
+version = "0.3.0"
 description = "The async API-client base on httpx2: safe retries, rate budgets, per-origin breakers, credential-safe caching, typed events and declared responses."
 readme = "README.md"
 requires-python = ">=3.14"
@@ -83,7 +83,7 @@ include = [
     "LICENSE",
     "pyproject.toml",
 ]
-exclude = [".hypothesis", "**/__pycache__", "**/*.pyc", "mutants", ".coverage*", ".codspeed"]
+exclude = ["docs/assets", ".hypothesis", "**/__pycache__", "**/*.pyc", "mutants", ".coverage*", ".codspeed"]
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"

{headgate-0.2.0 → headgate-0.3.0}/src/headgate/_client.py

@@ -70,6 +70,7 @@ from headgate._options import (
     HttpOptions,
     Timeouts,
     TransportPolicy,
+    check_timeout_fits,
     httpx_timeout,
     match_route,
     reject_upstream_httpx,
@@ -82,7 +83,7 @@ from headgate._view import KEEP, ROOT_DEFAULTS, Keep, overlay_timeout
 from headgate.breaker import BreakerOpenError, CircuitBreaker
 from headgate.breaker._registry import NO_BREAKER
 from headgate.breaker._scope import scoped_registry
-from headgate.cache._transport import host_untested
+from headgate.cache._transport import host_untested, store_accepted
 from headgate.errors import (
     CircuitOpenError,
     ClientError,
@@ -92,7 +93,7 @@ from headgate.errors import (
     RateLimitError,
 )
 from headgate.pagination import PageRequest, Paginated
-from headgate.ratelimit import BudgetPausedError
+from headgate.ratelimit import BudgetBacklogError, BudgetPausedError
 from headgate.retry import NO_RETRY, REPLAYABLE_BODY, RetryPolicy
 from headgate.retry._policy import NETWORK_ERRORS, RETRY_OUTCOME, RETRY_POLICY
 from headgate.streaming import Stream
@@ -263,6 +264,7 @@ class AsyncBaseClient:
         self._refusal_check = http.refusal_check
         self._max_response_bytes = http.max_response_bytes
         self._request_id_headers = http.request_id_headers
+        check_timeout_fits(http.timeout, policy.deadline)
         self._timeout = http.timeout
         self._emitter = Emitter(http.observers) if http.observers else SILENT
         self._view = ROOT_DEFAULTS
@@ -316,6 +318,8 @@ class AsyncBaseClient:
         :raises ValueError: for a timeout or deadline that is not positive.
         """
         layered = self._view.layered(headers=headers, deadline=deadline, retry=retry)
+        if timeout is not None:
+            check_timeout_fits(timeout, self._policy.deadline if layered.deadline is KEEP else layered.deadline)
         view = copy.copy(self)
         # A shallow copy shares the pool, the stack and any subclass state; only the view's own settings differ.
         vars(view).update(
@@ -506,7 +510,10 @@ class AsyncBaseClient:
             async with self._deadline(prepared), self._exchange(prepared) as (streamed, _):
                 announce_deprecation(prepared.context, streamed)
                 resp = await read_capped(streamed, self._max_response_bytes, self._site(prepared))
-            return self._dispatch(resp, spec, self._site(prepared))
+            answer = self._dispatch(resp, spec, self._site(prepared))
+            # Only now that the reader accepted it may a cached miss be stored.
+            await store_accepted(resp)
+            return answer
 
     @contextlib.asynccontextmanager
     async def _streamed(self, call: _Call) -> AsyncGenerator[Stream]:
@@ -526,6 +533,8 @@ class AsyncBaseClient:
                 if not streamed.is_success:
                     head = await read_head(streamed, _STREAM_ERROR_HEAD_BYTES)
                     raise status_error(head, self._site(prepared))
+                # A stream has no reader: passing the head checks is what accepts it.
+                await store_accepted(streamed)
             yield Stream(streamed, self._site(prepared), functools.partial(self._network_failure, prepared, verdict))
 
     # Preparing the request.
@@ -570,9 +579,10 @@ class AsyncBaseClient:
         full_url = sanitize_url(str(request.url)) if self._emitter.active else None
         info = CallInfo(method=call.method, url=log_url, route=route, full_url=full_url)
         route_policy = match_route(self._policy.routes, request.url.path)
-        context = CallContext(
-            info, clock=self._timing.clock, deadline_after=self._deadline_of(call, route_policy), emitter=self._emitter
-        )
+        deadline = self._deadline_of(call, route_policy)
+        if (timeout := options.get("timeout")) is not None:
+            check_timeout_fits(timeout, deadline)
+        context = CallContext(info, clock=self._timing.clock, deadline_after=deadline, emitter=self._emitter)
         context.follow_redirects = follow
         if (retry := self._retry_of(call, route_policy)) is not None:
             context.put(RETRY_POLICY, retry)
@@ -669,8 +679,12 @@ class AsyncBaseClient:
             async with asyncio.timeout(remaining):
                 yield
         except TimeoutError:
-            site = self._site(prepared)
-            msg = f"{site.method} {site.url}: deadline exceeded after {prepared.context.elapsed():.3g}s"
+            context = prepared.context
+            if context.progress.dispatched or context.attempt == 0:
+                site, unsent = self._site(prepared), ""
+            else:
+                site, unsent = self._unsent_site(prepared), f", before attempt {context.attempt} was sent"
+            msg = f"{site.method} {site.url}: deadline exceeded after {context.elapsed():.3g}s{unsent}"
             raise ClientTimeoutError(msg, **site.details()) from None
 
     # The exchange: one send under the origin's breaker.
@@ -704,6 +718,14 @@ class AsyncBaseClient:
         except BreakerOpenError as exc:
             details = self._site(prepared).details(retry_after=exc.retry_after)
             raise CircuitOpenError(str(exc), **details) from None
+        except BudgetBacklogError as exc:
+            # Our own pacing, not the provider's: the call was never sent (the retry layer withdrew the attempt), and
+            # sending it later will be admitted.
+            site = self._site(prepared)
+            details = site.details(retry_after=exc.retry_after)
+            details["retryable"] = True
+            msg = f"{site.method} {site.url}: never sent: {exc}"
+            raise ClientTimeoutError(msg, **details) from None
         except BudgetPausedError as exc:
             # Not the retry policy's call: the budget says when sending again will be admitted.
             details = self._site(prepared).details(retry_after=exc.retry_after)
@@ -831,6 +853,10 @@ class AsyncBaseClient:
             self._source, info.method, info.url, context.attempt, self._request_id_headers, context.get(RETRY_OUTCOME)
         )
 
+    def _unsent_site(self, prepared: _Prepared) -> CallSite:
+        """Return :meth:`_site` for a call whose current attempt never reached the network: it does not count."""
+        return replace(self._site(prepared), attempts=prepared.context.attempt - 1)
+
 
 def _effective_policy(policy: TransportPolicy, *, off: bool) -> TransportPolicy:
     """Return the policy a client built now runs: *policy*, less retries and the breaker when transport policy is *off*.

{headgate-0.2.0 → headgate-0.3.0}/src/headgate/_core/__init__.py

@@ -30,7 +30,7 @@ from headgate._core._events import (
 )
 from headgate._core._origin import origin_of, origin_text, same_origin
 from headgate._core._retry_after import RETRY_AFTER_STATUSES, parse_retry_after, retry_after_of
-from headgate._core._seams import BREAKER_GATE, CredentialCarrier, CredentialStamper
+from headgate._core._seams import BREAKER_GATE, BudgetBacklogError, CredentialCarrier, CredentialStamper
 from headgate._core._switch import policy_disabled, policy_is_disabled
 from headgate._core._time import (
     SYSTEM_TIMING,
@@ -53,6 +53,7 @@ __all__ = [
     "AttemptFinished",
     "BreakerChanged",
     "BreakerState",
+    "BudgetBacklogError",
     "CacheOutcome",
     "CacheResult",
     "CallContext",

{headgate-0.2.0 → headgate-0.3.0}/src/headgate/_core/_context.py

@@ -38,19 +38,39 @@ __all__ = ["CallContext", "SendProgress", "Slot"]
 
 #: The one request extension headgate keeps its per-call state in.
 _EXTENSION: Final = "headgate.call"
+#: The extension holding a request's timeouts as they were before :meth:`CallContext.fit_timeouts` first cut them.
+_REQUESTED_TIMEOUT: Final = "headgate.requested_timeout"
+
+
+#: A request's httpx2 timeouts as ``(phase, seconds)`` pairs sorted by phase; ``None`` is a phase without a limit.
+type PhaseTimeouts = tuple[tuple[str, float | None], ...]
+
+
+def _named(timeout: object) -> PhaseTimeouts:
+    """Return *timeout*, a request's ``timeout`` extension, as :data:`PhaseTimeouts`; empty when it is not one."""
+    if not isinstance(timeout, dict):
+        return ()
+    # Sorted by phase, which is unique, so the values (a float or None) are never compared.
+    pairs: list[tuple[str, float | None]] = sorted((str(phase), limit) for phase, limit in timeout.items())
+    return tuple(pairs)
 
 
 @dataclass(slots=True)
 class SendProgress:
-    """What one attempt established about sending: whether a connection was obtained, and request bytes written.
+    """What one attempt established about sending: whether it was handed to the network, connected, and bytes written.
 
     These are facts, recorded by whichever layer can observe them, so the retry layer can tell a request that never
     left from one that may have been processed.
     """
 
+    dispatched: bool = False
     connected: bool = False
     bytes_sent: int = 0
 
+    def mark_dispatched(self) -> None:
+        """Record that the attempt passed the rate budget and was handed to the network."""
+        self.dispatched = True
+
     def mark_connected(self) -> None:
         """Record that the attempt obtained a connection."""
         self.connected = True
@@ -173,11 +193,26 @@ class CallContext:
         timeout = request.extensions.get("timeout")
         if remaining is None or not isinstance(timeout, dict):
             return
+        # Recorded on the request itself: a call's hops (a token mint, say) may ask for timeouts of their own.
+        request.extensions.setdefault(_REQUESTED_TIMEOUT, timeout)
         left = max(remaining, floor)
         request.extensions["timeout"] = {
             phase: left if limit is None else min(limit, left) for phase, limit in timeout.items()
         }
 
+    @staticmethod
+    def requested_timeouts(request: httpx2.Request) -> PhaseTimeouts:
+        """Return the httpx2 timeouts *request* asked for, before :meth:`fit_timeouts` cut any of them to a deadline.
+
+        Before any fit, they are its own ``timeout`` extension (none without one).
+        """
+        return _named(request.extensions.get(_REQUESTED_TIMEOUT, request.extensions.get("timeout")))
+
+    @staticmethod
+    def timeouts_cut(request: httpx2.Request) -> bool:
+        """Return whether :meth:`fit_timeouts` cut *request*'s timeouts below the ones it asked for."""
+        return _named(request.extensions.get("timeout")) != CallContext.requested_timeouts(request)
+
     # Attempts.
 
     @property
@@ -196,6 +231,10 @@ class CallContext:
         self._progress = SendProgress()
         return self._attempt
 
+    def withdraw_attempt(self) -> None:
+        """Record that the attempt just begun was never sent (its rate-budget turn came too late): it does not count."""
+        self._attempt -= 1
+
     # Notes and events.
 
     @property

{headgate-0.2.0 → headgate-0.3.0}/src/headgate/_core/_seams.py

@@ -9,6 +9,9 @@
   declares, for the guard alone.
 * :data:`BREAKER_GATE`: set by the client on every call, read by the retry layer, so a retry sequence stops as soon as
   the origin's breaker opens without the retry layer knowing about breakers.
+* :class:`BudgetBacklogError`: raised by the rate budget for an attempt whose turn comes after the call's deadline. The
+  retry layer withdraws the attempt, which was never sent, and keeps the call's last failure when it has one; the
+  client raises it as ``ClientTimeoutError``.
 """
 
 from __future__ import annotations
@@ -18,7 +21,7 @@ from typing import Protocol, runtime_checkable
 
 from headgate._core._context import Slot
 
-__all__ = ["BREAKER_GATE", "CredentialCarrier", "CredentialStamper"]
+__all__ = ["BREAKER_GATE", "BudgetBacklogError", "CredentialCarrier", "CredentialStamper"]
 
 
 @runtime_checkable
@@ -48,3 +51,16 @@ class CredentialStamper(CredentialCarrier, Protocol):
 #: Answers whether the breaker for the call's origin is refusing right now. The client puts it on every call's
 #: context; the retry layer checks it before scheduling another attempt.
 BREAKER_GATE = Slot[Callable[[], bool]]("breaker_gate")
+
+
+class BudgetBacklogError(Exception):
+    """Raised by ``RateBudget.wait`` when an attempt's paced turn comes after its call's deadline, so it is never sent.
+
+    ``retry_after`` is the seconds until the turn the attempt would have had. It is public as
+    ``headgate.ratelimit.BudgetBacklogError``.
+    """
+
+    def __init__(self, message: str, *, retry_after: float) -> None:
+        """Record *message* and *retry_after*."""
+        super().__init__(message)
+        self.retry_after = retry_after

{headgate-0.2.0 → headgate-0.3.0}/src/headgate/_options.py

@@ -48,6 +48,7 @@ __all__ = [
     "Route",
     "Timeouts",
     "TransportPolicy",
+    "check_timeout_fits",
     "httpx_timeout",
     "match_route",
     "reject_upstream_httpx",
@@ -116,6 +117,31 @@ def httpx_timeout(client: Timeouts | float, call: Timeouts | float | None = None
     return httpx2.Timeout(connect=base.connect, read=base.read, write=base.write, pool=base.pool)
 
 
+def check_timeout_fits(timeout: Timeouts | float, deadline: float | None) -> None:
+    """Refuse a *timeout* someone set that is longer than the *deadline* it runs under, since it could never apply.
+
+    A bare number is the read timeout. Of a ``Timeouts``, only the phases set away from their defaults are checked, so
+    a short deadline over the default timeouts stays valid: there the deadline cuts each attempt's timeouts, as meant.
+
+    :raises ValueError: naming the phase, its timeout and the deadline.
+    """
+    if deadline is None:
+        return
+    defaults = Timeouts()
+    if isinstance(timeout, Timeouts):
+        phases = [(name, getattr(timeout, name)) for name in ("connect", "read", "write", "pool")]
+        chosen = [(name, limit) for name, limit in phases if limit != getattr(defaults, name)]
+    else:
+        chosen = [("read", timeout)]
+    for name, limit in chosen:
+        if limit > deadline:
+            msg = (
+                f"{name} timeout {limit:g}s is longer than the {deadline:g}s deadline it runs under, so it can never "
+                f"take effect: raise the deadline (TransportPolicy(deadline=...) or deadline=), or lower the timeout"
+            )
+            raise ValueError(msg)
+
+
 def _uuid4_text() -> str:
     """Return a random UUID as text."""
     return str(uuid.uuid4())