[john-zither]

Your checklist for this pull request

• Pulling a feature branch (feature/fetch-robustness) against power-source.
• Tests pass with coverage up: 464 passed (23 new, covering the typed error, stale-on-failure, and the budget), ruff check clean. The 10 failures are pre-existing on power-source (pandas 2.x with numpy 2.5) and are fixed by Stop constructing Timedeltas the way numpy 2.5 deprecates #106; they are unrelated to this change.
• CHANGELOG.md updated under the "Development" section.
• Code style: ruff.
• New functions and the new FetchDeadlineExceeded carry numpy-style docstrings; load_data and WeatherStation.load_data parameter docs updated.
• All commits carry the DCO Signed-off-by trailer.
• Parts of this change were drafted with an AI assistant; every commit records it in a Co-Authored-By trailer. The tool's terms impose no conditions inconsistent with the project's licence or the Open Source Definition, and the output does not incorporate third-party code.

Description

Three independent defects in what happens when a fetch goes wrong, as three commits.

Transport failures are untyped. A requests.ConnectionError or Timeout escapes load_data unchanged, so a caller must import requests to catch it — and no exception is exported at the top level, so it must know the submodule too. FetchError distinguishes "the network failed" from "the data does not exist" (DataNotAvailableError), which is the difference between a request worth retrying and one that never will be.

A failed refetch destroys usable data. _read_cached_year calls store.clear(key) on an expired entry and then returns None, after which the caller fetches; if that fetch fails the old block is already gone. This is not a rare path — entries expire only for volatile years, the current one and the tail of the previous, which is exactly the window a recent reporting period reads from. The common case is an expired-but-good entry, an upstream outage, and the library discarding the local copy before finding out. The block is now replaced only after a successful refetch.

Nothing caps how long a request may spend on the network. Every fetch path retries with a 120 second socket timeout — ghcnh three times, nasa_power four, base three for normals archives — per station-year, per site. Against an unresponsive upstream a large run does not fail in a way anyone can see; it runs for days. load_data(deadline=<seconds>) bounds it and raises FetchDeadlineExceeded. Unbounded by default.

Details worth review on the deadline:

• The budget is ambient — a ContextVar in sources/budget.py — rather than an argument threaded through the call chain, because fetch_year is a published extension point that sources.register invites anyone to implement, and passing a deadline through it would break every third-party source. A context variable reaches them without their cooperation, is inherited by asyncio tasks, and is not inherited by threads, which is what we want here: the registry auto-updater runs on its own thread and has no business inside a caller's request budget.
• All three retry loops check the budget before opening a socket, cap the socket timeout at what remains, and never back off past the deadline. Capping the timeout is what makes it real — checking only between attempts would still let one hung read run 120 seconds over.
• The guarantee is approximate at the edge and the docstring says so: requests times out per socket operation, not per response, so a slow trickle can outlast it. Overshoot is bounded at one timeout rather than tries × timeout.
• A deadline raises rather than returning what it collected. Partial weather that looks complete is the failure this exists to make visible.
• remaining() clamps to the budget it was given: deadline - now is floating point, and where the monotonic clock reads the same value twice — as it does wherever the counter is coarser than the gap between two calls — the subtraction rounds above the budget. Nothing downstream cared, but "never longer than the budget" should be an invariant.

Backoff moved into budget.sleep_within, so the three tests that observed retries by patching a module-local time.sleep now patch it there. That is the only behavioural change to existing paths.

[travis-recurve]

Good work, and the hazard is real. The context variable is the right mechanism, and the
registry auto-updater is indeed the only thread in the package.

Two changes before merge.

1. The stale-on-failure serve is invisible. load_year returns a stale block on
   FetchError with no warning and no provenance record, which contradicts the argument you
   make for the deadline in the same PR ("partial weather that looks complete is the failure
   this is meant to make visible"). Stale weather that looks fresh is the same failure. I
   would record it in Provenance rather than a warning, since staleness is a property of
   the data.

2. deadline does not reach WeatherLocation, which is the primary entry point and does
   not route through engine.load_data. Wrapping the call in fetch_budget works, but is
   undocumented and buried.

Minor: FetchError and fetch_budget are not exported at the top level, though the
docstring names that as part of the problem. request_text passes the literal "request"
as the source name, so failures read "Could not fetch request data for station=None". One
blank line between the exception classes where the file uses two.

The branch was rebased from our side after #105 merged, and briefly closed when the base
branch was deleted. Your commits are unchanged, but you will need
git fetch && git reset --hard origin/feature/fetch-robustness.

[john-zither]

Rebased and pushed. All four:

1. Stale serves now show up in Provenance. Added a stale field to the namedtuple (trailing, defaults to False). When load_year serves a stale block after a FetchError, it records that in a small ContextVar ledger keyed by (station_id, year), the same pattern as fetch_budget. engine.py reads the ledger when it builds Provenance. This only covers the station pipeline — NasaPowerSource._load_year has no stale path, so there's nothing to record for grid loads.
2. deadline reaches WeatherLocation now. Gave WeatherLocation.load_data a deadline param like WeatherStation.load_data has, and wrapped both estimate(...) calls in fetch_budget(deadline). It no longer relies on the engine.load_data wrap.
3. Exports. FetchError, FetchDeadlineExceeded, and fetch_budget are exported at the top level.
4. request_text. It takes source/station_id/year now and passes them into FetchError, and the ghcnh/tmy3/cz2010/NASA callers fill them in. Failures name the real source and station instead of station=None. Also fixed the blank line between the exception classes.