aioarpapiemonte 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,66 @@
1
+ """Async client for the real-time data of the stations of Arpa Piemonte.
2
+
3
+ Arpa Piemonte publishes the readings of its stations (river levels, rain,
4
+ temperature, humidity, wind, snow) in two places: the files read by the
5
+ station pages of its website, hourly with their validation, and the
6
+ documented api_realtime, a few hours later.
7
+
8
+ The data is by Arpa Piemonte, under CC BY 4.0: credit it with
9
+ :data:`ATTRIBUTION`. aioarpapiemonte is not affiliated with Arpa Piemonte.
10
+ """
11
+
12
+ from .client import ArpaPiemonteClient
13
+ from .const import ATTRIBUTION, DEFAULT_REQUEST_TIMEOUT, MAX_PAGES, PIEMONTE_NETWORK
14
+ from .exceptions import (
15
+ ArpaPiemonteConnectionError,
16
+ ArpaPiemonteError,
17
+ ArpaPiemonteNotFoundError,
18
+ ArpaPiemonteParseError,
19
+ )
20
+ from .models import (
21
+ USABLE,
22
+ LevelStatus,
23
+ Param,
24
+ ParamReading,
25
+ ParamSeries,
26
+ Reading,
27
+ RealtimeData,
28
+ RealtimeField,
29
+ RealtimeRecord,
30
+ RealtimeStation,
31
+ Sensor,
32
+ Thresholds,
33
+ Validation,
34
+ station_page_url,
35
+ )
36
+ from .urls import sensor_id
37
+
38
+ __all__ = [
39
+ "ATTRIBUTION",
40
+ "DEFAULT_REQUEST_TIMEOUT",
41
+ "MAX_PAGES",
42
+ "PIEMONTE_NETWORK",
43
+ "USABLE",
44
+ "ArpaPiemonteClient",
45
+ "ArpaPiemonteConnectionError",
46
+ "ArpaPiemonteError",
47
+ "ArpaPiemonteNotFoundError",
48
+ "ArpaPiemonteParseError",
49
+ "LevelStatus",
50
+ "Param",
51
+ "ParamReading",
52
+ "ParamSeries",
53
+ "Reading",
54
+ "RealtimeData",
55
+ "RealtimeField",
56
+ "RealtimeRecord",
57
+ "RealtimeStation",
58
+ "Sensor",
59
+ "Thresholds",
60
+ "Validation",
61
+ "__version__",
62
+ "sensor_id",
63
+ "station_page_url",
64
+ ]
65
+
66
+ __version__ = "0.1.0"
@@ -0,0 +1,52 @@
1
+ """Conditional requests: what a host answered before, by URL."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass
6
+
7
+
8
+ @dataclass(frozen=True, slots=True)
9
+ class _Entry[T]:
10
+ """A parsed answer and the validators the host sent with it."""
11
+
12
+ etag: str | None
13
+ last_modified: str | None
14
+ value: T
15
+
16
+
17
+ class ConditionalCache[T]:
18
+ """The latest parsed answer of each URL, with its validators.
19
+
20
+ The files of the Arpa website send an ``ETag`` and a ``Last-Modified``,
21
+ and answer 304 when asked with either (measured on 2026-11-17).
22
+ """
23
+
24
+ def __init__(self) -> None:
25
+ """Initialize an empty cache."""
26
+ self._entries: dict[str, _Entry[T]] = {}
27
+
28
+ def validators(self, url: str) -> dict[str, str]:
29
+ """Return the headers that ask the host whether the URL changed."""
30
+ entry = self._entries.get(url)
31
+ if entry is None:
32
+ return {}
33
+ headers = {}
34
+ if entry.etag is not None:
35
+ headers["If-None-Match"] = entry.etag
36
+ if entry.last_modified is not None:
37
+ headers["If-Modified-Since"] = entry.last_modified
38
+ return headers
39
+
40
+ def get(self, url: str) -> T | None:
41
+ """Return the latest parsed answer of a URL; None when there is none."""
42
+ entry = self._entries.get(url)
43
+ return None if entry is None else entry.value
44
+
45
+ def store(
46
+ self, url: str, value: T, *, etag: str | None, last_modified: str | None
47
+ ) -> None:
48
+ """Keep a parsed answer; without validators there is nothing to ask with."""
49
+ if etag is None and last_modified is None:
50
+ self._entries.pop(url, None)
51
+ return
52
+ self._entries[url] = _Entry(etag, last_modified, value)
@@ -0,0 +1,255 @@
1
+ """Async client of the real-time data of Arpa Piemonte."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ import json
7
+ import logging
8
+ from functools import partial
9
+ from http import HTTPStatus
10
+ from typing import TYPE_CHECKING, Self
11
+
12
+ import aiohttp
13
+
14
+ from ._http import ConditionalCache
15
+ from .const import DEFAULT_REQUEST_TIMEOUT, MAX_PAGES, REPOSITORY_URL
16
+ from .exceptions import (
17
+ ArpaPiemonteConnectionError,
18
+ ArpaPiemonteNotFoundError,
19
+ ArpaPiemonteParseError,
20
+ )
21
+ from .models import Param, RealtimeData, RealtimeRecord
22
+ from .parsers import (
23
+ parse_data_pie_page,
24
+ parse_pie_anag,
25
+ parse_sensors,
26
+ parse_series,
27
+ parse_status,
28
+ )
29
+ from .urls import (
30
+ data_pie_url,
31
+ pie_anag_url,
32
+ sensors_url,
33
+ series_url,
34
+ status_url,
35
+ )
36
+
37
+ if TYPE_CHECKING:
38
+ from collections.abc import Callable
39
+
40
+ from .models import ParamSeries, RealtimeStation, Sensor
41
+
42
+ _LOGGER = logging.getLogger(__name__)
43
+
44
+
45
+ class ArpaPiemonteClient:
46
+ """Async client of the real-time data of the stations of Arpa Piemonte.
47
+
48
+ Two sources, for the same stations and readings:
49
+
50
+ - the files of the Arpa website (:meth:`get_sensors`, :meth:`get_series`):
51
+ hourly readings with their validation, about 40 minutes after the hour;
52
+ - the api_realtime (:meth:`get_realtime_stations`,
53
+ :meth:`get_realtime_data`): every quantity of a station in one request,
54
+ about 3 hours and 40 minutes after the hour.
55
+
56
+ Pass the ``aiohttp.ClientSession`` of the application (it is never closed
57
+ by the client), or use the client as an async context manager to let it
58
+ manage its own session. The files of the website are asked whether they
59
+ changed since the last answer (``If-None-Match``, ``If-Modified-Since``):
60
+ when they did not, the client returns the object it returned before.
61
+ """
62
+
63
+ def __init__(
64
+ self,
65
+ session: aiohttp.ClientSession | None = None,
66
+ *,
67
+ request_timeout: float = DEFAULT_REQUEST_TIMEOUT,
68
+ user_agent: str | None = None,
69
+ ) -> None:
70
+ """Initialize the client.
71
+
72
+ ``request_timeout`` applies to each request, in seconds.
73
+ ``user_agent`` names the application in the requests (default:
74
+ aioarpapiemonte and its version).
75
+ """
76
+ self._session = session
77
+ self._close_session = False
78
+ self._request_timeout = request_timeout
79
+ self._user_agent = user_agent or _default_user_agent()
80
+ self._sensors: ConditionalCache[tuple[Sensor, ...]] = ConditionalCache()
81
+ self._series: ConditionalCache[ParamSeries] = ConditionalCache()
82
+
83
+ async def __aenter__(self) -> Self:
84
+ """Enter the async context."""
85
+ return self
86
+
87
+ async def __aexit__(self, *_exc_info: object) -> None:
88
+ """Exit the async context, closing the session owned by the client."""
89
+ await self.close()
90
+
91
+ async def close(self) -> None:
92
+ """Close the session if the client created it."""
93
+ if self._session is not None and self._close_session:
94
+ await self._session.close()
95
+ self._session = None
96
+ self._close_session = False
97
+
98
+ async def get_sensors(self) -> tuple[Sensor, ...]:
99
+ """Return the stations of the Arpa website, with their quantities.
100
+
101
+ The list is 617 KB, uncompressed, and written again every 15 minutes:
102
+ read it to choose a station, not at every update.
103
+
104
+ Raises :class:`ArpaPiemonteConnectionError` or
105
+ :class:`ArpaPiemonteParseError`.
106
+ """
107
+ return await self._get(sensors_url(), parse_sensors, self._sensors)
108
+
109
+ async def get_series(self, param: Param, station: str) -> ParamSeries:
110
+ """Return the hourly readings of a quantity of a station.
111
+
112
+ ``station`` is the identifier of the station on the website
113
+ ("002105900", see :func:`aioarpapiemonte.sensor_id`). Raises
114
+ ``ValueError`` for an identifier that is not 9 digits,
115
+ :class:`ArpaPiemonteNotFoundError` when the station does not publish
116
+ the quantity, :class:`ArpaPiemonteConnectionError` or
117
+ :class:`ArpaPiemonteParseError`.
118
+ """
119
+ param = Param(param)
120
+ url = series_url(param, station)
121
+ return await self._get(
122
+ url, partial(parse_series, param=param, station=station), self._series
123
+ )
124
+
125
+ async def get_realtime_status(self) -> str:
126
+ """Return the status of the api_realtime ("healthy").
127
+
128
+ Raises :class:`ArpaPiemonteConnectionError` or
129
+ :class:`ArpaPiemonteParseError`.
130
+ """
131
+ return parse_status(await self._fetch_json(status_url()))
132
+
133
+ async def get_realtime_stations(self) -> tuple[RealtimeStation, ...]:
134
+ """Return the stations of Piedmont of the api_realtime.
135
+
136
+ They give the identifier of each station on the website
137
+ (``sensor_id``). Raises :class:`ArpaPiemonteConnectionError` or
138
+ :class:`ArpaPiemonteParseError`.
139
+ """
140
+ data = await self._fetch_json(pie_anag_url())
141
+ return await asyncio.to_thread(parse_pie_anag, data)
142
+
143
+ async def get_realtime_data(self, station_code: str) -> RealtimeData:
144
+ """Return the records of a station of the last 3 days, from the oldest.
145
+
146
+ ``station_code`` is the code of the station in the network ("188").
147
+ A station the api_realtime does not know has no records. Raises
148
+ ``ValueError`` for a code that is not letters and digits,
149
+ :class:`ArpaPiemonteConnectionError` or
150
+ :class:`ArpaPiemonteParseError`.
151
+ """
152
+ data_pie_url(station_code)
153
+ records: dict[object, RealtimeRecord] = {}
154
+ page = 1
155
+ while True:
156
+ data = await self._fetch_json(data_pie_url(station_code, page))
157
+ found, total_pages = parse_data_pie_page(data, station_code)
158
+ records.update((record.time, record) for record in found)
159
+ if page >= total_pages:
160
+ break
161
+ if page >= MAX_PAGES:
162
+ msg = f"The records of {station_code} have more than {MAX_PAGES} pages"
163
+ raise ArpaPiemonteParseError(msg)
164
+ page += 1
165
+ return RealtimeData(
166
+ station_code,
167
+ tuple(sorted(records.values(), key=lambda record: record.time)),
168
+ )
169
+
170
+ def _get_session(self) -> aiohttp.ClientSession:
171
+ if self._session is None:
172
+ # The website sets a cookie on every answer: keep none.
173
+ self._session = aiohttp.ClientSession(cookie_jar=aiohttp.DummyCookieJar())
174
+ self._close_session = True
175
+ return self._session
176
+
177
+ async def _get[T](
178
+ self, url: str, parse: Callable[[object], T], cache: ConditionalCache[T]
179
+ ) -> T:
180
+ """Return the file at a URL parsed, or the same object when unchanged."""
181
+ body, headers = await self._request(url, cache.validators(url))
182
+ if body is None:
183
+ value = cache.get(url)
184
+ if value is None:
185
+ msg = f"HTTP status 304 fetching {url}, without a previous answer"
186
+ raise ArpaPiemonteConnectionError(msg)
187
+ return value
188
+ value = await asyncio.to_thread(_decode, url, body, parse)
189
+ cache.store(
190
+ url,
191
+ value,
192
+ etag=headers.get(aiohttp.hdrs.ETAG),
193
+ last_modified=headers.get(aiohttp.hdrs.LAST_MODIFIED),
194
+ )
195
+ return value
196
+
197
+ async def _fetch_json(self, url: str) -> object:
198
+ body, _ = await self._request(url, {})
199
+ if body is None:
200
+ msg = f"HTTP status 304 fetching {url}, without asking"
201
+ raise ArpaPiemonteConnectionError(msg)
202
+ return await asyncio.to_thread(_decode, url, body, _identity)
203
+
204
+ async def _request(
205
+ self, url: str, validators: dict[str, str]
206
+ ) -> tuple[bytes | None, dict[str, str]]:
207
+ """Return the body and headers at a URL; no body when unchanged (304)."""
208
+ session = self._get_session()
209
+ headers = {"User-Agent": self._user_agent, **validators}
210
+ _LOGGER.debug("Fetching %s", url)
211
+ try:
212
+ async with (
213
+ asyncio.timeout(self._request_timeout),
214
+ session.get(url, headers=headers) as response,
215
+ ):
216
+ if response.status == HTTPStatus.NOT_MODIFIED:
217
+ return None, {}
218
+ if response.status == HTTPStatus.NOT_FOUND:
219
+ msg = f"HTTP status 404 fetching {url}"
220
+ raise ArpaPiemonteNotFoundError(msg)
221
+ response.raise_for_status()
222
+ return await response.read(), dict(response.headers)
223
+ except TimeoutError as err:
224
+ msg = f"Timeout fetching {url}"
225
+ raise ArpaPiemonteConnectionError(msg) from err
226
+ except aiohttp.ClientResponseError as err:
227
+ msg = f"HTTP status {err.status} fetching {url}"
228
+ raise ArpaPiemonteConnectionError(msg) from err
229
+ except (aiohttp.ClientError, OSError) as err:
230
+ msg = f"Error fetching {url}: {err!r}"
231
+ raise ArpaPiemonteConnectionError(msg) from err
232
+
233
+
234
+ def _default_user_agent() -> str:
235
+ from . import __version__ # noqa: PLC0415 - the package imports this module
236
+
237
+ return f"aioarpapiemonte/{__version__} (+{REPOSITORY_URL})"
238
+
239
+
240
+ def _identity(data: object) -> object:
241
+ return data
242
+
243
+
244
+ def _decode[T](url: str, body: bytes, parse: Callable[[object], T]) -> T:
245
+ """Decode and parse a body: run in a worker thread, it can be 617 KB.
246
+
247
+ The api_realtime sends every answer as ``application/problem+json``: the
248
+ content type is not looked at.
249
+ """
250
+ try:
251
+ data: object = json.loads(body)
252
+ except ValueError as err:
253
+ msg = f"Invalid JSON from {url}"
254
+ raise ArpaPiemonteParseError(msg) from err
255
+ return parse(data)
@@ -0,0 +1,52 @@
1
+ """Constants of aioarpapiemonte."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Final
6
+
7
+ GEOJSON_BASE_URL: Final = "https://www.arpa.piemonte.it/rischi_naturali/data/tr/"
8
+ """The real-time files of the Arpa website, read by its station pages.
9
+
10
+ Documented in the "Guida alla lettura dei dati in tempo reale" (v1.0,
11
+ 2024-10-03): hourly values in UTC, validated automatically, written again
12
+ every 15 minutes.
13
+ """
14
+
15
+ REALTIME_BASE_URL: Final = "https://utility.arpa.piemonte.it/api_realtime/"
16
+ """The api_realtime of Arpa Piemonte (OpenAPI at ``openapi.json``)."""
17
+
18
+ STATION_PAGE_URL: Final = (
19
+ "https://www.arpa.piemonte.it/rischi_naturali/snippets_arpa_graphs/"
20
+ "dettaglio_stazione/?id={sensor_id}&param={param}"
21
+ )
22
+ """The public page of a station on the Arpa website, to link the source."""
23
+
24
+ PIEMONTE_NETWORK: Final = "PIE"
25
+ """Network of the Piedmont stations (``id_network``)."""
26
+
27
+ ATTRIBUTION: Final = "Fonte: Arpa Piemonte - www.arpa.piemonte.it"
28
+ """Credit the data needs (CC BY 4.0, https://www.arpa.piemonte.it/note-legali)."""
29
+
30
+ DEFAULT_REQUEST_TIMEOUT: Final = 15.0
31
+ """Seconds to wait for an answer.
32
+
33
+ Measured on 2026-11-17: the files of the website answered in 0.08 s at the
34
+ median (0.13 s for the 617 KB station list, sent uncompressed), and the
35
+ api_realtime in 0.6 s for a page of 10,000 records.
36
+ """
37
+
38
+ DATA_PIE_PAGE_SIZE: Final = 10_000
39
+ """Records per page of the api_realtime, its maximum.
40
+
41
+ The last 3 days of a station are about 74 records: one page.
42
+ """
43
+
44
+ MAX_PAGES: Final = 10
45
+ """Pages read at most from the api_realtime, against a server that never ends.
46
+
47
+ The 3 days of the whole network are 27,750 records (measured on 2026-11-17):
48
+ 3 pages.
49
+ """
50
+
51
+ REPOSITORY_URL: Final = "https://github.com/webysther/aio-arpa-piemonte"
52
+ """Home of aioarpapiemonte, named in its User-Agent."""
@@ -0,0 +1,24 @@
1
+ """Exceptions raised by aioarpapiemonte."""
2
+
3
+ from __future__ import annotations
4
+
5
+
6
+ class ArpaPiemonteError(Exception):
7
+ """Base class of the aioarpapiemonte errors."""
8
+
9
+
10
+ class ArpaPiemonteConnectionError(ArpaPiemonteError):
11
+ """Arpa Piemonte could not be reached: network error, HTTP error or timeout."""
12
+
13
+
14
+ class ArpaPiemonteParseError(ArpaPiemonteError):
15
+ """Arpa Piemonte answered data that is not valid JSON or has another format."""
16
+
17
+
18
+ class ArpaPiemonteNotFoundError(ArpaPiemonteError):
19
+ """The file does not exist (HTTP 404).
20
+
21
+ A station does not publish every quantity it has a sensor for: the wind
22
+ speed of a station can be ``vels`` instead of ``velv``. Retrying does not
23
+ help.
24
+ """