env-canada 0.8.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

env_canada/__init__.py

@@ -5,10 +5,11 @@ __all__ = [
     "ECHydro",
     "ECRadar",
     "ECWeather",
+    "ECWeatherUpdateFailed",
 ]
 
 from .ec_aqhi import ECAirQuality
 from .ec_historical import ECHistorical, ECHistoricalRange
 from .ec_hydro import ECHydro
 from .ec_radar import ECRadar
-from .ec_weather import ECWeather
+from .ec_weather import ECWeather, ECWeatherUpdateFailed

env_canada/ec_weather.py

@@ -1,13 +1,19 @@
 import csv
-import datetime
 import logging
 import re
-
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
 import voluptuous as vol
-from aiohttp import ClientSession
-from dateutil import parser, relativedelta, tz
+from aiohttp import (
+    ClientConnectorDNSError,
+    ClientResponseError,
+    ClientSession,
+    ClientTimeout,
+)
+from dateutil import parser, tz
 from geopy import distance
 from lxml import etree as et
+from lxml.etree import _Element
 
 from . import ec_exc
 from .constants import USER_AGENT
@@ -16,6 +22,8 @@ SITE_LIST_URL = "https://dd.weather.gc.ca/citypage_weather/docs/site_list_en.csv
 
 WEATHER_URL = "https://dd.weather.gc.ca/citypage_weather/xml/{}_{}.xml"
 
+CLIENT_TIMEOUT = ClientTimeout(10)
+
 LOG = logging.getLogger(__name__)
 
 ATTRIBUTION = {
@@ -24,7 +32,17 @@ ATTRIBUTION = {
 }
 
 
-__all__ = ["ECWeather"]
+__all__ = ["ECWeather", "ECWeatherUpdateFailed"]
+
+
+@dataclass
+class MetaData:
+    attribution: str
+    timestamp: datetime = datetime(1970, 1, 1, 0, 0, tzinfo=timezone.utc)
+    station: str | None = None
+    location: str | None = None
+    cache_returned_on_update: int = 0  # Resets to 0 after successful update
+    last_update_error: str = ""
 
 
 conditions_meta = {
@@ -179,35 +197,30 @@ summary_meta = {
     "label": {"english": "Forecast", "french": "Prévision"},
 }
 
-alerts_meta = {
-    "warnings": {
-        "english": {"label": "Warnings", "pattern": ".*WARNING((?!ENDED).)*$"},
-        "french": {
-            "label": "Alertes",
-            "pattern": ".*(ALERTE|AVERTISSEMENT)((?!TERMINÉ).)*$",
-        },
-    },
-    "watches": {
-        "english": {"label": "Watches", "pattern": ".*WATCH((?!ENDED).)*$"},
-        "french": {"label": "Veilles", "pattern": ".*VEILLE((?!TERMINÉ).)*$"},
+ALERTS_INIT = {
+    "english": {
+        "warnings": {"label": "Warnings", "value": []},
+        "watches": {"label": "Watches", "value": []},
+        "advisories": {"label": "Advisories", "value": []},
+        "statements": {"label": "Statements", "value": []},
+        "endings": {"label": "Endings", "value": []},
     },
-    "advisories": {
-        "english": {"label": "Advisories", "pattern": ".*ADVISORY((?!ENDED).)*$"},
-        "french": {"label": "Avis", "pattern": ".*AVIS((?!TERMINÉ).)*$"},
-    },
-    "statements": {
-        "english": {"label": "Statements", "pattern": ".*STATEMENT((?!ENDED).)*$"},
-        "french": {"label": "Bulletins", "pattern": ".*BULLETIN((?!TERMINÉ).)*$"},
-    },
-    "endings": {
-        "english": {"label": "Endings", "pattern": ".*ENDED"},
-        "french": {"label": "Terminaisons", "pattern": ".*TERMINÉE?"},
+    "french": {
+        "warnings": {"label": "Alertes", "value": []},
+        "watches": {"label": "Veilles", "value": []},
+        "advisories": {"label": "Avis", "value": []},
+        "statements": {"label": "Bulletins", "value": []},
+        "endings": {"label": "Terminaisons", "value": []},
     },
 }
 
-metadata_meta = {
-    "timestamp": {"xpath": "./dateTime/timeStamp"},
-    "location": {"xpath": "./location/name"},
+# Maps "type" in XML alert attribute to name used
+ALERT_TYPE_TO_NAME = {
+    "advisory": "advisories",
+    "ending": "endings",
+    "statement": "statements",
+    "warning": "warnings",
+    "watch": "watches",
 }
 
 
@@ -220,8 +233,15 @@ def validate_station(station):
     return station
 
 
-def parse_timestamp(t):
-    return parser.parse(t).replace(tzinfo=tz.UTC)
+def _parse_timestamp(time_str: str | None) -> datetime | None:
+    if time_str is not None:
+        return parser.parse(time_str).replace(tzinfo=tz.UTC)
+    return None
+
+
+def _get_xml_text(xml_root: _Element, xpath: str) -> str | None:
+    element = xml_root.find(xpath)
+    return None if element is None or element.text is None else element.text
 
 
 async def get_ec_sites():
@@ -231,7 +251,7 @@ async def get_ec_sites():
 
     async with ClientSession(raise_for_status=True) as session:
         response = await session.get(
-            SITE_LIST_URL, headers={"User-Agent": USER_AGENT}, timeout=10
+            SITE_LIST_URL, headers={"User-Agent": USER_AGENT}, timeout=CLIENT_TIMEOUT
         )
         sites_csv_string = await response.text()
 
@@ -292,7 +312,7 @@ class ECWeather:
 
         self.language = kwargs["language"]
         self.max_data_age = kwargs["max_data_age"]
-        self.metadata = {"attribution": ATTRIBUTION[self.language]}
+        self.metadata = MetaData(ATTRIBUTION[self.language])
         self.conditions = {}
         self.alerts = {}
         self.daily_forecasts = []
@@ -309,9 +329,29 @@ class ECWeather:
             self.lat = kwargs["coordinates"][0]
             self.lon = kwargs["coordinates"][1]
 
-    async def update(self):
+    def handle_error(self, err: Exception | None, msg: str) -> None:
+        """
+        Handle an known error, returning previous results if they have not expired, or
+        raising an exception if previous results have expired. Set the last_update_error
+        to the error no matter what.
+
+        On returning previous results, bump the cache returned counter else clear the counter.
+        """
+        expiry = self.metadata.timestamp + timedelta(hours=self.max_data_age)
+        self.metadata.last_update_error = msg
+        if expiry > datetime.now(timezone.utc):
+            self.metadata.cache_returned_on_update += 1
+            return
+
+        self.metadata.cache_returned_on_update = 0
+        raise ECWeatherUpdateFailed(msg) from err
+
+    async def update(self) -> None:
         """Get the latest data from Environment Canada."""
 
+        # Clear error at start, any error that is handled will set it
+        self.metadata.last_update_error = ""
+
         # Determine station ID or coordinates if not provided
         if not self.site_list:
             self.site_list = await get_ec_sites()
@@ -335,42 +375,43 @@ class ECWeather:
         )
 
         # Get weather data
-        async with ClientSession(raise_for_status=True) as session:
-            response = await session.get(
-                WEATHER_URL.format(self.station_id, self.language[0]),
-                headers={"User-Agent": USER_AGENT},
-                timeout=10,
+        try:
+            async with ClientSession(raise_for_status=True) as session:
+                response = await session.get(
+                    WEATHER_URL.format(self.station_id, self.language[0]),
+                    headers={"User-Agent": USER_AGENT},
+                    timeout=CLIENT_TIMEOUT,
+                )
+                weather_xml = await response.text()
+        except (ClientConnectorDNSError, TimeoutError) as err:
+            return self.handle_error(err, f"Unable to retrieve weather: {err}")
+        except ClientResponseError as err:
+            return self.handle_error(
+                err,
+                f"Unable to retrieve weather '{err.request_info.url}': {err.message} ({err.status})",
             )
-            result = await response.read()
-        weather_xml = result
 
         try:
-            weather_tree = et.fromstring(weather_xml)
+            weather_tree = et.fromstring(bytes(weather_xml, encoding="utf-8"))
         except et.ParseError as err:
-            raise ECWeatherUpdateFailed(
-                "Weather update failed; could not parse result"
-            ) from err
-
-        # Update metadata
-        for m, meta in metadata_meta.items():
-            element = weather_tree.find(meta["xpath"])
-            if element is not None:
-                self.metadata[m] = weather_tree.find(meta["xpath"]).text
-                if m == "timestamp":
-                    self.metadata[m] = parse_timestamp(self.metadata[m])
-            else:
-                self.metadata[m] = None
-
-        # Check data age
-        if self.metadata["timestamp"] is None:
-            raise ECWeatherUpdateFailed("Weather update failed; no timestamp found")
-
-        max_age = datetime.datetime.now(
-            datetime.timezone.utc
-        ) - relativedelta.relativedelta(hours=self.max_data_age)
+            # Parse error happens when data return is malformed (truncated, possibly because of network error)
+            return self.handle_error(
+                err, f"Could not parse retrieved weather; length {len(weather_xml)}"
+            )
 
-        if self.metadata["timestamp"] < max_age:
-            raise ECWeatherUpdateFailed("Weather update failed; outdated data returned")
+        timestamp = _parse_timestamp(
+            _get_xml_text(weather_tree, "./dateTime/timeStamp")
+        )
+        if timestamp is None:
+            return self.handle_error(
+                None, "Timestamp not found in retrieved weather; response ignored"
+            )
+        expiry = timestamp + timedelta(hours=self.max_data_age)
+        if expiry < datetime.now(timezone.utc):
+            return self.handle_error(
+                None,
+                f"Outdated conditions returned from Environment Canada '{timestamp}'; not used",
+            )
 
         # Parse condition
         def get_condition(meta):
@@ -404,21 +445,17 @@ class ECWeather:
                     elif meta["type"] == "str":
                         condition["value"] = element.text
                     elif meta["type"] == "timestamp":
-                        condition["value"] = parse_timestamp(element.text)
+                        condition["value"] = _parse_timestamp(element.text)
 
             return condition
 
         # Update current conditions
-        if len(weather_tree.find("./currentConditions")) > 0:
+        current_conditions = weather_tree.find("./currentConditions")
+        if current_conditions is not None and len(current_conditions) > 0:
             for c, meta in conditions_meta.items():
                 self.conditions[c] = {"label": meta[self.language]}
                 self.conditions[c].update(get_condition(meta))
 
-            # Update station metadata
-            self.metadata["station"] = weather_tree.find(
-                "./currentConditions/station"
-            ).text
-
             # Update text summary
             period = get_condition(summary_meta["forecast_period"])["value"]
             summary = get_condition(summary_meta["text_summary"])["value"]
@@ -429,67 +466,76 @@ class ECWeather:
             }
 
         # Update alerts
-        for category, meta in alerts_meta.items():
-            self.alerts[category] = {"value": [], "label": meta[self.language]["label"]}
-
+        self.alerts = ALERTS_INIT[self.language].copy()
         alert_elements = weather_tree.findall("./warnings/event")
-
-        for a in alert_elements:
-            title = a.attrib.get("description").strip()
-            for category, meta in alerts_meta.items():
-                category_match = re.search(meta[self.language]["pattern"], title)
-                if category_match:
-                    alert = {
-                        "title": title.title(),
-                        "date": a.find("./dateTime[last()]/textSummary").text,
+        for alert in alert_elements:
+            title = alert.attrib.get("description")
+            type_ = alert.attrib.get("type")
+            if title is not None and type_ is not None and type_ in ALERT_TYPE_TO_NAME:
+                self.alerts[ALERT_TYPE_TO_NAME[type_]]["value"].append(  # type: ignore[attr-defined]
+                    {
+                        "title": title.strip().title(),
+                        "date": _get_xml_text(alert, "./dateTime[last()]/textSummary"),
                     }
-                    self.alerts[category]["value"].append(alert)
+                )
 
         # Update forecasts
-        self.forecast_time = parse_timestamp(
-            weather_tree.findtext("./forecastGroup/dateTime/timeStamp")
+        self.forecast_time = _parse_timestamp(
+            _get_xml_text(weather_tree, "./forecastGroup/dateTime/timeStamp")
         )
         self.daily_forecasts = []
         self.hourly_forecasts = []
 
         # Update daily forecasts
-        forecast_time = self.forecast_time
-        for f in weather_tree.findall("./forecastGroup/forecast"):
-            self.daily_forecasts.append(
-                {
-                    "period": f.findtext("period"),
-                    "text_summary": f.findtext("textSummary"),
-                    "icon_code": f.findtext("./abbreviatedForecast/iconCode"),
-                    "temperature": int(f.findtext("./temperatures/temperature") or 0),
-                    "temperature_class": f.find(
-                        "./temperatures/temperature"
-                    ).attrib.get("class"),
-                    "precip_probability": int(
-                        f.findtext("./abbreviatedForecast/pop") or "0"
-                    ),
-                    "timestamp": forecast_time,
-                }
-            )
-            if self.daily_forecasts[-1]["temperature_class"] == "low":
-                forecast_time = forecast_time + datetime.timedelta(days=1)
+        if self.forecast_time is not None:
+            forecast_time = self.forecast_time
+            for f in weather_tree.findall("./forecastGroup/forecast"):
+                temperature_element = f.find("./temperatures/temperature")
+                self.daily_forecasts.append(
+                    {
+                        "period": f.findtext("period"),
+                        "text_summary": f.findtext("textSummary"),
+                        "icon_code": f.findtext("./abbreviatedForecast/iconCode"),
+                        "temperature": int(
+                            f.findtext("./temperatures/temperature") or 0
+                        ),
+                        "temperature_class": temperature_element.attrib.get("class")
+                        if temperature_element is not None
+                        else None,
+                        "precip_probability": int(
+                            f.findtext("./abbreviatedForecast/pop") or "0"
+                        ),
+                        "timestamp": forecast_time,
+                    }
+                )
+                if self.daily_forecasts[-1]["temperature_class"] == "low":
+                    forecast_time = forecast_time + timedelta(days=1)
 
         # Update hourly forecasts
         for f in weather_tree.findall("./hourlyForecastGroup/hourlyForecast"):
             wind_speed_text = f.findtext("./wind/speed")
             self.hourly_forecasts.append(
                 {
-                    "period": parse_timestamp(f.attrib.get("dateTimeUTC")),
+                    "period": _parse_timestamp(f.attrib.get("dateTimeUTC")),
                     "condition": f.findtext("./condition"),
                     "temperature": int(f.findtext("./temperature") or 0),
                     "icon_code": f.findtext("./iconCode"),
                     "precip_probability": int(f.findtext("./lop") or "0"),
-                    "wind_speed": int(
-                        wind_speed_text if wind_speed_text.isnumeric() else 0
-                    ),
+                    "wind_speed": int(wind_speed_text)
+                    if wind_speed_text and wind_speed_text.isnumeric()
+                    else 0,
                     "wind_direction": f.findtext("./wind/direction"),
                 }
             )
 
+        # Update metadata at the end
+        self.metadata.cache_returned_on_update = 0
+        self.metadata.timestamp = timestamp
+        self.metadata.location = _get_xml_text(weather_tree, "./location/name")
+        self.metadata.station = _get_xml_text(
+            weather_tree, "./currentConditions/station"
+        )
+
 
 class ECWeatherUpdateFailed(Exception):
     """Raised when an update fails to get usable data."""

{env_canada-0.8.0.dist-info → env_canada-0.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: env_canada
-Version: 0.8.0
+Version: 0.9.0
 Summary: A package to access meteorological data from Environment Canada
 Author-email: Michael Davie <michael.davie@gmail.com>
 Maintainer-email: Michael Davie <michael.davie@gmail.com>
@@ -27,25 +27,24 @@ License: Copyright (c) 2018 The Python Packaging Authority
 Project-URL: Homepage, https://github.com/michaeldavie/env_canada
 Project-URL: Documentation, https://github.com/michaeldavie/env_canada
 Project-URL: Repository, https://github.com/michaeldavie/env_canada
-Project-URL: Bug Tracker, https://github.com/michaeldavie/env_canada/issues
+Project-URL: Issues, https://github.com/michaeldavie/env_canada/issues
 Project-URL: Changelog, https://github.com/michaeldavie/env_canada/blob/master/CHANGELOG.md
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aiohttp>=3.9.0
-Requires-Dist: geopy
+Requires-Dist: geopy>=2.4.1
 Requires-Dist: imageio>=2.28.0
-Requires-Dist: lxml
+Requires-Dist: lxml>=5.3.0
 Requires-Dist: numpy>=1.22.2
-Requires-Dist: pandas>=1.3.0
+Requires-Dist: pandas>=2.2.3
 Requires-Dist: Pillow>=10.0.1
-Requires-Dist: python-dateutil
-Requires-Dist: voluptuous
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
+Requires-Dist: python-dateutil>=2.9
+Requires-Dist: voluptuous>=0.15.2
+Dynamic: license-file
 
 # Environment Canada (env_canada)
 

{env_canada-0.8.0.dist-info → env_canada-0.9.0.dist-info}/RECORD

@@ -1,6 +1,6 @@
 env_canada/10x20.pbm,sha256=ClKTs2WUmhUhTHAQzPuGwPTICGVBzCvos5l-vHRBE5M,2463
 env_canada/10x20.pil,sha256=Oki6-TD7b0xFtfm6vxCKsmpEpsZ5Jaia_0v_aDz8bfE,5143
-env_canada/__init__.py,sha256=Qqtu4qEY1gvzPF4D0qzi8kVvtYUizJDzQk5FZVqoo38,314
+env_canada/__init__.py,sha256=O1KVC2GAPTmxAP46FXo9jd8Tq3YMefViowGjuxJ5JJM,366
 env_canada/constants.py,sha256=RHa-Hp2H6XroFE9Z5-H0MIUPWlFXUVKmWEidwuWzakE,32
 env_canada/ec_aqhi.py,sha256=-N4XLLgApaWZvtepJvS2lvqDSNjwV2X_fkmbtKQv8rA,7741
 env_canada/ec_cache.py,sha256=zb3n79ul7hUTE0IohDfZbRBLY-siOHPjYzWldMbuPVk,798
@@ -8,9 +8,9 @@ env_canada/ec_exc.py,sha256=SBJwzmLf94lTx7KYVLfQYrMXYNYUoIxeVXc-BLkuXoE,67
 env_canada/ec_historical.py,sha256=qMr4RE6vfNiNa_zFolQ0PQGraok8bQtIVjs_o6sJKD4,16276
 env_canada/ec_hydro.py,sha256=JoBe-QVV8GEeZXCNFscIs2R_spgkbxCZpLt7tL6-NUI,4889
 env_canada/ec_radar.py,sha256=0SKusJWDTFODdn3D9yrhlkOS-Bv9hhBJM9EBh8TNRlk,12965
-env_canada/ec_weather.py,sha256=PSgb67PODo8Lv7A7O01q97SjvHCK0lwpcDtqTa70GI8,17048
-env_canada-0.8.0.dist-info/LICENSE,sha256=BkgGIGgy9sv-OsI7mRi9dIQ3Su0m4IbjpZlfxv8oBbM,1073
-env_canada-0.8.0.dist-info/METADATA,sha256=U548dMi4w3eX8MqFQrQseJthoggUFfC_a1AefMYjemA,12723
-env_canada-0.8.0.dist-info/WHEEL,sha256=A3WOREP4zgxI0fKrHUG8DC8013e3dK3n7a6HDbcEIwE,91
-env_canada-0.8.0.dist-info/top_level.txt,sha256=fw7Pcl9ULBXYvqnAdyBdmwPXW8GSRFmhO0sLZWVfOCc,11
-env_canada-0.8.0.dist-info/RECORD,,
+env_canada/ec_weather.py,sha256=l-gyXePkHBLW9vidFgiPEm81xevbZCeBKzKDLiLr7Y8,19200
+env_canada-0.9.0.dist-info/licenses/LICENSE,sha256=BkgGIGgy9sv-OsI7mRi9dIQ3Su0m4IbjpZlfxv8oBbM,1073
+env_canada-0.9.0.dist-info/METADATA,sha256=divVpZpbuU3Ch7_l1hno2So0e3ePrPoDr9nLOg9_8To,12709
+env_canada-0.9.0.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+env_canada-0.9.0.dist-info/top_level.txt,sha256=fw7Pcl9ULBXYvqnAdyBdmwPXW8GSRFmhO0sLZWVfOCc,11
+env_canada-0.9.0.dist-info/RECORD,,

{env_canada-0.8.0.dist-info → env_canada-0.9.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.7.0)
+Generator: setuptools (78.1.0)
 Root-Is-Purelib: true
 Tag: py3-none-any