env_canada 0.15.0__py3-none-any.whl

env_canada/__init__.py

@@ -0,0 +1,19 @@
+__all__ = [
+    "ECAirQuality",
+    "ECAlerts",
+    "ECHistorical",
+    "ECHistoricalRange",
+    "ECHydro",
+    "ECMap",
+    "ECRadar",
+    "ECWeather",
+    "ECWeatherUpdateFailed",
+]
+
+from .ec_aqhi import ECAirQuality
+from .ec_alerts import ECAlerts
+from .ec_historical import ECHistorical, ECHistoricalRange
+from .ec_hydro import ECHydro
+from .ec_radar import ECRadar
+from .ec_map import ECMap
+from .ec_weather import ECWeather, ECWeatherUpdateFailed

env_canada/constants.py

@@ -0,0 +1 @@
+USER_AGENT = "env_canada/0.15.0"

env_canada/ec_alerts.py

@@ -0,0 +1,164 @@
+import copy
+import logging
+import math
+from dataclasses import dataclass
+from datetime import datetime, timedelta, UTC
+
+from aiohttp import ClientSession, ClientTimeout
+
+from .constants import USER_AGENT
+from .ec_cache import Cache
+
+
+def _point_in_polygon(lon, lat, ring):
+    """Ray-casting point-in-polygon test for a single ring."""
+    inside = False
+    j = len(ring) - 1
+    for i, (xi, yi) in enumerate(ring):
+        xj, yj = ring[j]
+        if (yi > lat) != (yj > lat) and lon < (xj - xi) * (lat - yi) / (yj - yi) + xi:
+            inside = not inside
+        j = i
+    return inside
+
+
+def _point_in_geometry(lon, lat, geometry):
+    """Return True if (lon, lat) falls within a GeoJSON Polygon or MultiPolygon."""
+    gtype = geometry.get("type")
+    coords = geometry.get("coordinates", [])
+    if gtype == "Polygon":
+        return _point_in_polygon(lon, lat, coords[0])
+    if gtype == "MultiPolygon":
+        return any(_point_in_polygon(lon, lat, poly[0]) for poly in coords)
+    return False
+
+
+GEOMET_WFS_URL = "https://geo.weather.gc.ca/geomet"
+
+ALERTS_WFS_PARAMS = {
+    "SERVICE": "WFS",
+    "VERSION": "2.0.0",
+    "REQUEST": "GetFeature",
+    "TYPENAMES": "Current-Alerts",
+    "outputFormat": "application/json",
+}
+
+CLIENT_TIMEOUT = ClientTimeout(10)
+
+CACHE_TTL = timedelta(minutes=5)
+
+ATTRIBUTION = {
+    "english": "Data provided by Environment Canada",
+    "french": "Données fournies par Environnement Canada",
+}
+
+LOG = logging.getLogger(__name__)
+
+__all__ = ["ECAlerts"]
+
+
+@dataclass
+class MetaData:
+    attribution: str
+    timestamp: datetime = datetime(1970, 1, 1, 0, 0, tzinfo=UTC)
+
+
+class ECAlerts:
+    """Get weather alerts from Environment Canada GeoMet WFS."""
+
+    def __init__(self, coordinates, language="english"):
+        """Initialize ECAlerts with coordinates and language."""
+        from .ec_weather import ALERTS_INIT  # lazy import to avoid circular dependency
+
+        self.lat = coordinates[0]
+        self.lon = coordinates[1]
+        self.language = language
+        self.metadata = MetaData(ATTRIBUTION[language])
+        self.alerts = copy.deepcopy(ALERTS_INIT[language])
+        self.alert_features = []
+
+    async def update(self):
+        """Fetch current alerts from Environment Canada GeoMet WFS."""
+        from .ec_weather import ALERTS_INIT, ALERT_TYPE_TO_NAME  # lazy import
+
+        cache_key = f"alerts-{self.language}-{self.lat:.4f}-{self.lon:.4f}"
+        cached = Cache.get(cache_key)
+        if cached is not None:
+            self.alerts, self.alert_features = cached
+            return
+
+        km = 50
+        lat_delta = km / 111.0
+        lon_delta = km / (111.0 * math.cos(math.radians(self.lat)))
+        bbox = (
+            f"{self.lat - lat_delta:.4f},{self.lon - lon_delta:.4f},"
+            f"{self.lat + lat_delta:.4f},{self.lon + lon_delta:.4f},EPSG:4326"
+        )
+        params = {**ALERTS_WFS_PARAMS, "BBOX": bbox}
+
+        async with ClientSession(raise_for_status=True) as session:
+            response = await session.get(
+                GEOMET_WFS_URL,
+                params=params,
+                headers={"User-Agent": USER_AGENT},
+                timeout=CLIENT_TIMEOUT,
+            )
+            data = await response.json()
+
+        if not isinstance(data, dict) or data.get("type") != "FeatureCollection":
+            raise ValueError(f"Unexpected WFS response type: {type(data)}")
+
+        lang_suffix = "en" if self.language == "english" else "fr"
+
+        self.alerts = copy.deepcopy(ALERTS_INIT[self.language])
+        self.alert_features = []
+
+        for feature in data.get("features", []):
+            props = feature.get("properties", {})
+            if not isinstance(props, dict):
+                continue
+
+            geometry = feature.get("geometry") or {}
+            if not _point_in_geometry(self.lon, self.lat, geometry):
+                continue
+
+            self.alert_features.append(props)
+
+            status_en = (props.get("status_en") or "").lower()
+            alert_type = (props.get("alert_type") or "").lower()
+
+            # Ended alerts go to endings category regardless of alert_type
+            if status_en == "ended":
+                category = "endings"
+            else:
+                category = ALERT_TYPE_TO_NAME.get(alert_type)
+                if category is None:
+                    continue
+
+            title = props.get(f"alert_name_{lang_suffix}") or ""
+
+            alert_dict = {
+                "title": title.strip().title() if title else title,
+                "date": props.get("publication_datetime"),
+                "alertColourLevel": props.get(f"risk_colour_{lang_suffix}"),
+                "expiryTime": props.get("expiration_datetime"),
+                # Additive new fields
+                "text": props.get(f"alert_text_{lang_suffix}"),
+                "area": props.get(f"feature_name_{lang_suffix}"),
+                "status": props.get(f"status_{lang_suffix}"),
+                "confidence": props.get(f"confidence_{lang_suffix}"),
+                "impact": props.get(f"impact_{lang_suffix}"),
+                "alert_code": props.get("alert_code"),
+            }
+
+            self.alerts[category]["value"].append(alert_dict)
+
+        Cache.add(cache_key, (self.alerts, self.alert_features), CACHE_TTL)
+        self.metadata.timestamp = datetime.now(UTC)
+
+        LOG.debug(
+            "update(): fetched %d alert features for (%f, %f)",
+            len(self.alert_features),
+            self.lat,
+            self.lon,
+        )

env_canada/ec_aqhi.py

@@ -0,0 +1,233 @@
+import logging
+from dataclasses import dataclass
+from datetime import datetime, UTC
+
+import voluptuous as vol
+from aiohttp import ClientSession, ClientTimeout
+from geopy import distance
+from lxml import etree as et
+
+from .constants import USER_AGENT
+
+AQHI_SITE_LIST_URL = (
+    "https://dd.weather.gc.ca/today/air_quality/doc/AQHI_XML_File_List.xml"
+)
+AQHI_OBSERVATION_URL = "https://dd.weather.gc.ca/today/air_quality/aqhi/{}/observation/realtime/xml/AQ_OBS_{}_CURRENT.xml"
+AQHI_FORECAST_URL = "https://dd.weather.gc.ca/today/air_quality/aqhi/{}/forecast/realtime/xml/AQ_FCST_{}_CURRENT.xml"
+
+CLIENT_TIMEOUT = ClientTimeout(10)
+
+LOG = logging.getLogger(__name__)
+
+ATTRIBUTION = {
+    "EN": "Data provided by Environment Canada",
+    "FR": "Données fournies par Environnement Canada",
+}
+
+
+@dataclass
+class MetaData:
+    attribution: str
+    timestamp: datetime | None = None
+    location: str | None = None
+
+    # Not used; needed for compatability with ec_weather metadata
+    station: str | None = None
+
+
+__all__ = ["ECAirQuality"]
+
+
+def timestamp_to_datetime(timestamp):
+    dt = datetime.strptime(timestamp, "%Y%m%d%H%M%S")
+    dt = dt.replace(tzinfo=UTC)
+    return dt
+
+
+async def get_aqhi_regions(language):
+    """Get list of all AQHI regions from Environment Canada, for auto-config."""
+    zone_name_tag = f"name_{language.lower()}_CA"
+    region_name_tag = f"name{language.title()}"
+
+    LOG.debug("get_aqhi_regions() started")
+
+    regions = []
+    async with ClientSession(raise_for_status=True) as session:
+        response = await session.get(
+            AQHI_SITE_LIST_URL,
+            headers={"User-Agent": USER_AGENT},
+            timeout=CLIENT_TIMEOUT,
+        )
+        result = await response.read()
+
+    site_xml = result
+    xml_object = et.fromstring(site_xml)
+
+    for zone in xml_object.findall("./EC_administrativeZone"):
+        _zone_attribs = zone.attrib
+        _zone_attrib = {
+            "abbreviation": _zone_attribs["abreviation"],
+            "zone_name": _zone_attribs[zone_name_tag],
+        }
+        for region in zone.findall("./regionList/region"):
+            _region_attribs = region.attrib
+
+            _region_attrib = {
+                "region_name": _region_attribs[region_name_tag],
+                "cgndb": _region_attribs["cgndb"],
+                "latitude": float(_region_attribs["latitude"]),
+                "longitude": float(_region_attribs["longitude"]),
+            }
+            _children = list(region)
+            for child in _children:
+                _region_attrib[child.tag] = child.text
+            _region_attrib.update(_zone_attrib)
+            regions.append(_region_attrib)
+
+    LOG.debug("get_aqhi_regions(): found %d regions", len(regions))
+
+    return regions
+
+
+async def find_closest_region(language, lat, lon):
+    """Return the AQHI region and site ID of the closest site."""
+    region_list = await get_aqhi_regions(language)
+
+    def site_distance(site):
+        """Calculate distance to a region."""
+        return distance.distance((lat, lon), (site["latitude"], site["longitude"]))
+
+    return min(region_list, key=site_distance)
+
+
+class ECAirQuality:
+    """Get air quality data from Environment Canada."""
+
+    def __init__(self, **kwargs):
+        """Initialize the data object."""
+
+        init_schema = vol.Schema(
+            vol.All(
+                vol.Any(
+                    {
+                        vol.Required("coordinates"): object,
+                        vol.Optional("language"): object,
+                    },
+                    {
+                        vol.Required("zone_id"): object,
+                        vol.Required("region_id"): object,
+                        vol.Optional("language"): object,
+                    },
+                ),
+                {
+                    vol.Optional("zone_id"): vol.In(
+                        ["atl", "ont", "pnr", "pyr", "que"]
+                    ),
+                    vol.Optional("region_id"): vol.All(str, vol.Length(5)),
+                    vol.Optional("coordinates"): (
+                        vol.All(vol.Or(int, float), vol.Range(-90, 90)),
+                        vol.All(vol.Or(int, float), vol.Range(-180, 180)),
+                    ),
+                    vol.Optional("language", default="EN"): vol.In(["EN", "FR"]),
+                },
+            )
+        )
+
+        kwargs = init_schema(kwargs)
+
+        self.language = kwargs["language"]
+
+        if (
+            "zone_id" in kwargs
+            and "region_id" in kwargs
+            and kwargs["zone_id"] is not None
+            and kwargs["region_id"] is not None
+        ):
+            self.zone_id = kwargs["zone_id"]
+            self.region_id = kwargs["region_id"].upper()
+        else:
+            self.zone_id = None
+            self.region_id = None
+            self.coordinates = kwargs["coordinates"]
+
+        self.metadata = MetaData(ATTRIBUTION[self.language])
+        self.region_name = None
+        self.current = None
+        self.current_timestamp = None
+        self.forecasts = dict(daily={}, hourly={})
+
+    async def get_aqhi_data(self, url):
+        async with ClientSession(raise_for_status=True) as session:
+            try:
+                response = await session.get(
+                    url.format(self.zone_id, self.region_id),
+                    headers={"User-Agent": USER_AGENT},
+                    timeout=CLIENT_TIMEOUT,
+                )
+            except Exception:
+                LOG.debug("Retrieving AQHI failed", exc_info=True)
+                return None
+
+            result = await response.read()
+            aqhi_xml = result
+            return et.fromstring(aqhi_xml)
+
+    async def update(self):
+        # Find closest site if not identified
+
+        if not (self.zone_id and self.region_id):
+            closest = await find_closest_region(self.language, *self.coordinates)
+            self.zone_id = closest["abbreviation"]
+            self.region_id = closest["cgndb"]
+            LOG.debug(
+                "update() closest region returned: zone_id '%s' region_id '%s'",
+                self.zone_id,
+                self.region_id,
+            )
+
+        # Fetch current measurement
+        aqhi_current = await self.get_aqhi_data(url=AQHI_OBSERVATION_URL)
+
+        if aqhi_current is not None:
+            # Update region name
+            element = aqhi_current.find("region")
+            self.region_name = element.attrib[f"name{self.language.title()}"]
+            self.metadata.location = self.region_name
+
+            # Update AQHI current condition
+            element = aqhi_current.find("airQualityHealthIndex")
+            if element is not None:
+                self.current = float(element.text)
+            else:
+                self.current = None
+
+            element = aqhi_current.find("./dateStamp/UTCStamp")
+            if element is not None:
+                self.current_timestamp = timestamp_to_datetime(element.text)
+            else:
+                self.current_timestamp = None
+            self.metadata.timestamp = self.current_timestamp
+            LOG.debug(
+                "update(): aqhi_current %d timestamp %s",
+                self.current,
+                self.current_timestamp,
+            )
+
+        # Update AQHI forecasts
+        aqhi_forecast = await self.get_aqhi_data(url=AQHI_FORECAST_URL)
+
+        if aqhi_forecast is not None:
+            # Update AQHI daily forecasts
+            for f in aqhi_forecast.findall("./forecastGroup/forecast"):
+                for p in f.findall("./period"):
+                    if self.language == p.attrib["lang"]:
+                        period = p.attrib["forecastName"]
+                self.forecasts["daily"][period] = int(
+                    f.findtext("./airQualityHealthIndex") or 0
+                )
+
+            # Update AQHI hourly forecasts
+            for f in aqhi_forecast.findall("./hourlyForecastGroup/hourlyForecast"):
+                self.forecasts["hourly"][timestamp_to_datetime(f.attrib["UTCTime"])] = (
+                    int(f.text or 0)
+                )

env_canada/ec_cache.py

@@ -0,0 +1,47 @@
+from datetime import datetime
+from typing import Any, ClassVar
+
+
+class Cache:
+    _cache: ClassVar[dict[str, tuple[datetime, Any]]] = {}
+
+    @classmethod
+    def add(cls, cache_key, item, cache_time):
+        """Add an entry to the cache."""
+
+        cls._cache[cache_key] = (datetime.now() + cache_time, item)
+        return item  # Returning item useful for chaining calls
+
+    @classmethod
+    def get(cls, cache_key):
+        """Get an entry from the cache."""
+
+        # Delete expired entries at start so we don't use expired entries
+        now = datetime.now()
+        expired = [key for key, value in cls._cache.items() if value[0] < now]
+        for key in expired:
+            del cls._cache[key]
+
+        result = cls._cache.get(cache_key)
+        return result[1] if result else None
+
+    @classmethod
+    def clear(cls, prefix: str | None = None) -> int:
+        """Clear cache entries.
+
+        Args:
+            prefix: If provided, only clear entries whose keys start with this prefix.
+                    If None, clear all entries.
+
+        Returns:
+            Number of entries cleared.
+        """
+        if prefix is None:
+            count = len(cls._cache)
+            cls._cache.clear()
+            return count
+
+        keys_to_delete = [key for key in cls._cache if key.startswith(prefix)]
+        for key in keys_to_delete:
+            del cls._cache[key]
+        return len(keys_to_delete)

env_canada/ec_exc.py

@@ -0,0 +1,2 @@
+class UnknownStationId(Exception):
+    """Station ID is unknown"""