aiodpc 0.1.0__py3-none-any.whl

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",
+]

aiodpc/client.py

@@ -0,0 +1,351 @@
+"""Async client of the DPC bulletins."""
+
+from __future__ import annotations
+
+import asyncio
+import datetime as dt
+import json
+import logging
+import math
+from typing import TYPE_CHECKING, Any, Final, Self
+
+import aiohttp
+
+from .const import DEFAULT_PHENOMENA_RADIUS_KM, DEFAULT_REQUEST_TIMEOUT, ROME_TZ
+from .discovery import BulletinIdSource, MapPageIdSource
+from .exceptions import DpcConnectionError, DpcError, DpcParseError
+from .models import (
+    BulletinKind,
+    CriticalityBulletin,
+    CriticalityDay,
+    VigilanceBulletin,
+    VigilanceDay,
+)
+from .parsers import (
+    day_expires,
+    location_in_zones,
+    parse_criticality_day,
+    parse_criticality_id,
+    parse_phenomena,
+    parse_vigilance_day,
+    parse_vigilance_id,
+)
+from .urls import (
+    CRITICALITY_DAYS,
+    VIGILANCE_DAYS,
+    criticality_geojson_url,
+    phenomena_geojson_url,
+    vigilance_geojson_url,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Coroutine, Iterable
+
+_LOGGER = logging.getLogger(__name__)
+
+_MAX_LATITUDE: Final = 90.0
+_MAX_LONGITUDE: Final = 180.0
+
+
+class DpcClient:
+    """Async client of the DPC criticality and weather vigilance bulletins.
+
+    Pass the ``aiohttp.ClientSession`` of the application (it is never closed
+    by the client), or use the client as an async context manager to let it
+    manage its own session::
+
+        async with DpcClient() as client:
+            bulletin = await client.get_criticality(41.9, 12.5)
+
+    The bulletin files are large (a few MB per day): to poll, compare
+    :meth:`latest_bulletin_id` with the ID of the bulletin already fetched and
+    fetch the bulletin again only when it changed.
+    """
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession | None = None,
+        *,
+        request_timeout: float = DEFAULT_REQUEST_TIMEOUT,
+        id_source: BulletinIdSource | None = None,
+    ) -> None:
+        """Initialize the client.
+
+        ``request_timeout`` applies to each HTTP request, in seconds.
+        ``id_source`` finds the latest bulletin IDs (default: the DPC map pages).
+        """
+        self._session = session
+        self._close_session = False
+        self._request_timeout = request_timeout
+        self._id_source: BulletinIdSource = id_source or MapPageIdSource()
+
+    async def __aenter__(self) -> Self:
+        """Enter the async context."""
+        return self
+
+    async def __aexit__(self, *_exc_info: object) -> None:
+        """Exit the async context, closing the session owned by the client."""
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the session if the client created it."""
+        if self._session is not None and self._close_session:
+            await self._session.close()
+            self._session = None
+            self._close_session = False
+
+    async def latest_bulletin_id(self, kind: BulletinKind) -> str:
+        """Return the ID of the latest published bulletin of a kind.
+
+        Raises :class:`DpcConnectionError` or :class:`DpcParseError`.
+        """
+        kind = BulletinKind(kind)
+        bulletin_id = await self._id_source.latest_id(kind, self._fetch_text)
+        try:
+            if kind is BulletinKind.CRITICALITY:
+                parse_criticality_id(bulletin_id)
+            else:
+                parse_vigilance_id(bulletin_id)
+        except ValueError as err:
+            msg = f"Invalid {kind} bulletin ID from the ID source: {bulletin_id!r}"
+            raise DpcParseError(msg) from err
+        _LOGGER.debug("Latest %s bulletin: %s", kind, bulletin_id)
+        return bulletin_id
+
+    async def get_criticality(
+        self,
+        latitude: float,
+        longitude: float,
+        *,
+        municipality: str | None = None,
+        bulletin_id: str | None = None,
+        skip_expired: bool = True,
+        now: dt.datetime | None = None,
+    ) -> CriticalityBulletin:
+        """Return the criticality bulletin for a location.
+
+        ``municipality`` (optional) selects, among the zones listing it, the one
+        with the highest alert. ``bulletin_id`` defaults to the latest bulletin.
+        With ``skip_expired``, days already over at ``now`` (default: the
+        current time) are not downloaded and are missing from ``days``.
+
+        Raises :class:`DpcConnectionError`, :class:`DpcParseError` or
+        :class:`DpcLocationError`; ``ValueError`` for invalid arguments.
+        """
+        _check_location(latitude, longitude)
+        if bulletin_id is None:
+            bulletin_id = await self.latest_bulletin_id(BulletinKind.CRITICALITY)
+        published = parse_criticality_id(bulletin_id)
+        offsets = _offsets(
+            published.date(),
+            len(CRITICALITY_DAYS),
+            skip_expired=skip_expired,
+            now=now,
+        )
+        days = await _gather(
+            self._criticality_day(
+                bulletin_id, offset, latitude, longitude, municipality
+            )
+            for offset in offsets
+        )
+        return CriticalityBulletin(
+            id=bulletin_id, published=published, days=tuple(days)
+        )
+
+    async def get_vigilance(
+        self,
+        latitude: float,
+        longitude: float,
+        *,
+        municipality: str | None = None,
+        phenomena_radius_km: float = DEFAULT_PHENOMENA_RADIUS_KM,
+        bulletin_id: str | None = None,
+        skip_expired: bool = True,
+        now: dt.datetime | None = None,
+    ) -> VigilanceBulletin:
+        """Return the weather vigilance bulletin for a location.
+
+        Each day includes the phenomena within ``phenomena_radius_km`` of the
+        coordinates. The other arguments are as in :meth:`get_criticality`.
+
+        Raises :class:`DpcConnectionError`, :class:`DpcParseError` or
+        :class:`DpcLocationError`; ``ValueError`` for invalid arguments.
+        """
+        _check_location(latitude, longitude)
+        if not (math.isfinite(phenomena_radius_km) and phenomena_radius_km >= 0):
+            msg = f"Invalid phenomena radius: {phenomena_radius_km}"
+            raise ValueError(msg)
+        if bulletin_id is None:
+            bulletin_id = await self.latest_bulletin_id(BulletinKind.VIGILANCE)
+        published = parse_vigilance_id(bulletin_id)
+        offsets = _offsets(
+            published, len(VIGILANCE_DAYS), skip_expired=skip_expired, now=now
+        )
+        days = await _gather(
+            self._vigilance_day(
+                bulletin_id,
+                offset,
+                latitude,
+                longitude,
+                municipality,
+                phenomena_radius_km,
+            )
+            for offset in offsets
+        )
+        return VigilanceBulletin(id=bulletin_id, date=published, days=tuple(days))
+
+    async def is_location_covered(self, latitude: float, longitude: float) -> bool:
+        """Return whether a location is inside a DPC alert zone.
+
+        The zones of the latest criticality bulletin are used, or those of the
+        vigilance bulletin when the former cannot be fetched.
+
+        Raises the first :class:`DpcError` when no bulletin could be used.
+        """
+        _check_location(latitude, longitude)
+        sources = (
+            (BulletinKind.CRITICALITY, criticality_geojson_url),
+            (BulletinKind.VIGILANCE, vigilance_geojson_url),
+        )
+        errors: list[DpcError] = []
+        for kind, geojson_url in sources:
+            try:
+                bulletin_id = await self.latest_bulletin_id(kind)
+            except DpcError as err:
+                errors.append(err)
+                continue
+            for offset in (0, 1):
+                try:
+                    geojson = await self._fetch_json(geojson_url(bulletin_id, offset))
+                    return location_in_zones(geojson, latitude, longitude)
+                except DpcError as err:
+                    errors.append(err)
+        raise errors[0]
+
+    async def _criticality_day(
+        self,
+        bulletin_id: str,
+        offset: int,
+        latitude: float,
+        longitude: float,
+        municipality: str | None,
+    ) -> CriticalityDay:
+        geojson = await self._fetch_json(criticality_geojson_url(bulletin_id, offset))
+        return parse_criticality_day(
+            geojson,
+            bulletin_id=bulletin_id,
+            offset=offset,
+            latitude=latitude,
+            longitude=longitude,
+            municipality=municipality,
+        )
+
+    async def _vigilance_day(
+        self,
+        bulletin_id: str,
+        offset: int,
+        latitude: float,
+        longitude: float,
+        municipality: str | None,
+        phenomena_radius_km: float,
+    ) -> VigilanceDay:
+        zones, phenomena = await _gather(
+            self._fetch_json(url(bulletin_id, offset))
+            for url in (vigilance_geojson_url, phenomena_geojson_url)
+        )
+        return parse_vigilance_day(
+            zones,
+            bulletin_id=bulletin_id,
+            offset=offset,
+            latitude=latitude,
+            longitude=longitude,
+            municipality=municipality,
+            phenomena=parse_phenomena(
+                phenomena,
+                latitude=latitude,
+                longitude=longitude,
+                radius_km=phenomena_radius_km,
+            ),
+        )
+
+    def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None:
+            self._session = aiohttp.ClientSession()
+            self._close_session = True
+        return self._session
+
+    async def _request(self, url: str) -> bytes:
+        """Return the body at a URL, mapping every failure to DpcConnectionError."""
+        session = self._get_session()
+        _LOGGER.debug("Fetching %s", url)
+        try:
+            async with (
+                asyncio.timeout(self._request_timeout),
+                session.get(url) as response,
+            ):
+                response.raise_for_status()
+                return await response.read()
+        except TimeoutError as err:
+            msg = f"Timeout fetching {url}"
+            raise DpcConnectionError(msg) from err
+        except aiohttp.ClientResponseError as err:
+            msg = f"HTTP status {err.status} fetching {url}"
+            raise DpcConnectionError(msg) from err
+        except (aiohttp.ClientError, OSError) as err:
+            msg = f"Error fetching {url}: {err!r}"
+            raise DpcConnectionError(msg) from err
+
+    async def _fetch_text(self, url: str) -> str:
+        return (await self._request(url)).decode("utf-8", errors="replace")
+
+    async def _fetch_json(self, url: str) -> object:
+        body = await self._request(url)
+        try:
+            data: object = json.loads(body)
+        except ValueError as err:
+            msg = f"Invalid JSON from {url}"
+            raise DpcParseError(msg) from err
+        return data
+
+
+def _check_location(latitude: float, longitude: float) -> None:
+    if not (math.isfinite(latitude) and -_MAX_LATITUDE <= latitude <= _MAX_LATITUDE):
+        msg = f"Invalid latitude: {latitude}"
+        raise ValueError(msg)
+    if not (
+        math.isfinite(longitude) and -_MAX_LONGITUDE <= longitude <= _MAX_LONGITUDE
+    ):
+        msg = f"Invalid longitude: {longitude}"
+        raise ValueError(msg)
+
+
+def _offsets(
+    first_day: dt.date, count: int, *, skip_expired: bool, now: dt.datetime | None
+) -> list[int]:
+    """Return the day offsets to fetch, without the expired days if asked."""
+    if not skip_expired:
+        return list(range(count))
+    if now is None:
+        now = dt.datetime.now(ROME_TZ)
+    elif now.tzinfo is None:
+        now = now.replace(tzinfo=ROME_TZ)
+    return [
+        offset
+        for offset in range(count)
+        if day_expires(first_day + dt.timedelta(days=offset)) > now
+    ]
+
+
+async def _gather[T](coros: Iterable[Coroutine[Any, Any, T]]) -> list[T]:
+    """Run coroutines concurrently and return their results in order.
+
+    On the first failure the other coroutines are cancelled and that exception
+    is raised as is (not wrapped in an ExceptionGroup). Cancellation propagates.
+    """
+    try:
+        async with asyncio.TaskGroup() as group:
+            tasks = [group.create_task(coro) for coro in coros]
+    except ExceptionGroup as err:
+        error = err.exceptions[0]
+        raise error from error.__cause__
+    return [task.result() for task in tasks]

aiodpc/const.py

@@ -0,0 +1,42 @@
+"""Constants of the DPC open data."""
+
+from __future__ import annotations
+
+from typing import Final
+from zoneinfo import ZoneInfo
+
+ROME_TZ: Final = ZoneInfo("Europe/Rome")
+"""Time zone of the bulletins: their days are Italian calendar days."""
+
+ATTRIBUTION: Final = (
+    "Dipartimento della Protezione Civile – Presidenza del Consiglio dei Ministri"  # noqa: RUF001
+)
+"""Attribution required by the CC BY 4.0 license of the DPC data."""
+
+CRITICALITY_PAGE_URL: Final = (
+    "https://mappe.protezionecivile.gov.it/it/mappe-rischi/bollettino-di-criticita/"
+)
+"""Map page of the criticality bulletin ("Bollettino di criticità")."""
+
+VIGILANCE_PAGE_URL: Final = (
+    "https://mappe.protezionecivile.gov.it/it/mappe-rischi/bollettino-di-vigilanza/"
+)
+"""Map page of the weather vigilance bulletin ("Bollettino di vigilanza")."""
+
+CRITICALITY_FILES_URL: Final = (
+    "https://raw.githubusercontent.com/pcm-dpc/"
+    "DPC-Bollettini-Criticita-Idrogeologica-Idraulica/master/files"
+)
+"""Base URL of the criticality bulletin files published by DPC on GitHub."""
+
+VIGILANCE_FILES_URL: Final = (
+    "https://raw.githubusercontent.com/pcm-dpc/"
+    "DPC-Bollettini-Vigilanza-Meteorologica/master/files"
+)
+"""Base URL of the vigilance bulletin files published by DPC on GitHub."""
+
+DEFAULT_REQUEST_TIMEOUT: Final = 30.0
+"""Default timeout of each HTTP request, in seconds."""
+
+DEFAULT_PHENOMENA_RADIUS_KM: Final = 50.0
+"""Default radius around the location to report weather phenomena, in km."""

aiodpc/discovery.py

@@ -0,0 +1,87 @@
+"""Discovery of the ID of the latest bulletins.
+
+The ID is what names the bulletin files, so it must be found before anything
+else. The default :class:`MapPageIdSource` reads it from the DPC map pages
+with a regular expression. Another source (for example the GitHub contents
+API, which is rate-limited to 60 requests per hour without a token) can be
+plugged into :class:`aiodpc.DpcClient` by implementing
+:class:`BulletinIdSource`.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Awaitable, Callable, Mapping
+from typing import Final, Protocol
+
+from .const import CRITICALITY_PAGE_URL, VIGILANCE_PAGE_URL
+from .exceptions import DpcParseError
+from .models import BulletinKind
+from .parsers import parse_criticality_id, parse_vigilance_id
+
+type TextFetcher = Callable[[str], Awaitable[str]]
+"""Coroutine function returning the text at a URL.
+
+It raises :class:`aiodpc.DpcConnectionError` when the URL cannot be fetched.
+"""
+
+# 20261114_1430 (criticality) and 20261114.json (vigilance), as linked by the
+# map pages; the lookarounds keep them from matching inside longer numbers.
+_ID_PATTERNS: Final = {
+    BulletinKind.CRITICALITY: re.compile(r"(?<!\d)(\d{8}_\d{4})(?!\d)"),
+    BulletinKind.VIGILANCE: re.compile(r"(?<!\d)(\d{8})\.json", re.IGNORECASE),
+}
+_ID_PARSERS: Final[Mapping[BulletinKind, Callable[[str], object]]] = {
+    BulletinKind.CRITICALITY: parse_criticality_id,
+    BulletinKind.VIGILANCE: parse_vigilance_id,
+}
+
+
+def extract_bulletin_id(kind: BulletinKind, text: str) -> str:
+    """Return the latest bulletin ID of a kind found in a text (a DPC map page).
+
+    Matches that are not valid dates are ignored. When the text links more than
+    one bulletin (e.g. an "Aggiornamento" re-issue), the latest one is returned.
+
+    Raises :class:`aiodpc.DpcParseError` when the text contains no valid ID.
+    """
+    ids: set[str] = set()
+    for bulletin_id in _ID_PATTERNS[kind].findall(text):
+        try:
+            _ID_PARSERS[kind](bulletin_id)
+        except ValueError:
+            continue
+        ids.add(bulletin_id)
+    if not ids:
+        msg = f"No {kind} bulletin ID found in the DPC page"
+        raise DpcParseError(msg)
+    # The fixed-width IDs sort chronologically.
+    return max(ids)
+
+
+class BulletinIdSource(Protocol):
+    """Strategy that finds the ID of the latest bulletin of a kind."""
+
+    async def latest_id(self, kind: BulletinKind, fetch_text: TextFetcher) -> str:
+        """Return the ID of the latest bulletin of ``kind``.
+
+        ``fetch_text`` performs the HTTP requests with the client's session and
+        timeout. Raise :class:`aiodpc.DpcConnectionError` or
+        :class:`aiodpc.DpcParseError` when the ID cannot be found.
+        """
+        ...
+
+
+class MapPageIdSource:
+    """Find the latest bulletin IDs in the DPC map pages (the default source)."""
+
+    def __init__(self, page_urls: Mapping[BulletinKind, str] | None = None) -> None:
+        """Initialize the source, optionally with other page URLs."""
+        self._page_urls: Mapping[BulletinKind, str] = page_urls or {
+            BulletinKind.CRITICALITY: CRITICALITY_PAGE_URL,
+            BulletinKind.VIGILANCE: VIGILANCE_PAGE_URL,
+        }
+
+    async def latest_id(self, kind: BulletinKind, fetch_text: TextFetcher) -> str:
+        """Return the ID of the latest bulletin of ``kind`` linked by its page."""
+        return extract_bulletin_id(kind, await fetch_text(self._page_urls[kind]))

aiodpc/exceptions.py

@@ -0,0 +1,23 @@
+"""Exceptions raised by aiodpc."""
+
+from __future__ import annotations
+
+
+class DpcError(Exception):
+    """Base class of the aiodpc errors."""
+
+
+class DpcConnectionError(DpcError):
+    """DPC could not be reached: network error, HTTP error status or timeout."""
+
+
+class DpcParseError(DpcError):
+    """DPC returned data that is not valid JSON or has an unexpected format."""
+
+
+class DpcLocationError(DpcError):
+    """The location is not inside any alert zone of the bulletin.
+
+    This is permanent for the given coordinates (for example a location outside
+    Italy or at sea), so retrying does not help.
+    """

aiodpc/geo.py

@@ -0,0 +1,76 @@
+"""Geometry helpers on (latitude, longitude) points and GeoJSON geometries."""
+
+from __future__ import annotations
+
+import math
+from typing import TYPE_CHECKING, Any, Final
+
+from geojson_utils import point_distance, point_in_polygon
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+COMPASS_POINTS: Final = (
+    "N",
+    "NNE",
+    "NE",
+    "ENE",
+    "E",
+    "ESE",
+    "SE",
+    "SSE",
+    "S",
+    "SSW",
+    "SW",
+    "WSW",
+    "W",
+    "WNW",
+    "NW",
+    "NNW",
+)
+
+_AREA_TYPES: Final = frozenset({"Polygon", "MultiPolygon"})
+
+
+def geojson_point(latitude: float, longitude: float) -> dict[str, Any]:
+    """Return a GeoJSON Point (GeoJSON orders coordinates as longitude, latitude)."""
+    return {"type": "Point", "coordinates": [longitude, latitude]}
+
+
+def point_in_area(
+    latitude: float, longitude: float, geometry: Mapping[str, Any]
+) -> bool:
+    """Return whether a point is inside a Polygon or MultiPolygon geometry.
+
+    Points on the boundary count as inside; other geometry types never
+    contain a point.
+    """
+    if geometry.get("type") not in _AREA_TYPES:
+        return False
+    return bool(point_in_polygon(geojson_point(latitude, longitude), dict(geometry)))
+
+
+def distance_km(point_a: tuple[float, float], point_b: tuple[float, float]) -> float:
+    """Return the great-circle distance in km between two (lat, lon) points."""
+    meters = point_distance(geojson_point(*point_a), geojson_point(*point_b))
+    return float(meters) / 1000
+
+
+def calculate_initial_compass_bearing(
+    point_a: tuple[float, float], point_b: tuple[float, float]
+) -> tuple[str, int]:
+    """Return the compass point and degrees from point_a to point_b (lat, lon).
+
+    Credits: https://gist.github.com/jeromer/2005586
+    and https://gist.github.com/RobertSudwarts/acf8df23a16afdb5837f
+    """
+    lat1 = math.radians(point_a[0])
+    lat2 = math.radians(point_b[0])
+    diff_long = math.radians(point_b[1] - point_a[1])
+    x = math.sin(diff_long) * math.cos(lat2)
+    y = math.cos(lat1) * math.sin(lat2) - (
+        math.sin(lat1) * math.cos(lat2) * math.cos(diff_long)
+    )
+    compass_bearing = (math.degrees(math.atan2(x, y)) + 360) % 360
+    index = round(compass_bearing / (360.0 / len(COMPASS_POINTS)))
+    return COMPASS_POINTS[index % len(COMPASS_POINTS)], math.floor(compass_bearing)