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.
- aioarpapiemonte/__init__.py +66 -0
- aioarpapiemonte/_http.py +52 -0
- aioarpapiemonte/client.py +255 -0
- aioarpapiemonte/const.py +52 -0
- aioarpapiemonte/exceptions.py +24 -0
- aioarpapiemonte/models.py +481 -0
- aioarpapiemonte/parsers.py +344 -0
- aioarpapiemonte/py.typed +0 -0
- aioarpapiemonte/urls.py +82 -0
- aioarpapiemonte-0.1.0.dist-info/METADATA +210 -0
- aioarpapiemonte-0.1.0.dist-info/RECORD +13 -0
- aioarpapiemonte-0.1.0.dist-info/WHEEL +4 -0
- aioarpapiemonte-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,344 @@
|
|
|
1
|
+
"""Parsing of the real-time data of Arpa Piemonte, without I/O.
|
|
2
|
+
|
|
3
|
+
Two sources, measured on 2026-11-17:
|
|
4
|
+
|
|
5
|
+
- the files of the Arpa website: a GeoJSON Feature per station and quantity,
|
|
6
|
+
with hourly readings keyed by their time in UTC ("2026-11-17T02:00") and
|
|
7
|
+
their automatic validation; about the last 6 days;
|
|
8
|
+
- the api_realtime: JSON records with an offset in their times, about the
|
|
9
|
+
last 3 days. Every answer is ``application/problem+json``, even a 200, and
|
|
10
|
+
a query it cannot answer is a 200 whose fields are all null.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
import datetime as dt
|
|
16
|
+
import logging
|
|
17
|
+
import math
|
|
18
|
+
from collections.abc import Mapping
|
|
19
|
+
from typing import Final
|
|
20
|
+
|
|
21
|
+
from .const import PIEMONTE_NETWORK
|
|
22
|
+
from .exceptions import ArpaPiemonteParseError
|
|
23
|
+
from .models import (
|
|
24
|
+
Param,
|
|
25
|
+
ParamReading,
|
|
26
|
+
ParamSeries,
|
|
27
|
+
RealtimeField,
|
|
28
|
+
RealtimeRecord,
|
|
29
|
+
RealtimeStation,
|
|
30
|
+
Sensor,
|
|
31
|
+
Thresholds,
|
|
32
|
+
Validation,
|
|
33
|
+
)
|
|
34
|
+
from .urls import sensor_id
|
|
35
|
+
|
|
36
|
+
_LOGGER = logging.getLogger(__name__)
|
|
37
|
+
|
|
38
|
+
GEOJSON_TIME_FORMAT: Final = "%Y-%m-%dT%H:%M"
|
|
39
|
+
"""Format of the times of the files of the website, in UTC."""
|
|
40
|
+
|
|
41
|
+
THRESHOLD_KEYS: Final = (
|
|
42
|
+
"pre-alarm_threshold",
|
|
43
|
+
"guard_threshold",
|
|
44
|
+
"danger_threshold",
|
|
45
|
+
)
|
|
46
|
+
"""Thresholds in the level files (``idro``), in that order; with a hyphen."""
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def parse_sensors(data: object) -> tuple[Sensor, ...]:
|
|
50
|
+
"""Return the stations of the list of the website (``sensors.geojson``).
|
|
51
|
+
|
|
52
|
+
A station that cannot be read is left out (logged at debug level). Raises
|
|
53
|
+
:class:`ArpaPiemonteParseError` when the list has no station.
|
|
54
|
+
"""
|
|
55
|
+
features = _mapping(data, "The station list").get("features")
|
|
56
|
+
if not isinstance(features, list):
|
|
57
|
+
msg = "The station list has no features"
|
|
58
|
+
raise ArpaPiemonteParseError(msg)
|
|
59
|
+
sensors = []
|
|
60
|
+
for feature in features:
|
|
61
|
+
try:
|
|
62
|
+
sensors.append(_sensor(feature))
|
|
63
|
+
except ArpaPiemonteParseError as err:
|
|
64
|
+
_LOGGER.debug("Station left out: %s", err)
|
|
65
|
+
if not sensors:
|
|
66
|
+
msg = "The station list has no station"
|
|
67
|
+
raise ArpaPiemonteParseError(msg)
|
|
68
|
+
return tuple(sensors)
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def parse_series(data: object, param: Param, station: str | None = None) -> ParamSeries:
|
|
72
|
+
"""Return the readings of a file of a quantity of a station.
|
|
73
|
+
|
|
74
|
+
With ``station``, the file must be that station's. Raises
|
|
75
|
+
:class:`ArpaPiemonteParseError` when the file does not have the expected
|
|
76
|
+
format.
|
|
77
|
+
"""
|
|
78
|
+
properties = _mapping(_mapping(data, "The file").get("properties"), "properties")
|
|
79
|
+
found = _text(properties, "sensor")
|
|
80
|
+
if found is None or (station is not None and found != station):
|
|
81
|
+
msg = f"Asked for station {station}, the file is of station {found}"
|
|
82
|
+
raise ArpaPiemonteParseError(msg)
|
|
83
|
+
cells = _mapping(properties.get(param.value), f"The readings of {param.value}")
|
|
84
|
+
readings = sorted(
|
|
85
|
+
(
|
|
86
|
+
reading
|
|
87
|
+
for key, cell in cells.items()
|
|
88
|
+
if (reading := _param_reading(key, cell))
|
|
89
|
+
),
|
|
90
|
+
key=lambda reading: reading.time,
|
|
91
|
+
)
|
|
92
|
+
thresholds = None
|
|
93
|
+
if param is Param.LEVEL:
|
|
94
|
+
pre_alarm, guard, danger = (
|
|
95
|
+
_number(properties.get(key)) for key in THRESHOLD_KEYS
|
|
96
|
+
)
|
|
97
|
+
thresholds = Thresholds(pre_alarm, guard, danger)
|
|
98
|
+
return ParamSeries(
|
|
99
|
+
sensor_id=found,
|
|
100
|
+
param=param,
|
|
101
|
+
name=_text(properties, "name") or found,
|
|
102
|
+
readings=tuple(readings),
|
|
103
|
+
river=_text(properties, "river"),
|
|
104
|
+
basin=_text(properties, "basin"),
|
|
105
|
+
hydrometric_zero=_number(properties.get("zero_hydrometric")),
|
|
106
|
+
thresholds=thresholds,
|
|
107
|
+
description=_text(properties, "description"),
|
|
108
|
+
)
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
def parse_pie_anag(data: object) -> tuple[RealtimeStation, ...]:
|
|
112
|
+
"""Return the stations of Piedmont of the api_realtime (``pie_anag``).
|
|
113
|
+
|
|
114
|
+
A station that cannot be read is left out (logged at debug level). Raises
|
|
115
|
+
:class:`ArpaPiemonteParseError` when the answer is not a list of stations.
|
|
116
|
+
"""
|
|
117
|
+
if not isinstance(data, list):
|
|
118
|
+
msg = "The stations of the api_realtime are not a list"
|
|
119
|
+
raise ArpaPiemonteParseError(msg)
|
|
120
|
+
stations = []
|
|
121
|
+
for record in data:
|
|
122
|
+
if (
|
|
123
|
+
not isinstance(record, Mapping)
|
|
124
|
+
or record.get("id_network") != PIEMONTE_NETWORK
|
|
125
|
+
):
|
|
126
|
+
continue
|
|
127
|
+
try:
|
|
128
|
+
stations.append(_realtime_station(record))
|
|
129
|
+
except ArpaPiemonteParseError as err:
|
|
130
|
+
_LOGGER.debug("Station left out: %s", err)
|
|
131
|
+
if not stations:
|
|
132
|
+
msg = "The api_realtime has no station of Piedmont"
|
|
133
|
+
raise ArpaPiemonteParseError(msg)
|
|
134
|
+
return tuple(stations)
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def parse_data_pie_page(
|
|
138
|
+
data: object, station_code: str
|
|
139
|
+
) -> tuple[list[RealtimeRecord], int]:
|
|
140
|
+
"""Return the records of a station in a page of the api_realtime, and its pages.
|
|
141
|
+
|
|
142
|
+
A page without records has ``data`` null. Records of other stations are
|
|
143
|
+
left out. Raises :class:`ArpaPiemonteParseError` when the page does not
|
|
144
|
+
have the expected format.
|
|
145
|
+
"""
|
|
146
|
+
page = _mapping(data, "The page")
|
|
147
|
+
total_pages = page.get("total_pages")
|
|
148
|
+
if total_pages is None:
|
|
149
|
+
total_pages = 0
|
|
150
|
+
if isinstance(total_pages, bool) or not isinstance(total_pages, int):
|
|
151
|
+
msg = f"total_pages is not a number: {total_pages!r}"
|
|
152
|
+
raise ArpaPiemonteParseError(msg)
|
|
153
|
+
items = page.get("data")
|
|
154
|
+
if items is None:
|
|
155
|
+
return [], total_pages
|
|
156
|
+
if not isinstance(items, list):
|
|
157
|
+
msg = "The records are not a list"
|
|
158
|
+
raise ArpaPiemonteParseError(msg)
|
|
159
|
+
records = [
|
|
160
|
+
_realtime_record(item)
|
|
161
|
+
for item in items
|
|
162
|
+
if isinstance(item, Mapping) and item.get("station_code") == station_code
|
|
163
|
+
]
|
|
164
|
+
return records, total_pages
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
def parse_status(data: object) -> str:
|
|
168
|
+
"""Return the status of the api_realtime ("healthy")."""
|
|
169
|
+
status = _text(_mapping(data, "The status"), "status")
|
|
170
|
+
if status is None:
|
|
171
|
+
msg = "The api_realtime gave no status"
|
|
172
|
+
raise ArpaPiemonteParseError(msg)
|
|
173
|
+
return status
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def parse_decimal(value: object) -> float | None:
|
|
177
|
+
"""Return a number the api_realtime writes as text ("2.3", "3", "").
|
|
178
|
+
|
|
179
|
+
None for an empty or unreadable value.
|
|
180
|
+
"""
|
|
181
|
+
if isinstance(value, str):
|
|
182
|
+
text = value.strip().replace(",", ".")
|
|
183
|
+
if not text:
|
|
184
|
+
return None
|
|
185
|
+
try:
|
|
186
|
+
return _number(float(text))
|
|
187
|
+
except ValueError:
|
|
188
|
+
_LOGGER.debug("Not a number: %r", value)
|
|
189
|
+
return None
|
|
190
|
+
return _number(value)
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
def _sensor(feature: object) -> Sensor:
|
|
194
|
+
feature = _mapping(feature, "A station")
|
|
195
|
+
properties = _mapping(feature.get("properties"), "A station")
|
|
196
|
+
identifier = _text(properties, "sensor")
|
|
197
|
+
if identifier is None:
|
|
198
|
+
msg = "A station has no identifier"
|
|
199
|
+
raise ArpaPiemonteParseError(msg)
|
|
200
|
+
coordinates = _mapping(feature.get("geometry"), "A station").get("coordinates")
|
|
201
|
+
if not isinstance(coordinates, list) or len(coordinates) < 2: # noqa: PLR2004 - longitude and latitude
|
|
202
|
+
msg = f"Station {identifier} has no coordinates"
|
|
203
|
+
raise ArpaPiemonteParseError(msg)
|
|
204
|
+
longitude, latitude = _number(coordinates[0]), _number(coordinates[1])
|
|
205
|
+
if longitude is None or latitude is None:
|
|
206
|
+
msg = f"Station {identifier} has no coordinates"
|
|
207
|
+
raise ArpaPiemonteParseError(msg)
|
|
208
|
+
published = properties.get("sensors")
|
|
209
|
+
names = [str(name) for name in published] if isinstance(published, Mapping) else []
|
|
210
|
+
known = {param.value: param for param in Param}
|
|
211
|
+
return Sensor(
|
|
212
|
+
id=identifier,
|
|
213
|
+
name=_text(properties, "name") or identifier,
|
|
214
|
+
latitude=latitude,
|
|
215
|
+
longitude=longitude,
|
|
216
|
+
altitude=_number(properties.get("quote")),
|
|
217
|
+
params=frozenset(known[name] for name in names if name in known),
|
|
218
|
+
municipality=_text(properties, "municipality"),
|
|
219
|
+
river=_text(properties, "river"),
|
|
220
|
+
basin=_text(properties, "basin"),
|
|
221
|
+
other_params=tuple(sorted(name for name in names if name not in known)),
|
|
222
|
+
)
|
|
223
|
+
|
|
224
|
+
|
|
225
|
+
def _param_reading(key: str, cell: object) -> ParamReading | None:
|
|
226
|
+
"""Return a reading of a file; None for a cell without value."""
|
|
227
|
+
if not isinstance(cell, Mapping):
|
|
228
|
+
msg = f"The reading of {key!r} is not an object"
|
|
229
|
+
raise ArpaPiemonteParseError(msg)
|
|
230
|
+
value = cell.get("value")
|
|
231
|
+
if value is None:
|
|
232
|
+
return None
|
|
233
|
+
number = _number(value)
|
|
234
|
+
if number is None:
|
|
235
|
+
msg = f"The reading of {key!r} is not a number: {value!r}"
|
|
236
|
+
raise ArpaPiemonteParseError(msg)
|
|
237
|
+
valid_type = cell.get("valid_type")
|
|
238
|
+
valid_type = valid_type if isinstance(valid_type, str) else None
|
|
239
|
+
return ParamReading(
|
|
240
|
+
time=_utc_time(key),
|
|
241
|
+
value=number,
|
|
242
|
+
validation=Validation.of(valid_type),
|
|
243
|
+
valid_type=valid_type,
|
|
244
|
+
)
|
|
245
|
+
|
|
246
|
+
|
|
247
|
+
def _utc_time(key: str) -> dt.datetime:
|
|
248
|
+
try:
|
|
249
|
+
return dt.datetime.strptime(key, GEOJSON_TIME_FORMAT).replace(tzinfo=dt.UTC)
|
|
250
|
+
except ValueError as err:
|
|
251
|
+
msg = f"Not a time: {key!r}"
|
|
252
|
+
raise ArpaPiemonteParseError(msg) from err
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
def _realtime_station(record: Mapping[str, object]) -> RealtimeStation:
|
|
256
|
+
code = _text(record, "station_code")
|
|
257
|
+
name = _text(record, "name")
|
|
258
|
+
latitude = _number(record.get("lat"))
|
|
259
|
+
longitude = _number(record.get("lng"))
|
|
260
|
+
if code is None or name is None or latitude is None or longitude is None:
|
|
261
|
+
msg = f"Station without code, name or coordinates: {code!r}"
|
|
262
|
+
raise ArpaPiemonteParseError(msg)
|
|
263
|
+
return RealtimeStation(
|
|
264
|
+
station_code=code,
|
|
265
|
+
name=name,
|
|
266
|
+
latitude=latitude,
|
|
267
|
+
longitude=longitude,
|
|
268
|
+
altitude=_number(record.get("quote")),
|
|
269
|
+
station_type=_text(record, "station_type") or "",
|
|
270
|
+
municipality=_text(record, "municipality") or "",
|
|
271
|
+
municipality_code=_text(record, "municipality_code") or "",
|
|
272
|
+
river=_text(record, "river_name"),
|
|
273
|
+
basin=_text(record, "basin"),
|
|
274
|
+
hydrometric_zero=parse_decimal(record.get("hydrometric_zero")),
|
|
275
|
+
thresholds=Thresholds(
|
|
276
|
+
parse_decimal(record.get("threshold_level")),
|
|
277
|
+
parse_decimal(record.get("guard_threshold")),
|
|
278
|
+
parse_decimal(record.get("danger_threshold")),
|
|
279
|
+
),
|
|
280
|
+
sensor_id=_sensor_id(record),
|
|
281
|
+
)
|
|
282
|
+
|
|
283
|
+
|
|
284
|
+
def _sensor_id(record: Mapping[str, object]) -> str | None:
|
|
285
|
+
"""Return the identifier on the website of a station of the api_realtime."""
|
|
286
|
+
municipality = record.get("codice_istat_comune")
|
|
287
|
+
number = record.get("progr_punto_com")
|
|
288
|
+
if isinstance(number, str) and number.isdigit():
|
|
289
|
+
number = int(number)
|
|
290
|
+
if not isinstance(municipality, str) or not isinstance(number, int):
|
|
291
|
+
return None
|
|
292
|
+
try:
|
|
293
|
+
return sensor_id(municipality, number)
|
|
294
|
+
except ValueError:
|
|
295
|
+
return None
|
|
296
|
+
|
|
297
|
+
|
|
298
|
+
def _realtime_record(item: Mapping[str, object]) -> RealtimeRecord:
|
|
299
|
+
date = item.get("date")
|
|
300
|
+
if not isinstance(date, str):
|
|
301
|
+
msg = f"A record has no date: {date!r}"
|
|
302
|
+
raise ArpaPiemonteParseError(msg)
|
|
303
|
+
try:
|
|
304
|
+
time = dt.datetime.fromisoformat(date)
|
|
305
|
+
except ValueError as err:
|
|
306
|
+
msg = f"Not a date: {date!r}"
|
|
307
|
+
raise ArpaPiemonteParseError(msg) from err
|
|
308
|
+
if time.tzinfo is None:
|
|
309
|
+
msg = f"A date without offset: {date!r}"
|
|
310
|
+
raise ArpaPiemonteParseError(msg)
|
|
311
|
+
values = []
|
|
312
|
+
for field in RealtimeField:
|
|
313
|
+
raw = item.get(field.value)
|
|
314
|
+
if raw is None:
|
|
315
|
+
continue
|
|
316
|
+
number = _number(raw)
|
|
317
|
+
if number is None:
|
|
318
|
+
msg = f"{field.value} is not a number: {raw!r}"
|
|
319
|
+
raise ArpaPiemonteParseError(msg)
|
|
320
|
+
values.append((field, number))
|
|
321
|
+
return RealtimeRecord(time.astimezone(dt.UTC), tuple(values))
|
|
322
|
+
|
|
323
|
+
|
|
324
|
+
def _mapping(value: object, what: str) -> Mapping[str, object]:
|
|
325
|
+
if not isinstance(value, Mapping):
|
|
326
|
+
msg = f"{what} is not an object"
|
|
327
|
+
raise ArpaPiemonteParseError(msg)
|
|
328
|
+
return value
|
|
329
|
+
|
|
330
|
+
|
|
331
|
+
def _text(record: Mapping[str, object], key: str) -> str | None:
|
|
332
|
+
"""Return a text of a record, stripped; None when missing or empty."""
|
|
333
|
+
value = record.get(key)
|
|
334
|
+
if not isinstance(value, str) or not value.strip():
|
|
335
|
+
return None
|
|
336
|
+
return value.strip()
|
|
337
|
+
|
|
338
|
+
|
|
339
|
+
def _number(value: object) -> float | None:
|
|
340
|
+
"""Return a finite number as a float; None for anything else."""
|
|
341
|
+
if isinstance(value, bool) or not isinstance(value, int | float):
|
|
342
|
+
return None
|
|
343
|
+
number = float(value)
|
|
344
|
+
return number if math.isfinite(number) else None
|
aioarpapiemonte/py.typed
ADDED
|
File without changes
|
aioarpapiemonte/urls.py
ADDED
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
"""Addresses of the real-time data of Arpa Piemonte."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import re
|
|
6
|
+
from typing import TYPE_CHECKING, Final
|
|
7
|
+
from urllib.parse import urlencode
|
|
8
|
+
|
|
9
|
+
from .const import DATA_PIE_PAGE_SIZE, GEOJSON_BASE_URL, REALTIME_BASE_URL
|
|
10
|
+
|
|
11
|
+
if TYPE_CHECKING:
|
|
12
|
+
from .models import Param
|
|
13
|
+
|
|
14
|
+
_SENSOR_ID: Final = re.compile(r"\d{9}")
|
|
15
|
+
"""An identifier of a station on the Arpa website: 9 digits."""
|
|
16
|
+
|
|
17
|
+
_STATION_CODE: Final = re.compile(r"[0-9A-Za-z]+")
|
|
18
|
+
"""A code of a station in the network: letters and digits ("188", "S4059")."""
|
|
19
|
+
|
|
20
|
+
_MUNICIPALITY_CODE: Final = re.compile(r"\d{6}")
|
|
21
|
+
"""An ISTAT code of a municipality: 6 digits."""
|
|
22
|
+
|
|
23
|
+
_MAX_NUMBER: Final = 999
|
|
24
|
+
"""Highest number of a station in its municipality: it has 3 digits."""
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def sensor_id(municipality_code: str, number: int) -> str:
|
|
28
|
+
"""Return the identifier of a station on the Arpa website.
|
|
29
|
+
|
|
30
|
+
It is the ISTAT code of the municipality the station was set up in
|
|
31
|
+
(``codice_istat_comune``, which can be an old code: Pray is 002105, from
|
|
32
|
+
the province of Vercelli, while its code is now 096050) and the number of
|
|
33
|
+
the station in it (``progr_punto_com``), in 3 digits: "002105900".
|
|
34
|
+
|
|
35
|
+
Raises ``ValueError`` when they are not 6 digits and a number up to 999.
|
|
36
|
+
"""
|
|
37
|
+
if not _MUNICIPALITY_CODE.fullmatch(municipality_code) or not (
|
|
38
|
+
0 <= number <= _MAX_NUMBER
|
|
39
|
+
):
|
|
40
|
+
msg = f"Invalid station: {municipality_code!r}, {number!r}"
|
|
41
|
+
raise ValueError(msg)
|
|
42
|
+
return f"{municipality_code}{number:03d}"
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def sensors_url() -> str:
|
|
46
|
+
"""Return the URL of the list of the stations of the website."""
|
|
47
|
+
return f"{GEOJSON_BASE_URL}sensors.geojson"
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def series_url(param: Param, station: str) -> str:
|
|
51
|
+
"""Return the URL of the readings of a quantity of a station.
|
|
52
|
+
|
|
53
|
+
Raises ``ValueError`` when the station is not 9 digits.
|
|
54
|
+
"""
|
|
55
|
+
if not _SENSOR_ID.fullmatch(station):
|
|
56
|
+
msg = f"Invalid station identifier: {station!r}"
|
|
57
|
+
raise ValueError(msg)
|
|
58
|
+
return f"{GEOJSON_BASE_URL}{param.value}/{station}.geojson"
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def status_url() -> str:
|
|
62
|
+
"""Return the URL of the status of the api_realtime."""
|
|
63
|
+
return f"{REALTIME_BASE_URL}status"
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def pie_anag_url() -> str:
|
|
67
|
+
"""Return the URL of the stations of the api_realtime."""
|
|
68
|
+
return f"{REALTIME_BASE_URL}pie_anag"
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def data_pie_url(station_code: str, page: int = 1) -> str:
|
|
72
|
+
"""Return the URL of a page of the records of a station.
|
|
73
|
+
|
|
74
|
+
Raises ``ValueError`` for a code that is not letters and digits.
|
|
75
|
+
"""
|
|
76
|
+
if not _STATION_CODE.fullmatch(station_code):
|
|
77
|
+
msg = f"Invalid station code: {station_code!r}"
|
|
78
|
+
raise ValueError(msg)
|
|
79
|
+
query = urlencode(
|
|
80
|
+
{"station_code": station_code, "page_size": DATA_PIE_PAGE_SIZE, "page": page}
|
|
81
|
+
)
|
|
82
|
+
return f"{REALTIME_BASE_URL}data_pie?{query}"
|
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: aioarpapiemonte
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Async client for the real-time data of the stations of Arpa Piemonte: river levels, rain, temperature and snow, from its website files and its api_realtime
|
|
5
|
+
Project-URL: Homepage, https://github.com/webysther/aio-arpa-piemonte
|
|
6
|
+
Project-URL: Changelog, https://github.com/webysther/aio-arpa-piemonte/blob/main/CHANGELOG.md
|
|
7
|
+
Project-URL: Issues, https://github.com/webysther/aio-arpa-piemonte/issues
|
|
8
|
+
Author: Webysther Sperandio
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: api_realtime,arpa piemonte,asyncio,hydrometer,idrometro,italy,piemonte,river level,weather
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Framework :: AsyncIO
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Natural Language :: English
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
|
|
22
|
+
Classifier: Topic :: Scientific/Engineering :: Hydrology
|
|
23
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
24
|
+
Classifier: Typing :: Typed
|
|
25
|
+
Requires-Python: >=3.13
|
|
26
|
+
Requires-Dist: aiohttp>=3.10
|
|
27
|
+
Requires-Dist: tzdata; sys_platform == 'win32'
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
|
|
30
|
+
# aioarpapiemonte
|
|
31
|
+
|
|
32
|
+
Async Python client for the real-time data of the stations of
|
|
33
|
+
[Arpa Piemonte](https://www.arpa.piemonte.it): river levels, rain,
|
|
34
|
+
temperature, humidity, wind and snow of the 374 stations of the Piedmont
|
|
35
|
+
network, from its two official sources:
|
|
36
|
+
|
|
37
|
+
- the **files of the Arpa website**, read by its station pages: hourly
|
|
38
|
+
readings with their automatic validation, about 40 minutes after the hour,
|
|
39
|
+
for the last 6 days, with the thresholds of the hydrometers;
|
|
40
|
+
- the **[api_realtime](https://utility.arpa.piemonte.it/api_realtime/docs)**:
|
|
41
|
+
every quantity of a station in one request, about 3 hours and 40 minutes
|
|
42
|
+
after the hour, for the last 3 days.
|
|
43
|
+
|
|
44
|
+
asyncio and aiohttp, fully typed (mypy strict). The files of the website are
|
|
45
|
+
asked whether they changed (`If-None-Match`, `If-Modified-Since`): an
|
|
46
|
+
unchanged file is neither downloaded nor parsed again.
|
|
47
|
+
|
|
48
|
+
For the readings every 30 minutes of the Meteo 3R app of Arpa Piemonte, see
|
|
49
|
+
[aiometeo3r](https://github.com/webysther/aio-meteo3r).
|
|
50
|
+
|
|
51
|
+
## Installation
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
pip install aioarpapiemonte
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Python 3.13 or newer.
|
|
58
|
+
|
|
59
|
+
## Usage
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
import asyncio
|
|
63
|
+
|
|
64
|
+
from aioarpapiemonte import ArpaPiemonteClient, Param, RealtimeField
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
async def main() -> None:
|
|
68
|
+
async with ArpaPiemonteClient() as client:
|
|
69
|
+
# The website: hourly readings with their validation
|
|
70
|
+
series = await client.get_series(Param.LEVEL, "002105900") # Pray Sessera
|
|
71
|
+
latest = series.latest()
|
|
72
|
+
if latest is not None:
|
|
73
|
+
status = series.thresholds.status(latest.value) if series.thresholds else None
|
|
74
|
+
print(f"{series.name}: {latest.value} m at {latest.time:%H:%M} UTC,"
|
|
75
|
+
f" {latest.validation}, {status}")
|
|
76
|
+
|
|
77
|
+
# The api_realtime: every quantity in one request, a few hours later
|
|
78
|
+
data = await client.get_realtime_data("188")
|
|
79
|
+
rain = data.latest(RealtimeField.CUM_RAIN_24H)
|
|
80
|
+
if rain is not None:
|
|
81
|
+
print(f"Rain in 24 h: {rain.value} mm at {rain.time:%H:%M} UTC")
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
asyncio.run(main())
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
```text
|
|
88
|
+
PRAY SESSERA: 0.86 m at 02:00 UTC, to_verify, normal
|
|
89
|
+
Rain in 24 h: 0.0 mm at 23:00 UTC
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### Two identifiers
|
|
93
|
+
|
|
94
|
+
A station has a code in the network (`"188"`, the api_realtime and Meteo 3R)
|
|
95
|
+
and an identifier on the website (`"002105900"`). The website one is the ISTAT
|
|
96
|
+
code of the municipality when the station was set up, which can be an old
|
|
97
|
+
code, and the number of the station in it: it cannot be made from the current
|
|
98
|
+
ISTAT code. `get_realtime_stations()` gives both:
|
|
99
|
+
|
|
100
|
+
```python
|
|
101
|
+
import asyncio
|
|
102
|
+
|
|
103
|
+
from aioarpapiemonte import ArpaPiemonteClient
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
async def main() -> None:
|
|
107
|
+
async with ArpaPiemonteClient() as client:
|
|
108
|
+
stations = await client.get_realtime_stations()
|
|
109
|
+
pray = next(s for s in stations if s.station_code == "188")
|
|
110
|
+
print(f"{pray.name}: station {pray.station_code}, website {pray.sensor_id},"
|
|
111
|
+
f" municipality {pray.municipality_code}")
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
asyncio.run(main())
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
```text
|
|
118
|
+
PRAY SESSERA: station 188, website 002105900, municipality 096050
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Reference
|
|
122
|
+
|
|
123
|
+
### Client
|
|
124
|
+
|
|
125
|
+
`ArpaPiemonteClient(session=None, *, request_timeout=15.0, user_agent=None)`
|
|
126
|
+
|
|
127
|
+
Pass the `aiohttp.ClientSession` of your application: the client never closes
|
|
128
|
+
it. Without one, use the client as an async context manager; its own session
|
|
129
|
+
keeps no cookies (the website sets one on every answer).
|
|
130
|
+
|
|
131
|
+
| Method | Source | Returns |
|
|
132
|
+
| --- | --- | --- |
|
|
133
|
+
| `get_sensors()` | website, `sensors.geojson` (617 KB) | `Sensor` of each station, with the quantities it publishes |
|
|
134
|
+
| `get_series(param, station)` | website, `<param>/<station>.geojson` | `ParamSeries`: hourly readings, validation, thresholds |
|
|
135
|
+
| `get_realtime_stations()` | api_realtime, `pie_anag` | `RealtimeStation`, with `sensor_id` |
|
|
136
|
+
| `get_realtime_data(station_code)` | api_realtime, `data_pie` | `RealtimeData`: records of the last 3 days |
|
|
137
|
+
| `get_realtime_status()` | api_realtime, `status` | `"healthy"` |
|
|
138
|
+
|
|
139
|
+
`user_agent` names your application in the requests. The default is
|
|
140
|
+
`aioarpapiemonte/<version> (+<repository>)`; it is sent with each request, so
|
|
141
|
+
it replaces the one of a shared session.
|
|
142
|
+
|
|
143
|
+
### Quantities
|
|
144
|
+
|
|
145
|
+
| `Param` (website) | Unit | `RealtimeField` (api_realtime) | Unit |
|
|
146
|
+
| --- | --- | --- | --- |
|
|
147
|
+
| `LEVEL` (`idro`) | m | `HYDROMETRIC_LEVEL` | m |
|
|
148
|
+
| `TEMPERATURE` (`terma`) | °C | `AIR_TEMPERATURE` | °C |
|
|
149
|
+
| `HUMIDITY` (`igro`) | % | `HUMIDITY` | % |
|
|
150
|
+
| `RAIN_10_MIN` (`pluv`) | mm, see below | `CUM_RAIN_1H` ... `CUM_RAIN_24H` | mm |
|
|
151
|
+
| `WIND_SPEED` (`velv`), `WIND_SPEED_SECONDARY` (`vels`), `GUST_SPEED` (`velr`) | m/s | `WIND`, `GUST_OF_WIND` | km/h |
|
|
152
|
+
| `WIND_DIRECTION` (`dirv`) | ° | `WIND_DIRECTION`, `GUST_DIRECTION` | ° |
|
|
153
|
+
| `SNOW_DEPTH` (`nivo`) | cm | `SNOW_HEIGHT` | cm |
|
|
154
|
+
| `PRESSURE` (`baro`) | hPa | | |
|
|
155
|
+
| `RADIATION` (`radd`) | W/m² | | |
|
|
156
|
+
|
|
157
|
+
The rain of the website files is described by them as "Livello pioggia sui 10
|
|
158
|
+
minuti", and was lower than the rain of the hour of the api_realtime in 5 of
|
|
159
|
+
73 hours: it is not the rain of the hour. For it, read `CUM_RAIN_1H`.
|
|
160
|
+
|
|
161
|
+
### Validation
|
|
162
|
+
|
|
163
|
+
Each reading of the website has a `Validation`, from the first letter of its
|
|
164
|
+
code (`valid_type`), as the station pages color it: `OK` (green),
|
|
165
|
+
`TO_VERIFY` (V..., yellow: often the latest hours), `SUSPECT` (W..., orange),
|
|
166
|
+
`INVALID` (A..., red), `MISSING` (M... or none, grey). `ParamSeries.latest()`
|
|
167
|
+
returns the newest reading that is not invalid nor missing: a fast rise of a
|
|
168
|
+
river can be suspect while true.
|
|
169
|
+
|
|
170
|
+
### Errors
|
|
171
|
+
|
|
172
|
+
All errors derive from `ArpaPiemonteError`:
|
|
173
|
+
|
|
174
|
+
- `ArpaPiemonteConnectionError`: network error, error status, timeout;
|
|
175
|
+
- `ArpaPiemonteParseError`: an answer that is not the expected format;
|
|
176
|
+
- `ArpaPiemonteNotFoundError`: the file does not exist, for example a quantity
|
|
177
|
+
the station does not publish.
|
|
178
|
+
|
|
179
|
+
Invalid identifiers raise `ValueError` before any request.
|
|
180
|
+
|
|
181
|
+
## Data source and attribution
|
|
182
|
+
|
|
183
|
+
The data is by **Arpa Piemonte**, under the
|
|
184
|
+
[Creative Commons Attribution 4.0](https://creativecommons.org/licenses/by/4.0/)
|
|
185
|
+
license ([legal notes](https://www.arpa.piemonte.it/note-legali)). Credit it as
|
|
186
|
+
`ATTRIBUTION` does, "Fonte: Arpa Piemonte - www.arpa.piemonte.it", and link the
|
|
187
|
+
page of the station when you can (`ParamSeries.page_url`).
|
|
188
|
+
|
|
189
|
+
aioarpapiemonte is **not affiliated with or endorsed by Arpa Piemonte**. The
|
|
190
|
+
real-time data is validated automatically only, and may be corrected later by
|
|
191
|
+
Arpa Piemonte; it comes without any guarantee of availability. Do not rely on
|
|
192
|
+
it for safety: for alerts, follow the official bulletins and the civil
|
|
193
|
+
protection.
|
|
194
|
+
|
|
195
|
+
## Development
|
|
196
|
+
|
|
197
|
+
```bash
|
|
198
|
+
python -m venv .venv && . .venv/bin/activate
|
|
199
|
+
pip install --editable . --group dev # pip >= 25.1
|
|
200
|
+
ruff format --check . && ruff check .
|
|
201
|
+
mypy
|
|
202
|
+
pytest --cov
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
The tests never reach Arpa Piemonte: a local HTTPS server answers for its hosts
|
|
206
|
+
(`tests/server.py`), with real files in `tests/fixtures/real`.
|
|
207
|
+
|
|
208
|
+
## License
|
|
209
|
+
|
|
210
|
+
MIT, see [LICENSE](https://github.com/webysther/aio-arpa-piemonte/blob/main/LICENSE).
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
aioarpapiemonte/__init__.py,sha256=axLEEI3c3z7bFEIwEUZSVmIbZ2eXbVtm6W7MCBuxOuY,1600
|
|
2
|
+
aioarpapiemonte/_http.py,sha256=_94c21pVO_2FKyTFUIMrtCUIu3mBPtLgFPeQr6cY-KM,1737
|
|
3
|
+
aioarpapiemonte/client.py,sha256=AKZSLDQZpQu6AS4ttSKx6yrQNb8UVOkx3fRrIu8CvAQ,9752
|
|
4
|
+
aioarpapiemonte/const.py,sha256=nLaMvnKHEvNA7w-__xlGyz_me0AvRTKKJBPPBQdeANk,1799
|
|
5
|
+
aioarpapiemonte/exceptions.py,sha256=JBsMNmN4-hLrdVYGhK0eFqqF3zARUYoZCi3TppGJ-Cs,715
|
|
6
|
+
aioarpapiemonte/models.py,sha256=AsOdQvTR-Dr3dLOtT3Lz-CgtTstTDwIQo96shLhCQXE,15884
|
|
7
|
+
aioarpapiemonte/parsers.py,sha256=o33Iik6Qf22ee5Dm8C_29Y-s2DFFOPKeBZg2ND3eMks,12394
|
|
8
|
+
aioarpapiemonte/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
9
|
+
aioarpapiemonte/urls.py,sha256=BpENC64sFPtGCYD_3MJ4C6O3WGVoSKj8ouNig6tZiIA,2786
|
|
10
|
+
aioarpapiemonte-0.1.0.dist-info/METADATA,sha256=rkb7J0kL8rtO2EuaSAZLl5pQJ5DNCmkfj7YDFwZWZyQ,8292
|
|
11
|
+
aioarpapiemonte-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
12
|
+
aioarpapiemonte-0.1.0.dist-info/licenses/LICENSE,sha256=7e05He_KKPPL7MwEgG0N4Kg9ZhntAS5kHT9dHvkgoFU,1076
|
|
13
|
+
aioarpapiemonte-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Webysther Sperandio
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|