Client¶
dpc_radar.client ¶
An async client for the DPC radar API: the latest frame, or the frame at a time.
Give it your httpx.AsyncClient and timeouts, proxies and pooling stay
yours; give it none and it opens (and closes) its own. Network errors and
429/5xx are retried retries times with exponential backoff, except the one
answer that must never be retried: a frame the DPC no longer keeps (a 500 with
S3's 403 in the body), which comes back as :data:ABSENT.
To route every request through your own HTTP layer (a shared retry policy, a
rate limiter, a cache), pass send: an async (method, url, **kwargs) ->
httpx.Response. The client then uses it for every call and does no retrying
of its own. The hook must return error responses rather than raise on them,
or the client cannot tell a frame that is gone from a failure. For its own
failures it should raise :class:httpx.HTTPError: that is what
:func:dpc_radar.archive.archive counts as one failed frame, along with
:class:~dpc_radar.errors.DpcRadarError and :class:OSError.
An answer that is not a JSON object (a proxy or maintenance page, a body cut
off) raises :class:~dpc_radar.errors.DpcRadarError.
The client keeps no state between calls: no cache, no logging. Holding on to the last frame, and deciding what a failure means, is the caller's job.
Absent ¶
A frame the DPC no longer keeps (older than about five months).
RadarClient ¶
The open DPC radar API (radar-api.protezionecivile.it).
last_product
async
¶
last_product(name: str | Product) -> LastProduct | None
Time and period of the newest frame; None if the API lists none.
latest
async
¶
latest(name: str | Product, *, cached: RainGrid | None = None) -> RainGrid
The newest frame of a product.
Pass the frame you already hold as cached: if it is still the
newest, it comes back as is and nothing is downloaded (a CUM frame is
about 2 MB and changes every 30 minutes).
at
async
¶
at(name: str | Product, time: datetime) -> RainGrid | Absent
The frame of a product issued at time (aware), or :data:ABSENT.
download
async
¶
download(name: str | Product, time: datetime) -> bytes | Absent
The GeoTIFF of a frame as published, or :data:ABSENT (to archive it as is).
json_object ¶
json_object(response: Response) -> dict[str, Any]
The JSON object in an answer; :class:DpcRadarError if it holds anything else.