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,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
File without changes
@@ -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,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -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.