aiodpc 0.1.0__tar.gz

aiodpc-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+
+# Tool caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# Coverage
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Build artifacts
+build/
+dist/
+
+# Editors and OS
+.idea/
+.vscode/
+.DS_Store

aiodpc-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2019 caiosweet
+Copyright (c) 2026 Webysther Sperandio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aiodpc-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.5
+Name: aiodpc
+Version: 0.1.0
+Summary: Async client for the Italian Civil Protection Department (DPC) alert and weather vigilance bulletins
+Author: Webysther Sperandio
+License-Expression: MIT
+License-File: LICENSE
+Keywords: alert,allerta,asyncio,civil protection,dpc,italy,protezione civile,weather
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: aiohttp>=3.10
+Requires-Dist: geojson-utils<0.1,>=0.0.3
+Requires-Dist: tzdata; sys_platform == 'win32'
+Description-Content-Type: text/markdown
+
+# aiodpc
+
+Async Python client for the open data of the Italian Civil Protection
+Department (Dipartimento della Protezione Civile, DPC): the national alert
+bulletins.
+
+- **Bollettino di criticità idrogeologica e idraulica**: the alert level
+  (green, yellow, orange, red) of each alert zone for today and tomorrow, for
+  the hydraulic, thunderstorm and hydrogeological risks.
+- **Bollettino di vigilanza meteorologica**: the expected precipitation of each
+  vigilance zone for today, tomorrow and the day after, and the significant
+  weather phenomena (heavy rain, wind, sea storms, frost, fog, temperatures).
+
+Given a location (coordinates, optionally a municipality), aiodpc finds its
+zone and returns typed results. It is built on `asyncio` and `aiohttp`, has no
+Home Assistant dependency and is fully typed.
+
+## Installation
+
+```bash
+pip install aiodpc
+```
+
+Python 3.13 or later is required.
+
+## Usage
+
+```python
+import asyncio
+
+from aiodpc import AlertLevel, DpcClient, DpcError, Risk
+
+
+async def main() -> None:
+    async with DpcClient() as client:
+        try:
+            criticality = await client.get_criticality(41.9, 12.5)
+            vigilance = await client.get_vigilance(
+                41.9, 12.5, phenomena_radius_km=50
+            )
+        except DpcError as err:
+            print(f"DPC data unavailable: {err}")
+            return
+
+    print(f"Criticality bulletin {criticality.id}")
+    for day in criticality.days:
+        print(f"{day.date} {day.zone_name}: {day.summary.alert}")
+        for risk, assessment in day.risks.items():
+            print(f"  {risk.name.lower()}: {assessment.level.name}")
+
+    if (today := criticality.today()) and today.max_level >= AlertLevel.YELLOW:
+        print("Alert today:", today.risks[Risk.HYDROGEOLOGICAL].info)
+
+    for day in vigilance.days:
+        print(f"{day.date} {day.zone_name}: {day.precipitation}")
+        for phenomenon in day.phenomena:
+            print(
+                f"  {phenomenon.category} {phenomenon.description}"
+                f" {phenomenon.distance_km} km {phenomenon.direction}"
+            )
+
+
+asyncio.run(main())
+```
+
+Pass your own session with `DpcClient(session)`; the client never closes a
+session it did not create.
+
+### Days and expiry
+
+Each day of a bulletin carries its calendar `date` and its `expires` time (the
+midnight, Europe/Rome, that ends the day). Look days up by date instead of by
+position: `bulletin.day_for(date)`, `bulletin.today()` and
+`bulletin.tomorrow()`. After midnight the bulletin published the day before
+still answers `today()` with its second day until DPC publishes a new one.
+
+By default, days that are already over are not downloaded
+(`skip_expired=False` to get them all, e.g. for a past `bulletin_id`).
+
+### Polling
+
+The bulletin files are large (several MB per day). To poll, check the latest
+ID and fetch the bulletin only when it changed:
+
+```python
+from aiodpc import BulletinKind
+
+latest = await client.latest_bulletin_id(BulletinKind.CRITICALITY)
+if latest != criticality.id:
+    criticality = await client.get_criticality(41.9, 12.5, bulletin_id=latest)
+```
+
+The criticality bulletin is published every day by 16:00 (Europe/Rome) and may
+be re-issued later the same day ("Aggiornamento"); the vigilance bulletin by
+15:00.
+
+### Municipality
+
+With `municipality="Roma"`, the zones that list the municipality are
+considered and the one with the highest level is used; `zone_name` is the zone
+containing the coordinates. Large municipalities span several zones.
+
+### Coverage check
+
+`await client.is_location_covered(lat, lon)` returns whether the coordinates
+are inside a DPC alert zone, for example to validate a configuration.
+
+### Errors
+
+All errors derive from `DpcError`:
+
+- `DpcConnectionError`: network error, HTTP error status or timeout.
+- `DpcParseError`: invalid JSON or unexpected data format.
+- `DpcLocationError`: the location is not inside any zone of the bulletin.
+
+Invalid arguments (coordinates, bulletin IDs) raise `ValueError`.
+
+### Translations and codes
+
+The texts written by DPC are kept in Italian (`Assessment.info`,
+`Assessment.alert`, `VigilanceDay.precipitation`,
+`Phenomenon.description`). Codes are exposed for translation and icons:
+`AlertLevel`, `Risk` (value: the DPC code, e.g. `idraulico`),
+`PhenomenonCategory` (e.g. `PRECIPITAZIONI`) and `Phenomenon.code` (the DPC
+`id_fenomeno`).
+
+### Low-level API
+
+- `aiodpc.parsers`: pure parsing functions taking the decoded GeoJSON, to parse
+  one download for several locations or to test without network.
+- `aiodpc.urls`: URLs of the bulletin files.
+- `aiodpc.discovery`: the latest bulletin ID is read from the DPC map pages by
+  default (`MapPageIdSource`); implement `BulletinIdSource` to use another
+  source.
+
+## Data source and attribution
+
+The data is published by the Dipartimento della Protezione Civile on
+[mappe.protezionecivile.gov.it](https://mappe.protezionecivile.gov.it/) and
+GitHub
+([pcm-dpc/DPC-Bollettini-Criticita-Idrogeologica-Idraulica](https://github.com/pcm-dpc/DPC-Bollettini-Criticita-Idrogeologica-Idraulica),
+[pcm-dpc/DPC-Bollettini-Vigilanza-Meteorologica](https://github.com/pcm-dpc/DPC-Bollettini-Vigilanza-Meteorologica))
+under the [Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/)
+license. Applications showing the data must credit:
+
+> Dipartimento della Protezione Civile – Presidenza del Consiglio dei Ministri
+
+The text is available as `aiodpc.ATTRIBUTION`.
+
+This project is not affiliated with or endorsed by DPC. The bulletins are
+official, but this library is not: for safety decisions, always refer to
+the official DPC and regional channels.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install --editable . --group dev   # pip >= 25.1
+ruff format --check . && ruff check .
+mypy
+pytest --cov
+```
+
+The tests never reach DPC: a local HTTPS server answers for the DPC hosts.
+`tests/fixtures/real` holds unmodified excerpts of real bulletins to guard the
+data format.
+
+## Credits
+
+aiodpc derives from the [DPC Alert](https://github.com/caiosweet/Home-Assistant-custom-components-DPC-Alert)
+Home Assistant integration by caiosweet (MIT license).
+
+## License
+
+MIT, see [LICENSE](LICENSE).

aiodpc-0.1.0/README.md

@@ -0,0 +1,175 @@
+# aiodpc
+
+Async Python client for the open data of the Italian Civil Protection
+Department (Dipartimento della Protezione Civile, DPC): the national alert
+bulletins.
+
+- **Bollettino di criticità idrogeologica e idraulica**: the alert level
+  (green, yellow, orange, red) of each alert zone for today and tomorrow, for
+  the hydraulic, thunderstorm and hydrogeological risks.
+- **Bollettino di vigilanza meteorologica**: the expected precipitation of each
+  vigilance zone for today, tomorrow and the day after, and the significant
+  weather phenomena (heavy rain, wind, sea storms, frost, fog, temperatures).
+
+Given a location (coordinates, optionally a municipality), aiodpc finds its
+zone and returns typed results. It is built on `asyncio` and `aiohttp`, has no
+Home Assistant dependency and is fully typed.
+
+## Installation
+
+```bash
+pip install aiodpc
+```
+
+Python 3.13 or later is required.
+
+## Usage
+
+```python
+import asyncio
+
+from aiodpc import AlertLevel, DpcClient, DpcError, Risk
+
+
+async def main() -> None:
+    async with DpcClient() as client:
+        try:
+            criticality = await client.get_criticality(41.9, 12.5)
+            vigilance = await client.get_vigilance(
+                41.9, 12.5, phenomena_radius_km=50
+            )
+        except DpcError as err:
+            print(f"DPC data unavailable: {err}")
+            return
+
+    print(f"Criticality bulletin {criticality.id}")
+    for day in criticality.days:
+        print(f"{day.date} {day.zone_name}: {day.summary.alert}")
+        for risk, assessment in day.risks.items():
+            print(f"  {risk.name.lower()}: {assessment.level.name}")
+
+    if (today := criticality.today()) and today.max_level >= AlertLevel.YELLOW:
+        print("Alert today:", today.risks[Risk.HYDROGEOLOGICAL].info)
+
+    for day in vigilance.days:
+        print(f"{day.date} {day.zone_name}: {day.precipitation}")
+        for phenomenon in day.phenomena:
+            print(
+                f"  {phenomenon.category} {phenomenon.description}"
+                f" {phenomenon.distance_km} km {phenomenon.direction}"
+            )
+
+
+asyncio.run(main())
+```
+
+Pass your own session with `DpcClient(session)`; the client never closes a
+session it did not create.
+
+### Days and expiry
+
+Each day of a bulletin carries its calendar `date` and its `expires` time (the
+midnight, Europe/Rome, that ends the day). Look days up by date instead of by
+position: `bulletin.day_for(date)`, `bulletin.today()` and
+`bulletin.tomorrow()`. After midnight the bulletin published the day before
+still answers `today()` with its second day until DPC publishes a new one.
+
+By default, days that are already over are not downloaded
+(`skip_expired=False` to get them all, e.g. for a past `bulletin_id`).
+
+### Polling
+
+The bulletin files are large (several MB per day). To poll, check the latest
+ID and fetch the bulletin only when it changed:
+
+```python
+from aiodpc import BulletinKind
+
+latest = await client.latest_bulletin_id(BulletinKind.CRITICALITY)
+if latest != criticality.id:
+    criticality = await client.get_criticality(41.9, 12.5, bulletin_id=latest)
+```
+
+The criticality bulletin is published every day by 16:00 (Europe/Rome) and may
+be re-issued later the same day ("Aggiornamento"); the vigilance bulletin by
+15:00.
+
+### Municipality
+
+With `municipality="Roma"`, the zones that list the municipality are
+considered and the one with the highest level is used; `zone_name` is the zone
+containing the coordinates. Large municipalities span several zones.
+
+### Coverage check
+
+`await client.is_location_covered(lat, lon)` returns whether the coordinates
+are inside a DPC alert zone, for example to validate a configuration.
+
+### Errors
+
+All errors derive from `DpcError`:
+
+- `DpcConnectionError`: network error, HTTP error status or timeout.
+- `DpcParseError`: invalid JSON or unexpected data format.
+- `DpcLocationError`: the location is not inside any zone of the bulletin.
+
+Invalid arguments (coordinates, bulletin IDs) raise `ValueError`.
+
+### Translations and codes
+
+The texts written by DPC are kept in Italian (`Assessment.info`,
+`Assessment.alert`, `VigilanceDay.precipitation`,
+`Phenomenon.description`). Codes are exposed for translation and icons:
+`AlertLevel`, `Risk` (value: the DPC code, e.g. `idraulico`),
+`PhenomenonCategory` (e.g. `PRECIPITAZIONI`) and `Phenomenon.code` (the DPC
+`id_fenomeno`).
+
+### Low-level API
+
+- `aiodpc.parsers`: pure parsing functions taking the decoded GeoJSON, to parse
+  one download for several locations or to test without network.
+- `aiodpc.urls`: URLs of the bulletin files.
+- `aiodpc.discovery`: the latest bulletin ID is read from the DPC map pages by
+  default (`MapPageIdSource`); implement `BulletinIdSource` to use another
+  source.
+
+## Data source and attribution
+
+The data is published by the Dipartimento della Protezione Civile on
+[mappe.protezionecivile.gov.it](https://mappe.protezionecivile.gov.it/) and
+GitHub
+([pcm-dpc/DPC-Bollettini-Criticita-Idrogeologica-Idraulica](https://github.com/pcm-dpc/DPC-Bollettini-Criticita-Idrogeologica-Idraulica),
+[pcm-dpc/DPC-Bollettini-Vigilanza-Meteorologica](https://github.com/pcm-dpc/DPC-Bollettini-Vigilanza-Meteorologica))
+under the [Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/)
+license. Applications showing the data must credit:
+
+> Dipartimento della Protezione Civile – Presidenza del Consiglio dei Ministri
+
+The text is available as `aiodpc.ATTRIBUTION`.
+
+This project is not affiliated with or endorsed by DPC. The bulletins are
+official, but this library is not: for safety decisions, always refer to
+the official DPC and regional channels.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install --editable . --group dev   # pip >= 25.1
+ruff format --check . && ruff check .
+mypy
+pytest --cov
+```
+
+The tests never reach DPC: a local HTTPS server answers for the DPC hosts.
+`tests/fixtures/real` holds unmodified excerpts of real bulletins to guard the
+data format.
+
+## Credits
+
+aiodpc derives from the [DPC Alert](https://github.com/caiosweet/Home-Assistant-custom-components-DPC-Alert)
+Home Assistant integration by caiosweet (MIT license).
+
+## License
+
+MIT, see [LICENSE](LICENSE).

aiodpc-0.1.0/pyproject.toml

@@ -0,0 +1,115 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aiodpc"
+dynamic = ["version"]
+description = "Async client for the Italian Civil Protection Department (DPC) alert and weather vigilance bulletins"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Webysther Sperandio" }]
+requires-python = ">=3.13"
+keywords = [
+  "allerta",
+  "alert",
+  "asyncio",
+  "civil protection",
+  "dpc",
+  "italy",
+  "protezione civile",
+  "weather",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: AsyncIO",
+  "Intended Audience :: Developers",
+  "Natural Language :: English",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Scientific/Engineering :: Atmospheric Science",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+dependencies = [
+  "aiohttp>=3.10",
+  "geojson-utils>=0.0.3,<0.1",
+  # zoneinfo needs a time zone database; Windows has none built in.
+  "tzdata; sys_platform == 'win32'",
+]
+
+[dependency-groups]
+dev = [
+  "mypy>=1.15",
+  "pytest>=8.3",
+  "pytest-asyncio>=1.0",
+  "pytest-cov>=6.0",
+  "ruff==0.14.4",
+  # Certificates of the local HTTPS server standing in for DPC in the tests
+  "trustme>=1.2",
+]
+
+[tool.hatch.version]
+path = "src/aiodpc/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aiodpc"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE"]
+
+[tool.ruff]
+target-version = "py313"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+  "COM812", # conflicts with the formatter
+  "D203",   # incompatible with D211
+  "D213",   # incompatible with D212
+  "PLR0913", # keyword-only options on public methods
+]
+
+[tool.ruff.lint.flake8-type-checking]
+# Keep the imports of dataclass annotations at runtime (typing.get_type_hints).
+runtime-evaluated-decorators = ["dataclasses.dataclass"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+  "PLR2004", # magic values in assertions
+  "S101",    # assert
+  "SLF001",  # private access to test internals
+]
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+files = ["src", "tests"]
+mypy_path = "src"
+
+[[tool.mypy.overrides]]
+# geojson-utils ships type hints but no py.typed marker.
+module = ["geojson_utils", "geojson_utils.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+addopts = "--strict-markers --strict-config"
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+source = ["aiodpc"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+fail_under = 95
+exclude_also = ["if TYPE_CHECKING:", "\\.\\.\\."]

aiodpc-0.1.0/src/aiodpc/__init__.py

@@ -0,0 +1,62 @@
+"""Async client for the Italian Civil Protection Department (DPC) bulletins.
+
+It reads the national "Bollettino di criticità idrogeologica e idraulica"
+(alert levels per risk) and "Bollettino di vigilanza meteorologica" (weather
+vigilance and phenomena) published by DPC as open data.
+"""
+
+from .client import DpcClient
+from .const import (
+    ATTRIBUTION,
+    CRITICALITY_PAGE_URL,
+    DEFAULT_PHENOMENA_RADIUS_KM,
+    DEFAULT_REQUEST_TIMEOUT,
+    ROME_TZ,
+    VIGILANCE_PAGE_URL,
+)
+from .discovery import BulletinIdSource, MapPageIdSource, TextFetcher
+from .exceptions import DpcConnectionError, DpcError, DpcLocationError, DpcParseError
+from .models import (
+    AlertLevel,
+    Assessment,
+    BulletinKind,
+    CriticalityBulletin,
+    CriticalityDay,
+    Phenomenon,
+    PhenomenonCategory,
+    Risk,
+    VigilanceBulletin,
+    VigilanceDay,
+    rome_date,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ATTRIBUTION",
+    "CRITICALITY_PAGE_URL",
+    "DEFAULT_PHENOMENA_RADIUS_KM",
+    "DEFAULT_REQUEST_TIMEOUT",
+    "ROME_TZ",
+    "VIGILANCE_PAGE_URL",
+    "AlertLevel",
+    "Assessment",
+    "BulletinIdSource",
+    "BulletinKind",
+    "CriticalityBulletin",
+    "CriticalityDay",
+    "DpcClient",
+    "DpcConnectionError",
+    "DpcError",
+    "DpcLocationError",
+    "DpcParseError",
+    "MapPageIdSource",
+    "Phenomenon",
+    "PhenomenonCategory",
+    "Risk",
+    "TextFetcher",
+    "VigilanceBulletin",
+    "VigilanceDay",
+    "__version__",
+    "rome_date",
+]