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.
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/PKG-INFO +143 -12
- aioarpapiemonte-0.2.0/README.md +312 -0
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/pyproject.toml +5 -1
- aioarpapiemonte-0.2.0/src/aioarpapiemonte/__init__.py +123 -0
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/src/aioarpapiemonte/_http.py +6 -3
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/src/aioarpapiemonte/client.py +107 -9
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/src/aioarpapiemonte/const.py +30 -0
- aioarpapiemonte-0.2.0/src/aioarpapiemonte/data/IT-21_micro-regions.geojson +1 -0
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/src/aioarpapiemonte/exceptions.py +2 -1
- aioarpapiemonte-0.2.0/src/aioarpapiemonte/geo.py +205 -0
- aioarpapiemonte-0.2.0/src/aioarpapiemonte/models.py +958 -0
- aioarpapiemonte-0.2.0/src/aioarpapiemonte/parsers.py +698 -0
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/src/aioarpapiemonte/urls.py +40 -2
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/__init__.py +10 -1
- aioarpapiemonte-0.2.0/tests/fixtures/real/2026-04-18-IT-21.json +377 -0
- aioarpapiemonte-0.2.0/tests/fixtures/real/caldo_torino.json +55 -0
- aioarpapiemonte-0.2.0/tests/fixtures/real/sismica_tabella.json +394 -0
- aioarpapiemonte-0.2.0/tests/fixtures/real/widget_005005.json +58 -0
- aioarpapiemonte-0.2.0/tests/fixtures/real/widget_096050.json +58 -0
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/server.py +2 -2
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/test_client.py +88 -1
- aioarpapiemonte-0.2.0/tests/test_geo.py +131 -0
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/test_models.py +113 -4
- aioarpapiemonte-0.2.0/tests/test_risks.py +446 -0
- aioarpapiemonte-0.1.1/README.md +0 -181
- aioarpapiemonte-0.1.1/src/aioarpapiemonte/__init__.py +0 -66
- aioarpapiemonte-0.1.1/src/aioarpapiemonte/models.py +0 -481
- aioarpapiemonte-0.1.1/src/aioarpapiemonte/parsers.py +0 -349
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/.gitignore +0 -0
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/LICENSE +0 -0
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/src/aioarpapiemonte/py.typed +0 -0
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/conftest.py +0 -0
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/fixtures/real/data_pie_188.json +0 -0
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/fixtures/real/data_pie_999.json +0 -0
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/fixtures/real/idro_002105900.geojson +0 -0
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/fixtures/real/igro_001022905.geojson +0 -0
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/fixtures/real/nivo_001019900.geojson +0 -0
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/fixtures/real/pie_anag.json +0 -0
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/fixtures/real/pluv_001013900.geojson +0 -0
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/fixtures/real/sensors.geojson +0 -0
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/fixtures/real/status.json +0 -0
- {aioarpapiemonte-0.1.1 → aioarpapiemonte-0.2.0}/tests/fixtures/real/terma_002105900.geojson +0 -0
- {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.
|
|
4
|
-
Summary: Async client for the
|
|
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
|
-
|
|
45
|
-
|
|
46
|
-
|
|
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
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
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
|
|
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"
|