aioarpapiemonte 0.1.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.0/.gitignore +33 -0
- aioarpapiemonte-0.1.0/LICENSE +21 -0
- aioarpapiemonte-0.1.0/PKG-INFO +210 -0
- aioarpapiemonte-0.1.0/README.md +181 -0
- aioarpapiemonte-0.1.0/pyproject.toml +116 -0
- aioarpapiemonte-0.1.0/src/aioarpapiemonte/__init__.py +66 -0
- aioarpapiemonte-0.1.0/src/aioarpapiemonte/_http.py +52 -0
- aioarpapiemonte-0.1.0/src/aioarpapiemonte/client.py +255 -0
- aioarpapiemonte-0.1.0/src/aioarpapiemonte/const.py +52 -0
- aioarpapiemonte-0.1.0/src/aioarpapiemonte/exceptions.py +24 -0
- aioarpapiemonte-0.1.0/src/aioarpapiemonte/models.py +481 -0
- aioarpapiemonte-0.1.0/src/aioarpapiemonte/parsers.py +344 -0
- aioarpapiemonte-0.1.0/src/aioarpapiemonte/py.typed +0 -0
- aioarpapiemonte-0.1.0/src/aioarpapiemonte/urls.py +82 -0
- aioarpapiemonte-0.1.0/tests/__init__.py +32 -0
- aioarpapiemonte-0.1.0/tests/conftest.py +45 -0
- aioarpapiemonte-0.1.0/tests/fixtures/real/data_pie_188.json +1 -0
- aioarpapiemonte-0.1.0/tests/fixtures/real/data_pie_999.json +1 -0
- aioarpapiemonte-0.1.0/tests/fixtures/real/idro_002105900.geojson +780 -0
- aioarpapiemonte-0.1.0/tests/fixtures/real/igro_001022905.geojson +780 -0
- aioarpapiemonte-0.1.0/tests/fixtures/real/nivo_001019900.geojson +780 -0
- aioarpapiemonte-0.1.0/tests/fixtures/real/pie_anag.json +1 -0
- aioarpapiemonte-0.1.0/tests/fixtures/real/pluv_001013900.geojson +780 -0
- aioarpapiemonte-0.1.0/tests/fixtures/real/sensors.geojson +21869 -0
- aioarpapiemonte-0.1.0/tests/fixtures/real/status.json +1 -0
- aioarpapiemonte-0.1.0/tests/fixtures/real/terma_002105900.geojson +780 -0
- aioarpapiemonte-0.1.0/tests/server.py +176 -0
- aioarpapiemonte-0.1.0/tests/test_client.py +294 -0
- aioarpapiemonte-0.1.0/tests/test_models.py +134 -0
- aioarpapiemonte-0.1.0/tests/test_parsers.py +322 -0
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Virtual environments
|
|
2
|
+
.venv/
|
|
3
|
+
venv/
|
|
4
|
+
env/
|
|
5
|
+
|
|
6
|
+
# Python
|
|
7
|
+
__pycache__/
|
|
8
|
+
*.py[cod]
|
|
9
|
+
*.egg-info/
|
|
10
|
+
|
|
11
|
+
# Tool caches
|
|
12
|
+
.mypy_cache/
|
|
13
|
+
.pytest_cache/
|
|
14
|
+
.ruff_cache/
|
|
15
|
+
|
|
16
|
+
# Coverage
|
|
17
|
+
.coverage
|
|
18
|
+
.coverage.*
|
|
19
|
+
coverage.xml
|
|
20
|
+
htmlcov/
|
|
21
|
+
|
|
22
|
+
# Build artifacts
|
|
23
|
+
build/
|
|
24
|
+
dist/
|
|
25
|
+
|
|
26
|
+
# Local settings of editors and assistants
|
|
27
|
+
.idea/
|
|
28
|
+
.vscode/
|
|
29
|
+
.claude/settings.local.json
|
|
30
|
+
|
|
31
|
+
# Operating systems
|
|
32
|
+
.DS_Store
|
|
33
|
+
Thumbs.db
|
|
@@ -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.
|
|
@@ -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,181 @@
|
|
|
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
|
+
asyncio and aiohttp, fully typed (mypy strict). The files of the website are
|
|
16
|
+
asked whether they changed (`If-None-Match`, `If-Modified-Since`): an
|
|
17
|
+
unchanged file is neither downloaded nor parsed again.
|
|
18
|
+
|
|
19
|
+
For the readings every 30 minutes of the Meteo 3R app of Arpa Piemonte, see
|
|
20
|
+
[aiometeo3r](https://github.com/webysther/aio-meteo3r).
|
|
21
|
+
|
|
22
|
+
## Installation
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
pip install aioarpapiemonte
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Python 3.13 or newer.
|
|
29
|
+
|
|
30
|
+
## Usage
|
|
31
|
+
|
|
32
|
+
```python
|
|
33
|
+
import asyncio
|
|
34
|
+
|
|
35
|
+
from aioarpapiemonte import ArpaPiemonteClient, Param, RealtimeField
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
async def main() -> None:
|
|
39
|
+
async with ArpaPiemonteClient() as client:
|
|
40
|
+
# The website: hourly readings with their validation
|
|
41
|
+
series = await client.get_series(Param.LEVEL, "002105900") # Pray Sessera
|
|
42
|
+
latest = series.latest()
|
|
43
|
+
if latest is not None:
|
|
44
|
+
status = series.thresholds.status(latest.value) if series.thresholds else None
|
|
45
|
+
print(f"{series.name}: {latest.value} m at {latest.time:%H:%M} UTC,"
|
|
46
|
+
f" {latest.validation}, {status}")
|
|
47
|
+
|
|
48
|
+
# The api_realtime: every quantity in one request, a few hours later
|
|
49
|
+
data = await client.get_realtime_data("188")
|
|
50
|
+
rain = data.latest(RealtimeField.CUM_RAIN_24H)
|
|
51
|
+
if rain is not None:
|
|
52
|
+
print(f"Rain in 24 h: {rain.value} mm at {rain.time:%H:%M} UTC")
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
asyncio.run(main())
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
```text
|
|
59
|
+
PRAY SESSERA: 0.86 m at 02:00 UTC, to_verify, normal
|
|
60
|
+
Rain in 24 h: 0.0 mm at 23:00 UTC
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### Two identifiers
|
|
64
|
+
|
|
65
|
+
A station has a code in the network (`"188"`, the api_realtime and Meteo 3R)
|
|
66
|
+
and an identifier on the website (`"002105900"`). The website one is the ISTAT
|
|
67
|
+
code of the municipality when the station was set up, which can be an old
|
|
68
|
+
code, and the number of the station in it: it cannot be made from the current
|
|
69
|
+
ISTAT code. `get_realtime_stations()` gives both:
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
import asyncio
|
|
73
|
+
|
|
74
|
+
from aioarpapiemonte import ArpaPiemonteClient
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
async def main() -> None:
|
|
78
|
+
async with ArpaPiemonteClient() as client:
|
|
79
|
+
stations = await client.get_realtime_stations()
|
|
80
|
+
pray = next(s for s in stations if s.station_code == "188")
|
|
81
|
+
print(f"{pray.name}: station {pray.station_code}, website {pray.sensor_id},"
|
|
82
|
+
f" municipality {pray.municipality_code}")
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
asyncio.run(main())
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
```text
|
|
89
|
+
PRAY SESSERA: station 188, website 002105900, municipality 096050
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Reference
|
|
93
|
+
|
|
94
|
+
### Client
|
|
95
|
+
|
|
96
|
+
`ArpaPiemonteClient(session=None, *, request_timeout=15.0, user_agent=None)`
|
|
97
|
+
|
|
98
|
+
Pass the `aiohttp.ClientSession` of your application: the client never closes
|
|
99
|
+
it. Without one, use the client as an async context manager; its own session
|
|
100
|
+
keeps no cookies (the website sets one on every answer).
|
|
101
|
+
|
|
102
|
+
| Method | Source | Returns |
|
|
103
|
+
| --- | --- | --- |
|
|
104
|
+
| `get_sensors()` | website, `sensors.geojson` (617 KB) | `Sensor` of each station, with the quantities it publishes |
|
|
105
|
+
| `get_series(param, station)` | website, `<param>/<station>.geojson` | `ParamSeries`: hourly readings, validation, thresholds |
|
|
106
|
+
| `get_realtime_stations()` | api_realtime, `pie_anag` | `RealtimeStation`, with `sensor_id` |
|
|
107
|
+
| `get_realtime_data(station_code)` | api_realtime, `data_pie` | `RealtimeData`: records of the last 3 days |
|
|
108
|
+
| `get_realtime_status()` | api_realtime, `status` | `"healthy"` |
|
|
109
|
+
|
|
110
|
+
`user_agent` names your application in the requests. The default is
|
|
111
|
+
`aioarpapiemonte/<version> (+<repository>)`; it is sent with each request, so
|
|
112
|
+
it replaces the one of a shared session.
|
|
113
|
+
|
|
114
|
+
### Quantities
|
|
115
|
+
|
|
116
|
+
| `Param` (website) | Unit | `RealtimeField` (api_realtime) | Unit |
|
|
117
|
+
| --- | --- | --- | --- |
|
|
118
|
+
| `LEVEL` (`idro`) | m | `HYDROMETRIC_LEVEL` | m |
|
|
119
|
+
| `TEMPERATURE` (`terma`) | °C | `AIR_TEMPERATURE` | °C |
|
|
120
|
+
| `HUMIDITY` (`igro`) | % | `HUMIDITY` | % |
|
|
121
|
+
| `RAIN_10_MIN` (`pluv`) | mm, see below | `CUM_RAIN_1H` ... `CUM_RAIN_24H` | mm |
|
|
122
|
+
| `WIND_SPEED` (`velv`), `WIND_SPEED_SECONDARY` (`vels`), `GUST_SPEED` (`velr`) | m/s | `WIND`, `GUST_OF_WIND` | km/h |
|
|
123
|
+
| `WIND_DIRECTION` (`dirv`) | ° | `WIND_DIRECTION`, `GUST_DIRECTION` | ° |
|
|
124
|
+
| `SNOW_DEPTH` (`nivo`) | cm | `SNOW_HEIGHT` | cm |
|
|
125
|
+
| `PRESSURE` (`baro`) | hPa | | |
|
|
126
|
+
| `RADIATION` (`radd`) | W/m² | | |
|
|
127
|
+
|
|
128
|
+
The rain of the website files is described by them as "Livello pioggia sui 10
|
|
129
|
+
minuti", and was lower than the rain of the hour of the api_realtime in 5 of
|
|
130
|
+
73 hours: it is not the rain of the hour. For it, read `CUM_RAIN_1H`.
|
|
131
|
+
|
|
132
|
+
### Validation
|
|
133
|
+
|
|
134
|
+
Each reading of the website has a `Validation`, from the first letter of its
|
|
135
|
+
code (`valid_type`), as the station pages color it: `OK` (green),
|
|
136
|
+
`TO_VERIFY` (V..., yellow: often the latest hours), `SUSPECT` (W..., orange),
|
|
137
|
+
`INVALID` (A..., red), `MISSING` (M... or none, grey). `ParamSeries.latest()`
|
|
138
|
+
returns the newest reading that is not invalid nor missing: a fast rise of a
|
|
139
|
+
river can be suspect while true.
|
|
140
|
+
|
|
141
|
+
### Errors
|
|
142
|
+
|
|
143
|
+
All errors derive from `ArpaPiemonteError`:
|
|
144
|
+
|
|
145
|
+
- `ArpaPiemonteConnectionError`: network error, error status, timeout;
|
|
146
|
+
- `ArpaPiemonteParseError`: an answer that is not the expected format;
|
|
147
|
+
- `ArpaPiemonteNotFoundError`: the file does not exist, for example a quantity
|
|
148
|
+
the station does not publish.
|
|
149
|
+
|
|
150
|
+
Invalid identifiers raise `ValueError` before any request.
|
|
151
|
+
|
|
152
|
+
## Data source and attribution
|
|
153
|
+
|
|
154
|
+
The data is by **Arpa Piemonte**, under the
|
|
155
|
+
[Creative Commons Attribution 4.0](https://creativecommons.org/licenses/by/4.0/)
|
|
156
|
+
license ([legal notes](https://www.arpa.piemonte.it/note-legali)). Credit it as
|
|
157
|
+
`ATTRIBUTION` does, "Fonte: Arpa Piemonte - www.arpa.piemonte.it", and link the
|
|
158
|
+
page of the station when you can (`ParamSeries.page_url`).
|
|
159
|
+
|
|
160
|
+
aioarpapiemonte is **not affiliated with or endorsed by Arpa Piemonte**. The
|
|
161
|
+
real-time data is validated automatically only, and may be corrected later by
|
|
162
|
+
Arpa Piemonte; it comes without any guarantee of availability. Do not rely on
|
|
163
|
+
it for safety: for alerts, follow the official bulletins and the civil
|
|
164
|
+
protection.
|
|
165
|
+
|
|
166
|
+
## Development
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
python -m venv .venv && . .venv/bin/activate
|
|
170
|
+
pip install --editable . --group dev # pip >= 25.1
|
|
171
|
+
ruff format --check . && ruff check .
|
|
172
|
+
mypy
|
|
173
|
+
pytest --cov
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
The tests never reach Arpa Piemonte: a local HTTPS server answers for its hosts
|
|
177
|
+
(`tests/server.py`), with real files in `tests/fixtures/real`.
|
|
178
|
+
|
|
179
|
+
## License
|
|
180
|
+
|
|
181
|
+
MIT, see [LICENSE](https://github.com/webysther/aio-arpa-piemonte/blob/main/LICENSE).
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "aioarpapiemonte"
|
|
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"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
authors = [{ name = "Webysther Sperandio" }]
|
|
13
|
+
requires-python = ">=3.13"
|
|
14
|
+
keywords = [
|
|
15
|
+
"api_realtime",
|
|
16
|
+
"arpa piemonte",
|
|
17
|
+
"asyncio",
|
|
18
|
+
"hydrometer",
|
|
19
|
+
"idrometro",
|
|
20
|
+
"italy",
|
|
21
|
+
"piemonte",
|
|
22
|
+
"river level",
|
|
23
|
+
"weather",
|
|
24
|
+
]
|
|
25
|
+
classifiers = [
|
|
26
|
+
"Development Status :: 3 - Alpha",
|
|
27
|
+
"Framework :: AsyncIO",
|
|
28
|
+
"Intended Audience :: Developers",
|
|
29
|
+
"Natural Language :: English",
|
|
30
|
+
"Operating System :: OS Independent",
|
|
31
|
+
"Programming Language :: Python :: 3",
|
|
32
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
33
|
+
"Programming Language :: Python :: 3.13",
|
|
34
|
+
"Programming Language :: Python :: 3.14",
|
|
35
|
+
"Topic :: Scientific/Engineering :: Atmospheric Science",
|
|
36
|
+
"Topic :: Scientific/Engineering :: Hydrology",
|
|
37
|
+
"Topic :: Software Development :: Libraries",
|
|
38
|
+
"Typing :: Typed",
|
|
39
|
+
]
|
|
40
|
+
dependencies = [
|
|
41
|
+
"aiohttp>=3.10",
|
|
42
|
+
# zoneinfo needs a time zone database; Windows has none built in.
|
|
43
|
+
"tzdata; sys_platform == 'win32'",
|
|
44
|
+
]
|
|
45
|
+
|
|
46
|
+
[project.urls]
|
|
47
|
+
Homepage = "https://github.com/webysther/aio-arpa-piemonte"
|
|
48
|
+
Changelog = "https://github.com/webysther/aio-arpa-piemonte/blob/main/CHANGELOG.md"
|
|
49
|
+
Issues = "https://github.com/webysther/aio-arpa-piemonte/issues"
|
|
50
|
+
|
|
51
|
+
[dependency-groups]
|
|
52
|
+
dev = [
|
|
53
|
+
"mypy>=1.15",
|
|
54
|
+
"pytest>=8.3",
|
|
55
|
+
"pytest-asyncio>=1.0",
|
|
56
|
+
"pytest-cov>=6.0",
|
|
57
|
+
"ruff==0.14.4",
|
|
58
|
+
# Certificates of the local HTTPS server standing in for Arpa Piemonte in the tests
|
|
59
|
+
"trustme>=1.2",
|
|
60
|
+
]
|
|
61
|
+
|
|
62
|
+
[tool.hatch.version]
|
|
63
|
+
path = "src/aioarpapiemonte/__init__.py"
|
|
64
|
+
|
|
65
|
+
[tool.hatch.build.targets.wheel]
|
|
66
|
+
packages = ["src/aioarpapiemonte"]
|
|
67
|
+
|
|
68
|
+
[tool.hatch.build.targets.sdist]
|
|
69
|
+
include = ["src", "tests", "README.md", "LICENSE"]
|
|
70
|
+
|
|
71
|
+
[tool.ruff]
|
|
72
|
+
target-version = "py313"
|
|
73
|
+
src = ["src", "tests"]
|
|
74
|
+
|
|
75
|
+
[tool.ruff.lint]
|
|
76
|
+
select = ["ALL"]
|
|
77
|
+
ignore = [
|
|
78
|
+
"COM812", # conflicts with the formatter
|
|
79
|
+
"D203", # incompatible with D211
|
|
80
|
+
"D213", # incompatible with D212
|
|
81
|
+
"PLR0913", # keyword-only options on public methods
|
|
82
|
+
]
|
|
83
|
+
|
|
84
|
+
[tool.ruff.lint.flake8-type-checking]
|
|
85
|
+
# Keep the imports of dataclass annotations at runtime (typing.get_type_hints).
|
|
86
|
+
runtime-evaluated-decorators = ["dataclasses.dataclass"]
|
|
87
|
+
|
|
88
|
+
[tool.ruff.lint.per-file-ignores]
|
|
89
|
+
"tests/**" = [
|
|
90
|
+
"PLR2004", # magic values in assertions
|
|
91
|
+
"S101", # assert
|
|
92
|
+
"SLF001", # private access to test internals
|
|
93
|
+
]
|
|
94
|
+
|
|
95
|
+
[tool.mypy]
|
|
96
|
+
python_version = "3.13"
|
|
97
|
+
strict = true
|
|
98
|
+
files = ["src", "tests"]
|
|
99
|
+
mypy_path = "src"
|
|
100
|
+
|
|
101
|
+
[tool.pytest.ini_options]
|
|
102
|
+
asyncio_mode = "auto"
|
|
103
|
+
asyncio_default_fixture_loop_scope = "function"
|
|
104
|
+
testpaths = ["tests"]
|
|
105
|
+
addopts = "--strict-markers --strict-config"
|
|
106
|
+
filterwarnings = ["error"]
|
|
107
|
+
|
|
108
|
+
[tool.coverage.run]
|
|
109
|
+
source = ["aioarpapiemonte"]
|
|
110
|
+
branch = true
|
|
111
|
+
|
|
112
|
+
[tool.coverage.report]
|
|
113
|
+
show_missing = true
|
|
114
|
+
skip_covered = false
|
|
115
|
+
fail_under = 95
|
|
116
|
+
exclude_also = ["if TYPE_CHECKING:", "\\.\\.\\."]
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
"""Async client for the real-time data of the stations of Arpa Piemonte.
|
|
2
|
+
|
|
3
|
+
Arpa Piemonte publishes the readings of its stations (river levels, rain,
|
|
4
|
+
temperature, humidity, wind, snow) in two places: the files read by the
|
|
5
|
+
station pages of its website, hourly with their validation, and the
|
|
6
|
+
documented api_realtime, a few hours later.
|
|
7
|
+
|
|
8
|
+
The data is by Arpa Piemonte, under CC BY 4.0: credit it with
|
|
9
|
+
:data:`ATTRIBUTION`. aioarpapiemonte is not affiliated with Arpa Piemonte.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from .client import ArpaPiemonteClient
|
|
13
|
+
from .const import ATTRIBUTION, DEFAULT_REQUEST_TIMEOUT, MAX_PAGES, PIEMONTE_NETWORK
|
|
14
|
+
from .exceptions import (
|
|
15
|
+
ArpaPiemonteConnectionError,
|
|
16
|
+
ArpaPiemonteError,
|
|
17
|
+
ArpaPiemonteNotFoundError,
|
|
18
|
+
ArpaPiemonteParseError,
|
|
19
|
+
)
|
|
20
|
+
from .models import (
|
|
21
|
+
USABLE,
|
|
22
|
+
LevelStatus,
|
|
23
|
+
Param,
|
|
24
|
+
ParamReading,
|
|
25
|
+
ParamSeries,
|
|
26
|
+
Reading,
|
|
27
|
+
RealtimeData,
|
|
28
|
+
RealtimeField,
|
|
29
|
+
RealtimeRecord,
|
|
30
|
+
RealtimeStation,
|
|
31
|
+
Sensor,
|
|
32
|
+
Thresholds,
|
|
33
|
+
Validation,
|
|
34
|
+
station_page_url,
|
|
35
|
+
)
|
|
36
|
+
from .urls import sensor_id
|
|
37
|
+
|
|
38
|
+
__all__ = [
|
|
39
|
+
"ATTRIBUTION",
|
|
40
|
+
"DEFAULT_REQUEST_TIMEOUT",
|
|
41
|
+
"MAX_PAGES",
|
|
42
|
+
"PIEMONTE_NETWORK",
|
|
43
|
+
"USABLE",
|
|
44
|
+
"ArpaPiemonteClient",
|
|
45
|
+
"ArpaPiemonteConnectionError",
|
|
46
|
+
"ArpaPiemonteError",
|
|
47
|
+
"ArpaPiemonteNotFoundError",
|
|
48
|
+
"ArpaPiemonteParseError",
|
|
49
|
+
"LevelStatus",
|
|
50
|
+
"Param",
|
|
51
|
+
"ParamReading",
|
|
52
|
+
"ParamSeries",
|
|
53
|
+
"Reading",
|
|
54
|
+
"RealtimeData",
|
|
55
|
+
"RealtimeField",
|
|
56
|
+
"RealtimeRecord",
|
|
57
|
+
"RealtimeStation",
|
|
58
|
+
"Sensor",
|
|
59
|
+
"Thresholds",
|
|
60
|
+
"Validation",
|
|
61
|
+
"__version__",
|
|
62
|
+
"sensor_id",
|
|
63
|
+
"station_page_url",
|
|
64
|
+
]
|
|
65
|
+
|
|
66
|
+
__version__ = "0.1.0"
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
"""Conditional requests: what a host answered before, by URL."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from dataclasses import dataclass
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
@dataclass(frozen=True, slots=True)
|
|
9
|
+
class _Entry[T]:
|
|
10
|
+
"""A parsed answer and the validators the host sent with it."""
|
|
11
|
+
|
|
12
|
+
etag: str | None
|
|
13
|
+
last_modified: str | None
|
|
14
|
+
value: T
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class ConditionalCache[T]:
|
|
18
|
+
"""The latest parsed answer of each URL, with its validators.
|
|
19
|
+
|
|
20
|
+
The files of the Arpa website send an ``ETag`` and a ``Last-Modified``,
|
|
21
|
+
and answer 304 when asked with either (measured on 2026-11-17).
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
def __init__(self) -> None:
|
|
25
|
+
"""Initialize an empty cache."""
|
|
26
|
+
self._entries: dict[str, _Entry[T]] = {}
|
|
27
|
+
|
|
28
|
+
def validators(self, url: str) -> dict[str, str]:
|
|
29
|
+
"""Return the headers that ask the host whether the URL changed."""
|
|
30
|
+
entry = self._entries.get(url)
|
|
31
|
+
if entry is None:
|
|
32
|
+
return {}
|
|
33
|
+
headers = {}
|
|
34
|
+
if entry.etag is not None:
|
|
35
|
+
headers["If-None-Match"] = entry.etag
|
|
36
|
+
if entry.last_modified is not None:
|
|
37
|
+
headers["If-Modified-Since"] = entry.last_modified
|
|
38
|
+
return headers
|
|
39
|
+
|
|
40
|
+
def get(self, url: str) -> T | None:
|
|
41
|
+
"""Return the latest parsed answer of a URL; None when there is none."""
|
|
42
|
+
entry = self._entries.get(url)
|
|
43
|
+
return None if entry is None else entry.value
|
|
44
|
+
|
|
45
|
+
def store(
|
|
46
|
+
self, url: str, value: T, *, etag: str | None, last_modified: str | None
|
|
47
|
+
) -> None:
|
|
48
|
+
"""Keep a parsed answer; without validators there is nothing to ask with."""
|
|
49
|
+
if etag is None and last_modified is None:
|
|
50
|
+
self._entries.pop(url, None)
|
|
51
|
+
return
|
|
52
|
+
self._entries[url] = _Entry(etag, last_modified, value)
|