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.
Files changed (30) hide show
  1. aioarpapiemonte-0.1.0/.gitignore +33 -0
  2. aioarpapiemonte-0.1.0/LICENSE +21 -0
  3. aioarpapiemonte-0.1.0/PKG-INFO +210 -0
  4. aioarpapiemonte-0.1.0/README.md +181 -0
  5. aioarpapiemonte-0.1.0/pyproject.toml +116 -0
  6. aioarpapiemonte-0.1.0/src/aioarpapiemonte/__init__.py +66 -0
  7. aioarpapiemonte-0.1.0/src/aioarpapiemonte/_http.py +52 -0
  8. aioarpapiemonte-0.1.0/src/aioarpapiemonte/client.py +255 -0
  9. aioarpapiemonte-0.1.0/src/aioarpapiemonte/const.py +52 -0
  10. aioarpapiemonte-0.1.0/src/aioarpapiemonte/exceptions.py +24 -0
  11. aioarpapiemonte-0.1.0/src/aioarpapiemonte/models.py +481 -0
  12. aioarpapiemonte-0.1.0/src/aioarpapiemonte/parsers.py +344 -0
  13. aioarpapiemonte-0.1.0/src/aioarpapiemonte/py.typed +0 -0
  14. aioarpapiemonte-0.1.0/src/aioarpapiemonte/urls.py +82 -0
  15. aioarpapiemonte-0.1.0/tests/__init__.py +32 -0
  16. aioarpapiemonte-0.1.0/tests/conftest.py +45 -0
  17. aioarpapiemonte-0.1.0/tests/fixtures/real/data_pie_188.json +1 -0
  18. aioarpapiemonte-0.1.0/tests/fixtures/real/data_pie_999.json +1 -0
  19. aioarpapiemonte-0.1.0/tests/fixtures/real/idro_002105900.geojson +780 -0
  20. aioarpapiemonte-0.1.0/tests/fixtures/real/igro_001022905.geojson +780 -0
  21. aioarpapiemonte-0.1.0/tests/fixtures/real/nivo_001019900.geojson +780 -0
  22. aioarpapiemonte-0.1.0/tests/fixtures/real/pie_anag.json +1 -0
  23. aioarpapiemonte-0.1.0/tests/fixtures/real/pluv_001013900.geojson +780 -0
  24. aioarpapiemonte-0.1.0/tests/fixtures/real/sensors.geojson +21869 -0
  25. aioarpapiemonte-0.1.0/tests/fixtures/real/status.json +1 -0
  26. aioarpapiemonte-0.1.0/tests/fixtures/real/terma_002105900.geojson +780 -0
  27. aioarpapiemonte-0.1.0/tests/server.py +176 -0
  28. aioarpapiemonte-0.1.0/tests/test_client.py +294 -0
  29. aioarpapiemonte-0.1.0/tests/test_models.py +134 -0
  30. 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)