aioarpapiemonte 0.1.1__tar.gz → 0.2.0__tar.gz

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.
Files changed (43) hide show
  1. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/PKG-INFO +143 -12
  2. aioarpapiemonte-0.2.0/README.md +312 -0
  3. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/pyproject.toml +5 -1
  4. aioarpapiemonte-0.2.0/src/aioarpapiemonte/__init__.py +123 -0
  5. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/src/aioarpapiemonte/_http.py +6 -3
  6. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/src/aioarpapiemonte/client.py +107 -9
  7. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/src/aioarpapiemonte/const.py +30 -0
  8. aioarpapiemonte-0.2.0/src/aioarpapiemonte/data/IT-21_micro-regions.geojson +1 -0
  9. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/src/aioarpapiemonte/exceptions.py +2 -1
  10. aioarpapiemonte-0.2.0/src/aioarpapiemonte/geo.py +205 -0
  11. aioarpapiemonte-0.2.0/src/aioarpapiemonte/models.py +958 -0
  12. aioarpapiemonte-0.2.0/src/aioarpapiemonte/parsers.py +698 -0
  13. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/src/aioarpapiemonte/urls.py +40 -2
  14. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/__init__.py +10 -1
  15. aioarpapiemonte-0.2.0/tests/fixtures/real/2026-04-18-IT-21.json +377 -0
  16. aioarpapiemonte-0.2.0/tests/fixtures/real/caldo_torino.json +55 -0
  17. aioarpapiemonte-0.2.0/tests/fixtures/real/sismica_tabella.json +394 -0
  18. aioarpapiemonte-0.2.0/tests/fixtures/real/widget_005005.json +58 -0
  19. aioarpapiemonte-0.2.0/tests/fixtures/real/widget_096050.json +58 -0
  20. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/server.py +2 -2
  21. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/test_client.py +88 -1
  22. aioarpapiemonte-0.2.0/tests/test_geo.py +131 -0
  23. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/test_models.py +113 -4
  24. aioarpapiemonte-0.2.0/tests/test_risks.py +446 -0
  25. aioarpapiemonte-0.1.1/README.md +0 -181
  26. aioarpapiemonte-0.1.1/src/aioarpapiemonte/__init__.py +0 -66
  27. aioarpapiemonte-0.1.1/src/aioarpapiemonte/models.py +0 -481
  28. aioarpapiemonte-0.1.1/src/aioarpapiemonte/parsers.py +0 -349
  29. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/.gitignore +0 -0
  30. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/LICENSE +0 -0
  31. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/src/aioarpapiemonte/py.typed +0 -0
  32. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/conftest.py +0 -0
  33. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/fixtures/real/data_pie_188.json +0 -0
  34. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/fixtures/real/data_pie_999.json +0 -0
  35. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/fixtures/real/idro_002105900.geojson +0 -0
  36. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/fixtures/real/igro_001022905.geojson +0 -0
  37. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/fixtures/real/nivo_001019900.geojson +0 -0
  38. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/fixtures/real/pie_anag.json +0 -0
  39. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/fixtures/real/pluv_001013900.geojson +0 -0
  40. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/fixtures/real/sensors.geojson +0 -0
  41. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/fixtures/real/status.json +0 -0
  42. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/fixtures/real/terma_002105900.geojson +0 -0
  43. {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/test_parsers.py +0 -0
@@ -1,14 +1,14 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: aioarpapiemonte
3
- Version: 0.1.1
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
3
+ Version: 0.2.0
4
+ Summary: Async client for the data of Arpa Piemonte: river levels, rain, temperature and snow of its stations, alerts, earthquakes, heat waves and avalanche bulletins
5
5
  Project-URL: Homepage, https://github.com/webysther/aio-arpa-piemonte
6
6
  Project-URL: Changelog, https://github.com/webysther/aio-arpa-piemonte/blob/main/CHANGELOG.md
7
7
  Project-URL: Issues, https://github.com/webysther/aio-arpa-piemonte/issues
8
8
  Author: Webysther Sperandio
9
9
  License-Expression: MIT
10
10
  License-File: LICENSE
11
- Keywords: api_realtime,arpa piemonte,asyncio,hydrometer,idrometro,italy,piemonte,river level,weather
11
+ Keywords: allerta,api_realtime,arpa piemonte,asyncio,avalanche,earthquake,heat wave,hydrometer,idrometro,italy,piemonte,river level,weather
12
12
  Classifier: Development Status :: 3 - Alpha
13
13
  Classifier: Framework :: AsyncIO
14
14
  Classifier: Intended Audience :: Developers
@@ -41,9 +41,13 @@ network, from its two official sources:
41
41
  every quantity of a station in one request, about 3 hours and 40 minutes
42
42
  after the hour, for the last 3 days.
43
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.
44
+ It also reads the natural risks: the alerts of each municipality, the
45
+ earthquakes and the heat waves of the Arpa website, and the avalanche
46
+ bulletins of Piedmont, published by AINEVA through EAWS.
47
+
48
+ asyncio and aiohttp, fully typed (mypy strict). The files are asked whether
49
+ they changed (`If-None-Match`, `If-Modified-Since`): an unchanged file is
50
+ neither downloaded nor parsed again.
47
51
 
48
52
  For the readings every 30 minutes of the Meteo 3R app of Arpa Piemonte, see
49
53
  [aiometeo3r](https://github.com/webysther/aio-meteo3r).
@@ -118,6 +122,84 @@ asyncio.run(main())
118
122
  PRAY SESSERA: station 188, website 002105900, municipality 096050
119
123
  ```
120
124
 
125
+ ### Natural risks
126
+
127
+ ```python
128
+ import asyncio
129
+ import datetime as dt
130
+ from zoneinfo import ZoneInfo
131
+
132
+ from aioarpapiemonte import (
133
+ MICRO_REGION_NAMES,
134
+ ArpaPiemonteClient,
135
+ ArpaPiemonteNotFoundError,
136
+ HeatCity,
137
+ RiskType,
138
+ )
139
+
140
+ PRAY = (45.6739, 8.22167)
141
+
142
+
143
+ async def main() -> None:
144
+ today = dt.datetime.now(ZoneInfo("Europe/Rome")).date()
145
+ tomorrow = today + dt.timedelta(days=1)
146
+ async with ArpaPiemonteClient() as client:
147
+ # The alerts of a municipality, by its current ISTAT code
148
+ alerts = await client.get_municipality_alerts("096050")
149
+ print(f"{alerts.name} ({', '.join(alerts.zones)}), bulletin {alerts.bulletin}")
150
+ for risk in RiskType:
151
+ print(f" {risk}: today {alerts.level_on(risk, today)},"
152
+ f" tomorrow {alerts.level_on(risk, tomorrow)}")
153
+ print(f" danger now: {alerts.current_danger}, phase: {alerts.phase}")
154
+
155
+ # The earthquakes of the last 30 days, within 100 km
156
+ for quake in await client.get_earthquakes():
157
+ if quake.distance_km(*PRAY) <= 100:
158
+ print(f"M{quake.magnitude} {quake.district}, {quake.time:%Y-%m-%d}:"
159
+ f" {quake.distance_km(*PRAY):.0f} km")
160
+
161
+ # The heat waves, in the capital of the province (Biella)
162
+ city = HeatCity.capital_of(alerts.municipality_code) or HeatCity.nearest(*PRAY)
163
+ forecast = await client.get_heat_forecast(city)
164
+ heat = forecast.on(today)
165
+ print(f"Heat in {city}: {heat.level if heat else 'no bulletin today'}")
166
+
167
+ # The avalanches, in the micro-region of a position (Macugnaga)
168
+ region = await client.get_micro_region(45.9686, 7.9672)
169
+ print(f"{region}, {MICRO_REGION_NAMES[region]}")
170
+ try:
171
+ bulletin = await client.get_avalanche_bulletin(today)
172
+ except ArpaPiemonteNotFoundError:
173
+ print(" no avalanche bulletin: out of season")
174
+ else:
175
+ print(f" avalanche danger: {bulletin.of_region(region).danger}")
176
+
177
+
178
+ asyncio.run(main())
179
+ ```
180
+
181
+ ```text
182
+ Pray (Piem-B), bulletin 334/2026
183
+ idrogeologico: today green, tomorrow unknown
184
+ idraulico: today green, tomorrow unknown
185
+ temporali: today green, tomorrow unknown
186
+ neve: today green, tomorrow unknown
187
+ valanghe: today not_evaluated, tomorrow unknown
188
+ danger now: green, phase: none
189
+ M1.1 Alpi Pennine, 2026-11-17: 60 km
190
+ M1.3 Alpi Pennine, 2026-11-11: 97 km
191
+ M1.4 Alpi Pennine, 2026-11-07: 94 km
192
+ Heat in biella: no bulletin today
193
+ IT-21-VB-01, Alpi Pennine di Confine
194
+ no avalanche bulletin: out of season
195
+ ```
196
+
197
+ The alert bulletin is issued around 13:00, for that day and the next: in the
198
+ morning, its first day is yesterday. `level_on(risk, date)` gives the level of
199
+ a date, and UNKNOWN when the bulletin does not cover it yet (tomorrow, above,
200
+ at 07:20); `level(risk, AlertDay.ISSUE_DAY)` gives a day of the bulletin as
201
+ published.
202
+
121
203
  ## Reference
122
204
 
123
205
  ### Client
@@ -135,6 +217,11 @@ keeps no cookies (the website sets one on every answer).
135
217
  | `get_realtime_stations()` | api_realtime, `pie_anag` | `RealtimeStation`, with `sensor_id` |
136
218
  | `get_realtime_data(station_code)` | api_realtime, `data_pie` | `RealtimeData`: records of the last 3 days |
137
219
  | `get_realtime_status()` | api_realtime, `status` | `"healthy"` |
220
+ | `get_municipality_alerts(municipality_code)` | website, `widget/comuni/<code>/index.json` | `MunicipalityAlerts`: each risk today and tomorrow, the danger now, the operational phase |
221
+ | `get_earthquakes()` | website, `data/sismica/sismica_tabella.json` | `Earthquake` of the last 30 days, newest first |
222
+ | `get_heat_forecast(city)` | website, `widget/caldo/<city>/index.json` | `HeatForecast`: 3 days, from 15 May to about 30 September |
223
+ | `get_avalanche_bulletin(day)` | EAWS, `static.avalanche.report` | `AvalancheBulletin`: danger and problems by micro-region, from December to May |
224
+ | `get_micro_region(latitude, longitude)` | shipped with the package | the micro-region of a position, or `None` |
138
225
 
139
226
  `user_agent` names your application in the requests. The default is
140
227
  `aioarpapiemonte/<version> (+<repository>)`; it is sent with each request, so
@@ -167,6 +254,40 @@ code (`valid_type`), as the station pages color it: `OK` (green),
167
254
  returns the newest reading that is not invalid nor missing: a fast rise of a
168
255
  river can be suspect while true.
169
256
 
257
+ ### Natural risks
258
+
259
+ - **Alerts** (`MunicipalityAlerts`): the level of each `RiskType`
260
+ (`HYDROGEOLOGICAL`, `HYDRAULIC`, `THUNDERSTORMS`, `SNOW`, `AVALANCHES`) on
261
+ each `AlertDay` of the bulletin, or on a date (`level_on`, `highest_on`);
262
+ `alert`, the highest of the municipality (the bell of the widget);
263
+ `current_danger`, assessed from the rain and the rivers measured; `phase`,
264
+ the operational phase the municipality declared (`OperationalPhase`: `NONE`,
265
+ `ATTENTION`, `PRE_ALARM`, `ALARM`); the `bulletin` number, its `issued` and
266
+ `next_update` times, and the alert `zones` ("Piem-B"; a few municipalities
267
+ are in two). An `AlertLevel` is `UNKNOWN`, `NOT_EVALUATED` (white: the
268
+ avalanches out of season), `GREEN`, `YELLOW`, `ORANGE` or `RED`: they
269
+ compare, and `is_alert` from yellow. The widget uses the current ISTAT code
270
+ of the municipality, as the api_realtime gives it.
271
+ - **Earthquakes** (`Earthquake`): time in UTC, epicentre, depth, magnitude
272
+ (local magnitude, ML), whether a seismologist `reviewed` it, and
273
+ `distance_km(latitude, longitude)`. The list covers about 6 to 10° E and
274
+ 43.5 to 47° N.
275
+ - **Heat waves** (`HeatForecast`): the 8 provincial capitals (`HeatCity`,
276
+ with `capital_of(municipality_code)` and `nearest(latitude, longitude)`),
277
+ 3 days each, with the `HeatLevel` of bioclimatic discomfort (`GREEN` to
278
+ `RED`, the levels 0 to 3 of Arpa: the 75th, 90th and 95th percentiles of
279
+ the apparent temperature), temperatures and consecutive hot days. Out of
280
+ season the file keeps the last bulletin: `on(today)` is `None`.
281
+ - **Avalanches** (`AvalancheBulletin`): the bulletin of each micro-region
282
+ (`of_region(region_id)`, a `RegionBulletin`), with its `danger` (the
283
+ highest of its `ratings`, an `AvalancheDanger` from `LOW` to `VERY_HIGH`,
284
+ `scale` 1 to 5), its ratings by elevation and time of day, its avalanche
285
+ `problems` and its `tendency`. Out of season, `get_avalanche_bulletin`
286
+ raises `ArpaPiemonteNotFoundError`. The 14 micro-regions of Piedmont cover
287
+ its mountains, not its plains and hills: Torino and Pray are in none.
288
+ `micro_region_at(latitude, longitude)` is the blocking form of
289
+ `get_micro_region`, and `MICRO_REGION_NAMES` names them.
290
+
170
291
  ### Errors
171
292
 
172
293
  All errors derive from `ArpaPiemonteError`:
@@ -174,7 +295,7 @@ All errors derive from `ArpaPiemonteError`:
174
295
  - `ArpaPiemonteConnectionError`: network error, error status, timeout;
175
296
  - `ArpaPiemonteParseError`: an answer that is not the expected format;
176
297
  - `ArpaPiemonteNotFoundError`: the file does not exist, for example a quantity
177
- the station does not publish.
298
+ the station does not publish, or an avalanche bulletin out of season.
178
299
 
179
300
  Invalid identifiers raise `ValueError` before any request.
180
301
 
@@ -186,11 +307,21 @@ license ([legal notes](https://www.arpa.piemonte.it/note-legali)). Credit it as
186
307
  `ATTRIBUTION` does, "Fonte: Arpa Piemonte - www.arpa.piemonte.it", and link the
187
308
  page of the station when you can (`ParamSeries.page_url`).
188
309
 
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.
310
+ The widgets of the alerts and of the heat waves ask to cite the source and to
311
+ keep the layout of the widgets of Arpa; the widget of a municipality, unless
312
+ only its bell, the highest alert, is used (`nota_implementazione_widget`).
313
+
314
+ The avalanche bulletins are by **AINEVA** ("AINEVA Piemonte"), published in
315
+ the format of EAWS at [avalanche.report](https://avalanche.report); their
316
+ licence is not stated. Credit them as `AVALANCHE_ATTRIBUTION` does. The
317
+ micro-regions and their names, shipped with the package, are by
318
+ [EAWS](https://gitlab.com/eaws/eaws-regions), under CC0.
319
+
320
+ aioarpapiemonte is **not affiliated with or endorsed by Arpa Piemonte, AINEVA
321
+ or EAWS**. The real-time data is validated automatically only, and may be
322
+ corrected later by Arpa Piemonte; it comes without any guarantee of
323
+ availability. Do not rely on it for safety: for alerts, follow the official
324
+ bulletins and the civil protection.
194
325
 
195
326
  ## Development
196
327
 
@@ -0,0 +1,312 @@
1
+ # aioarpapiemonte
2
+
3
+ Async Python client for the real-time data of the stations of
4
+ [Arpa Piemonte](https://www.arpa.piemonte.it): river levels, rain,
5
+ temperature, humidity, wind and snow of the 374 stations of the Piedmont
6
+ network, from its two official sources:
7
+
8
+ - the **files of the Arpa website**, read by its station pages: hourly
9
+ readings with their automatic validation, about 40 minutes after the hour,
10
+ for the last 6 days, with the thresholds of the hydrometers;
11
+ - the **[api_realtime](https://utility.arpa.piemonte.it/api_realtime/docs)**:
12
+ every quantity of a station in one request, about 3 hours and 40 minutes
13
+ after the hour, for the last 3 days.
14
+
15
+ It also reads the natural risks: the alerts of each municipality, the
16
+ earthquakes and the heat waves of the Arpa website, and the avalanche
17
+ bulletins of Piedmont, published by AINEVA through EAWS.
18
+
19
+ asyncio and aiohttp, fully typed (mypy strict). The files are asked whether
20
+ they changed (`If-None-Match`, `If-Modified-Since`): an unchanged file is
21
+ neither downloaded nor parsed again.
22
+
23
+ For the readings every 30 minutes of the Meteo 3R app of Arpa Piemonte, see
24
+ [aiometeo3r](https://github.com/webysther/aio-meteo3r).
25
+
26
+ ## Installation
27
+
28
+ ```bash
29
+ pip install aioarpapiemonte
30
+ ```
31
+
32
+ Python 3.13 or newer.
33
+
34
+ ## Usage
35
+
36
+ ```python
37
+ import asyncio
38
+
39
+ from aioarpapiemonte import ArpaPiemonteClient, Param, RealtimeField
40
+
41
+
42
+ async def main() -> None:
43
+ async with ArpaPiemonteClient() as client:
44
+ # The website: hourly readings with their validation
45
+ series = await client.get_series(Param.LEVEL, "002105900") # Pray Sessera
46
+ latest = series.latest()
47
+ if latest is not None:
48
+ status = series.thresholds.status(latest.value) if series.thresholds else None
49
+ print(f"{series.name}: {latest.value} m at {latest.time:%H:%M} UTC,"
50
+ f" {latest.validation}, {status}")
51
+
52
+ # The api_realtime: every quantity in one request, a few hours later
53
+ data = await client.get_realtime_data("188")
54
+ rain = data.latest(RealtimeField.CUM_RAIN_24H)
55
+ if rain is not None:
56
+ print(f"Rain in 24 h: {rain.value} mm at {rain.time:%H:%M} UTC")
57
+
58
+
59
+ asyncio.run(main())
60
+ ```
61
+
62
+ ```text
63
+ PRAY SESSERA: 0.86 m at 02:00 UTC, to_verify, normal
64
+ Rain in 24 h: 0.0 mm at 23:00 UTC
65
+ ```
66
+
67
+ ### Two identifiers
68
+
69
+ A station has a code in the network (`"188"`, the api_realtime and Meteo 3R)
70
+ and an identifier on the website (`"002105900"`). The website one is the ISTAT
71
+ code of the municipality when the station was set up, which can be an old
72
+ code, and the number of the station in it: it cannot be made from the current
73
+ ISTAT code. `get_realtime_stations()` gives both:
74
+
75
+ ```python
76
+ import asyncio
77
+
78
+ from aioarpapiemonte import ArpaPiemonteClient
79
+
80
+
81
+ async def main() -> None:
82
+ async with ArpaPiemonteClient() as client:
83
+ stations = await client.get_realtime_stations()
84
+ pray = next(s for s in stations if s.station_code == "188")
85
+ print(f"{pray.name}: station {pray.station_code}, website {pray.sensor_id},"
86
+ f" municipality {pray.municipality_code}")
87
+
88
+
89
+ asyncio.run(main())
90
+ ```
91
+
92
+ ```text
93
+ PRAY SESSERA: station 188, website 002105900, municipality 096050
94
+ ```
95
+
96
+ ### Natural risks
97
+
98
+ ```python
99
+ import asyncio
100
+ import datetime as dt
101
+ from zoneinfo import ZoneInfo
102
+
103
+ from aioarpapiemonte import (
104
+ MICRO_REGION_NAMES,
105
+ ArpaPiemonteClient,
106
+ ArpaPiemonteNotFoundError,
107
+ HeatCity,
108
+ RiskType,
109
+ )
110
+
111
+ PRAY = (45.6739, 8.22167)
112
+
113
+
114
+ async def main() -> None:
115
+ today = dt.datetime.now(ZoneInfo("Europe/Rome")).date()
116
+ tomorrow = today + dt.timedelta(days=1)
117
+ async with ArpaPiemonteClient() as client:
118
+ # The alerts of a municipality, by its current ISTAT code
119
+ alerts = await client.get_municipality_alerts("096050")
120
+ print(f"{alerts.name} ({', '.join(alerts.zones)}), bulletin {alerts.bulletin}")
121
+ for risk in RiskType:
122
+ print(f" {risk}: today {alerts.level_on(risk, today)},"
123
+ f" tomorrow {alerts.level_on(risk, tomorrow)}")
124
+ print(f" danger now: {alerts.current_danger}, phase: {alerts.phase}")
125
+
126
+ # The earthquakes of the last 30 days, within 100 km
127
+ for quake in await client.get_earthquakes():
128
+ if quake.distance_km(*PRAY) <= 100:
129
+ print(f"M{quake.magnitude} {quake.district}, {quake.time:%Y-%m-%d}:"
130
+ f" {quake.distance_km(*PRAY):.0f} km")
131
+
132
+ # The heat waves, in the capital of the province (Biella)
133
+ city = HeatCity.capital_of(alerts.municipality_code) or HeatCity.nearest(*PRAY)
134
+ forecast = await client.get_heat_forecast(city)
135
+ heat = forecast.on(today)
136
+ print(f"Heat in {city}: {heat.level if heat else 'no bulletin today'}")
137
+
138
+ # The avalanches, in the micro-region of a position (Macugnaga)
139
+ region = await client.get_micro_region(45.9686, 7.9672)
140
+ print(f"{region}, {MICRO_REGION_NAMES[region]}")
141
+ try:
142
+ bulletin = await client.get_avalanche_bulletin(today)
143
+ except ArpaPiemonteNotFoundError:
144
+ print(" no avalanche bulletin: out of season")
145
+ else:
146
+ print(f" avalanche danger: {bulletin.of_region(region).danger}")
147
+
148
+
149
+ asyncio.run(main())
150
+ ```
151
+
152
+ ```text
153
+ Pray (Piem-B), bulletin 334/2026
154
+ idrogeologico: today green, tomorrow unknown
155
+ idraulico: today green, tomorrow unknown
156
+ temporali: today green, tomorrow unknown
157
+ neve: today green, tomorrow unknown
158
+ valanghe: today not_evaluated, tomorrow unknown
159
+ danger now: green, phase: none
160
+ M1.1 Alpi Pennine, 2026-11-17: 60 km
161
+ M1.3 Alpi Pennine, 2026-11-11: 97 km
162
+ M1.4 Alpi Pennine, 2026-11-07: 94 km
163
+ Heat in biella: no bulletin today
164
+ IT-21-VB-01, Alpi Pennine di Confine
165
+ no avalanche bulletin: out of season
166
+ ```
167
+
168
+ The alert bulletin is issued around 13:00, for that day and the next: in the
169
+ morning, its first day is yesterday. `level_on(risk, date)` gives the level of
170
+ a date, and UNKNOWN when the bulletin does not cover it yet (tomorrow, above,
171
+ at 07:20); `level(risk, AlertDay.ISSUE_DAY)` gives a day of the bulletin as
172
+ published.
173
+
174
+ ## Reference
175
+
176
+ ### Client
177
+
178
+ `ArpaPiemonteClient(session=None, *, request_timeout=15.0, user_agent=None)`
179
+
180
+ Pass the `aiohttp.ClientSession` of your application: the client never closes
181
+ it. Without one, use the client as an async context manager; its own session
182
+ keeps no cookies (the website sets one on every answer).
183
+
184
+ | Method | Source | Returns |
185
+ | --- | --- | --- |
186
+ | `get_sensors()` | website, `sensors.geojson` (617 KB) | `Sensor` of each station, with the quantities it publishes |
187
+ | `get_series(param, station)` | website, `<param>/<station>.geojson` | `ParamSeries`: hourly readings, validation, thresholds |
188
+ | `get_realtime_stations()` | api_realtime, `pie_anag` | `RealtimeStation`, with `sensor_id` |
189
+ | `get_realtime_data(station_code)` | api_realtime, `data_pie` | `RealtimeData`: records of the last 3 days |
190
+ | `get_realtime_status()` | api_realtime, `status` | `"healthy"` |
191
+ | `get_municipality_alerts(municipality_code)` | website, `widget/comuni/<code>/index.json` | `MunicipalityAlerts`: each risk today and tomorrow, the danger now, the operational phase |
192
+ | `get_earthquakes()` | website, `data/sismica/sismica_tabella.json` | `Earthquake` of the last 30 days, newest first |
193
+ | `get_heat_forecast(city)` | website, `widget/caldo/<city>/index.json` | `HeatForecast`: 3 days, from 15 May to about 30 September |
194
+ | `get_avalanche_bulletin(day)` | EAWS, `static.avalanche.report` | `AvalancheBulletin`: danger and problems by micro-region, from December to May |
195
+ | `get_micro_region(latitude, longitude)` | shipped with the package | the micro-region of a position, or `None` |
196
+
197
+ `user_agent` names your application in the requests. The default is
198
+ `aioarpapiemonte/<version> (+<repository>)`; it is sent with each request, so
199
+ it replaces the one of a shared session.
200
+
201
+ ### Quantities
202
+
203
+ | `Param` (website) | Unit | `RealtimeField` (api_realtime) | Unit |
204
+ | --- | --- | --- | --- |
205
+ | `LEVEL` (`idro`) | m | `HYDROMETRIC_LEVEL` | m |
206
+ | `TEMPERATURE` (`terma`) | °C | `AIR_TEMPERATURE` | °C |
207
+ | `HUMIDITY` (`igro`) | % | `HUMIDITY` | % |
208
+ | `RAIN_10_MIN` (`pluv`) | mm, see below | `CUM_RAIN_1H` ... `CUM_RAIN_24H` | mm |
209
+ | `WIND_SPEED` (`velv`), `WIND_SPEED_SECONDARY` (`vels`), `GUST_SPEED` (`velr`) | m/s | `WIND`, `GUST_OF_WIND` | km/h |
210
+ | `WIND_DIRECTION` (`dirv`) | ° | `WIND_DIRECTION`, `GUST_DIRECTION` | ° |
211
+ | `SNOW_DEPTH` (`nivo`) | cm | `SNOW_HEIGHT` | cm |
212
+ | `PRESSURE` (`baro`) | hPa | | |
213
+ | `RADIATION` (`radd`) | W/m² | | |
214
+
215
+ The rain of the website files is described by them as "Livello pioggia sui 10
216
+ minuti", and was lower than the rain of the hour of the api_realtime in 5 of
217
+ 73 hours: it is not the rain of the hour. For it, read `CUM_RAIN_1H`.
218
+
219
+ ### Validation
220
+
221
+ Each reading of the website has a `Validation`, from the first letter of its
222
+ code (`valid_type`), as the station pages color it: `OK` (green),
223
+ `TO_VERIFY` (V..., yellow: often the latest hours), `SUSPECT` (W..., orange),
224
+ `INVALID` (A..., red), `MISSING` (M... or none, grey). `ParamSeries.latest()`
225
+ returns the newest reading that is not invalid nor missing: a fast rise of a
226
+ river can be suspect while true.
227
+
228
+ ### Natural risks
229
+
230
+ - **Alerts** (`MunicipalityAlerts`): the level of each `RiskType`
231
+ (`HYDROGEOLOGICAL`, `HYDRAULIC`, `THUNDERSTORMS`, `SNOW`, `AVALANCHES`) on
232
+ each `AlertDay` of the bulletin, or on a date (`level_on`, `highest_on`);
233
+ `alert`, the highest of the municipality (the bell of the widget);
234
+ `current_danger`, assessed from the rain and the rivers measured; `phase`,
235
+ the operational phase the municipality declared (`OperationalPhase`: `NONE`,
236
+ `ATTENTION`, `PRE_ALARM`, `ALARM`); the `bulletin` number, its `issued` and
237
+ `next_update` times, and the alert `zones` ("Piem-B"; a few municipalities
238
+ are in two). An `AlertLevel` is `UNKNOWN`, `NOT_EVALUATED` (white: the
239
+ avalanches out of season), `GREEN`, `YELLOW`, `ORANGE` or `RED`: they
240
+ compare, and `is_alert` from yellow. The widget uses the current ISTAT code
241
+ of the municipality, as the api_realtime gives it.
242
+ - **Earthquakes** (`Earthquake`): time in UTC, epicentre, depth, magnitude
243
+ (local magnitude, ML), whether a seismologist `reviewed` it, and
244
+ `distance_km(latitude, longitude)`. The list covers about 6 to 10° E and
245
+ 43.5 to 47° N.
246
+ - **Heat waves** (`HeatForecast`): the 8 provincial capitals (`HeatCity`,
247
+ with `capital_of(municipality_code)` and `nearest(latitude, longitude)`),
248
+ 3 days each, with the `HeatLevel` of bioclimatic discomfort (`GREEN` to
249
+ `RED`, the levels 0 to 3 of Arpa: the 75th, 90th and 95th percentiles of
250
+ the apparent temperature), temperatures and consecutive hot days. Out of
251
+ season the file keeps the last bulletin: `on(today)` is `None`.
252
+ - **Avalanches** (`AvalancheBulletin`): the bulletin of each micro-region
253
+ (`of_region(region_id)`, a `RegionBulletin`), with its `danger` (the
254
+ highest of its `ratings`, an `AvalancheDanger` from `LOW` to `VERY_HIGH`,
255
+ `scale` 1 to 5), its ratings by elevation and time of day, its avalanche
256
+ `problems` and its `tendency`. Out of season, `get_avalanche_bulletin`
257
+ raises `ArpaPiemonteNotFoundError`. The 14 micro-regions of Piedmont cover
258
+ its mountains, not its plains and hills: Torino and Pray are in none.
259
+ `micro_region_at(latitude, longitude)` is the blocking form of
260
+ `get_micro_region`, and `MICRO_REGION_NAMES` names them.
261
+
262
+ ### Errors
263
+
264
+ All errors derive from `ArpaPiemonteError`:
265
+
266
+ - `ArpaPiemonteConnectionError`: network error, error status, timeout;
267
+ - `ArpaPiemonteParseError`: an answer that is not the expected format;
268
+ - `ArpaPiemonteNotFoundError`: the file does not exist, for example a quantity
269
+ the station does not publish, or an avalanche bulletin out of season.
270
+
271
+ Invalid identifiers raise `ValueError` before any request.
272
+
273
+ ## Data source and attribution
274
+
275
+ The data is by **Arpa Piemonte**, under the
276
+ [Creative Commons Attribution 4.0](https://creativecommons.org/licenses/by/4.0/)
277
+ license ([legal notes](https://www.arpa.piemonte.it/note-legali)). Credit it as
278
+ `ATTRIBUTION` does, "Fonte: Arpa Piemonte - www.arpa.piemonte.it", and link the
279
+ page of the station when you can (`ParamSeries.page_url`).
280
+
281
+ The widgets of the alerts and of the heat waves ask to cite the source and to
282
+ keep the layout of the widgets of Arpa; the widget of a municipality, unless
283
+ only its bell, the highest alert, is used (`nota_implementazione_widget`).
284
+
285
+ The avalanche bulletins are by **AINEVA** ("AINEVA Piemonte"), published in
286
+ the format of EAWS at [avalanche.report](https://avalanche.report); their
287
+ licence is not stated. Credit them as `AVALANCHE_ATTRIBUTION` does. The
288
+ micro-regions and their names, shipped with the package, are by
289
+ [EAWS](https://gitlab.com/eaws/eaws-regions), under CC0.
290
+
291
+ aioarpapiemonte is **not affiliated with or endorsed by Arpa Piemonte, AINEVA
292
+ or EAWS**. The real-time data is validated automatically only, and may be
293
+ corrected later by Arpa Piemonte; it comes without any guarantee of
294
+ availability. Do not rely on it for safety: for alerts, follow the official
295
+ bulletins and the civil protection.
296
+
297
+ ## Development
298
+
299
+ ```bash
300
+ python -m venv .venv && . .venv/bin/activate
301
+ pip install --editable . --group dev # pip >= 25.1
302
+ ruff format --check . && ruff check .
303
+ mypy
304
+ pytest --cov
305
+ ```
306
+
307
+ The tests never reach Arpa Piemonte: a local HTTPS server answers for its hosts
308
+ (`tests/server.py`), with real files in `tests/fixtures/real`.
309
+
310
+ ## License
311
+
312
+ MIT, see [LICENSE](https://github.com/webysther/aio-arpa-piemonte/blob/main/LICENSE).
@@ -5,16 +5,20 @@ build-backend = "hatchling.build"
5
5
  [project]
6
6
  name = "aioarpapiemonte"
7
7
  dynamic = ["version"]
8
- description = "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"
8
+ description = "Async client for the data of Arpa Piemonte: river levels, rain, temperature and snow of its stations, alerts, earthquakes, heat waves and avalanche bulletins"
9
9
  readme = "README.md"
10
10
  license = "MIT"
11
11
  license-files = ["LICENSE"]
12
12
  authors = [{ name = "Webysther Sperandio" }]
13
13
  requires-python = ">=3.13"
14
14
  keywords = [
15
+ "allerta",
15
16
  "api_realtime",
16
17
  "arpa piemonte",
17
18
  "asyncio",
19
+ "avalanche",
20
+ "earthquake",
21
+ "heat wave",
18
22
  "hydrometer",
19
23
  "idrometro",
20
24
  "italy",
@@ -0,0 +1,123 @@
1
+ """Async client for the data of Arpa Piemonte: its stations and natural risks.
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. Its website also publishes the
7
+ alerts of each municipality, the earthquakes and the heat waves; AINEVA
8
+ publishes the avalanche bulletins of Piedmont through EAWS.
9
+
10
+ The data is by Arpa Piemonte, under CC BY 4.0: credit it with
11
+ :data:`ATTRIBUTION`, and the avalanche bulletins with
12
+ :data:`AVALANCHE_ATTRIBUTION`. aioarpapiemonte is not affiliated with Arpa
13
+ Piemonte, AINEVA or EAWS.
14
+ """
15
+
16
+ from .client import ArpaPiemonteClient
17
+ from .const import (
18
+ ATTRIBUTION,
19
+ AVALANCHE_ATTRIBUTION,
20
+ DEFAULT_REQUEST_TIMEOUT,
21
+ MAX_PAGES,
22
+ PIEMONTE_EAWS_REGION,
23
+ PIEMONTE_NETWORK,
24
+ )
25
+ from .exceptions import (
26
+ ArpaPiemonteConnectionError,
27
+ ArpaPiemonteError,
28
+ ArpaPiemonteNotFoundError,
29
+ ArpaPiemonteParseError,
30
+ )
31
+ from .geo import (
32
+ MICRO_REGION_NAMES,
33
+ MicroRegion,
34
+ distance_km,
35
+ micro_region_at,
36
+ micro_regions,
37
+ )
38
+ from .models import (
39
+ USABLE,
40
+ AlertDay,
41
+ AlertLevel,
42
+ AvalancheBulletin,
43
+ AvalancheDanger,
44
+ AvalancheProblem,
45
+ DangerRating,
46
+ Earthquake,
47
+ HeatCity,
48
+ HeatDay,
49
+ HeatForecast,
50
+ HeatLevel,
51
+ LevelStatus,
52
+ MunicipalityAlerts,
53
+ OperationalPhase,
54
+ Param,
55
+ ParamReading,
56
+ ParamSeries,
57
+ Reading,
58
+ RealtimeData,
59
+ RealtimeField,
60
+ RealtimeRecord,
61
+ RealtimeStation,
62
+ RegionBulletin,
63
+ RiskLevel,
64
+ RiskType,
65
+ Sensor,
66
+ Thresholds,
67
+ Validation,
68
+ station_page_url,
69
+ )
70
+ from .urls import sensor_id
71
+
72
+ __all__ = [
73
+ "ATTRIBUTION",
74
+ "AVALANCHE_ATTRIBUTION",
75
+ "DEFAULT_REQUEST_TIMEOUT",
76
+ "MAX_PAGES",
77
+ "MICRO_REGION_NAMES",
78
+ "PIEMONTE_EAWS_REGION",
79
+ "PIEMONTE_NETWORK",
80
+ "USABLE",
81
+ "AlertDay",
82
+ "AlertLevel",
83
+ "ArpaPiemonteClient",
84
+ "ArpaPiemonteConnectionError",
85
+ "ArpaPiemonteError",
86
+ "ArpaPiemonteNotFoundError",
87
+ "ArpaPiemonteParseError",
88
+ "AvalancheBulletin",
89
+ "AvalancheDanger",
90
+ "AvalancheProblem",
91
+ "DangerRating",
92
+ "Earthquake",
93
+ "HeatCity",
94
+ "HeatDay",
95
+ "HeatForecast",
96
+ "HeatLevel",
97
+ "LevelStatus",
98
+ "MicroRegion",
99
+ "MunicipalityAlerts",
100
+ "OperationalPhase",
101
+ "Param",
102
+ "ParamReading",
103
+ "ParamSeries",
104
+ "Reading",
105
+ "RealtimeData",
106
+ "RealtimeField",
107
+ "RealtimeRecord",
108
+ "RealtimeStation",
109
+ "RegionBulletin",
110
+ "RiskLevel",
111
+ "RiskType",
112
+ "Sensor",
113
+ "Thresholds",
114
+ "Validation",
115
+ "__version__",
116
+ "distance_km",
117
+ "micro_region_at",
118
+ "micro_regions",
119
+ "sensor_id",
120
+ "station_page_url",
121
+ ]
122
+
123
+ __version__ = "0.2.0"