env-canada 0.10.1__tar.gz → 0.11.0__tar.gz

{env_canada-0.10.1/env_canada.egg-info → env_canada-0.11.0}/PKG-INFO

@@ -1,36 +1,16 @@
 Metadata-Version: 2.4
 Name: env_canada
-Version: 0.10.1
+Version: 0.11.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>
-License: Copyright (c) 2018 The Python Packaging Authority
-        
-        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
-        
+License-Expression: MIT
 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: 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.11
 Description-Content-Type: text/markdown
@@ -69,31 +49,45 @@ This package provides access to various data sources published by [Environment a
 
 ## Weather Observations and Forecasts
 
-`ECWeather` provides current conditions and forecasts. It automatically determines which weather station to use based on latitude/longitude provided. It is also possible to specify a specific station code of the form `AB/s0000123` based on those listed in [this CSV file](https://dd.weather.gc.ca/citypage_weather/docs/site_list_towns_en.csv). For example:
+`ECWeather` provides current conditions and forecasts. It automatically determines which weather station to use based on latitude/longitude provided. It is also possible to specify a station code in multiple flexible formats:
+
+- **Full format**: `"AB/s0000123"` (province code and full station ID)
+- **Station ID only**: `"s0000123"` (station ID without province - province is resolved automatically)
+- **Numeric only**: `"123"` (just the station number - province is resolved automatically)
+
+Station codes are based on those listed in [this CSV file](https://dd.weather.gc.ca/citypage_weather/docs/site_list_towns_en.csv). For example:
 
 ```python
 import asyncio
 
 from env_canada import ECWeather
 
-ec_en = ECWeather(coordinates=(50, -100))
-ec_fr = ECWeather(station_id="ON/s0000430", language="french")
+# Using coordinates (automatic station selection)
+ec_coords = ECWeather(coordinates=(50, -100))
+
+# Using station ID - multiple formats supported:
+ec_full = ECWeather(station_id="ON/s0000430", language="french")  # Full format
+ec_station = ECWeather(station_id="s0000430")  # Station ID only
+ec_numeric = ECWeather(station_id="430")  # Numeric only
 
-asyncio.run(ec_en.update())
+asyncio.run(ec_coords.update())
 
 # current conditions
-ec_en.conditions
+ec_coords.conditions
 
 # daily forecasts
-ec_en.daily_forecasts
+ec_coords.daily_forecasts
 
 # hourly forecasts
-ec_en.hourly_forecasts
+ec_coords.hourly_forecasts
 
 # alerts
-ec_en.alerts
+ec_coords.alerts
 ```
 
+> [!NOTE]
+> As of version 0.11.0, `ECWeather` automatically handles Environment Canada's new timestamped weather file URL structure (effective June 2025). The library dynamically discovers the most recent weather files, ensuring continued functionality during Environment Canada's infrastructure changes.
+
 ## Weather Radar
 
 `ECRadar` provides Environment Canada meteorological [radar imagery](https://weather.gc.ca/radar/index_e.html).
@@ -110,6 +104,55 @@ animated_gif = asyncio.run(radar_coords.get_loop())
 latest_png = asyncio.run(radar_coords.get_latest_frame())
 ```
 
+## Weather Maps
+
+`ECMap` provides Environment Canada WMS weather map imagery with support for various meteorological layers.
+
+```python
+import asyncio
+
+from env_canada import ECMap
+
+# Create a map with rain radar layer
+map_coords = ECMap(coordinates=(50, -100), layer="rain")
+
+# Get the latest image with the specified layer
+latest_png = asyncio.run(map_coords.get_latest_frame())
+
+# Get an animated GIF with the specified layer
+animated_gif = asyncio.run(map_coords.get_loop())
+
+# Customize the map appearance
+custom_map = ECMap(
+    coordinates=(50, -100),
+    layer="snow",
+    width=1200,
+    height=800,
+    radius=300,
+    layer_opacity=80,
+    legend=True,
+    timestamp=True,
+    language="french",
+)
+```
+
+Available layers include:
+
+- `rain`: Precipitation rain radar
+- `snow`: Precipitation snow radar
+- `precip_type`: Surface precipitation type
+
+Additional configuration options:
+
+- `width`/`height`: Image dimensions (default: 800x800)
+- `radius`: Map radius in km around coordinates (default: 200km)
+- `layer_opacity`: Layer transparency 0-100% (default: 65%)
+- `legend`: Show legend (default: True)
+- `timestamp`: Show timestamp (default: True)
+- `language`: "english" or "french" (default: "english")
+
+> **Note**: ECMap automatically discovers available legend styles from Environment Canada's WMS capabilities, ensuring compatibility with any future style changes.
+
 ## Air Quality Health Index (AQHI)
 
 `ECAirQuality` provides Environment Canada [air quality](https://weather.gc.ca/airquality/pages/index_e.html) data.

{env_canada-0.10.1 → env_canada-0.11.0}/README.md

@@ -21,31 +21,45 @@ This package provides access to various data sources published by [Environment a
 
 ## Weather Observations and Forecasts
 
-`ECWeather` provides current conditions and forecasts. It automatically determines which weather station to use based on latitude/longitude provided. It is also possible to specify a specific station code of the form `AB/s0000123` based on those listed in [this CSV file](https://dd.weather.gc.ca/citypage_weather/docs/site_list_towns_en.csv). For example:
+`ECWeather` provides current conditions and forecasts. It automatically determines which weather station to use based on latitude/longitude provided. It is also possible to specify a station code in multiple flexible formats:
+
+- **Full format**: `"AB/s0000123"` (province code and full station ID)
+- **Station ID only**: `"s0000123"` (station ID without province - province is resolved automatically)
+- **Numeric only**: `"123"` (just the station number - province is resolved automatically)
+
+Station codes are based on those listed in [this CSV file](https://dd.weather.gc.ca/citypage_weather/docs/site_list_towns_en.csv). For example:
 
 ```python
 import asyncio
 
 from env_canada import ECWeather
 
-ec_en = ECWeather(coordinates=(50, -100))
-ec_fr = ECWeather(station_id="ON/s0000430", language="french")
+# Using coordinates (automatic station selection)
+ec_coords = ECWeather(coordinates=(50, -100))
+
+# Using station ID - multiple formats supported:
+ec_full = ECWeather(station_id="ON/s0000430", language="french")  # Full format
+ec_station = ECWeather(station_id="s0000430")  # Station ID only
+ec_numeric = ECWeather(station_id="430")  # Numeric only
 
-asyncio.run(ec_en.update())
+asyncio.run(ec_coords.update())
 
 # current conditions
-ec_en.conditions
+ec_coords.conditions
 
 # daily forecasts
-ec_en.daily_forecasts
+ec_coords.daily_forecasts
 
 # hourly forecasts
-ec_en.hourly_forecasts
+ec_coords.hourly_forecasts
 
 # alerts
-ec_en.alerts
+ec_coords.alerts
 ```
 
+> [!NOTE]
+> As of version 0.11.0, `ECWeather` automatically handles Environment Canada's new timestamped weather file URL structure (effective June 2025). The library dynamically discovers the most recent weather files, ensuring continued functionality during Environment Canada's infrastructure changes.
+
 ## Weather Radar
 
 `ECRadar` provides Environment Canada meteorological [radar imagery](https://weather.gc.ca/radar/index_e.html).
@@ -62,6 +76,55 @@ animated_gif = asyncio.run(radar_coords.get_loop())
 latest_png = asyncio.run(radar_coords.get_latest_frame())
 ```
 
+## Weather Maps
+
+`ECMap` provides Environment Canada WMS weather map imagery with support for various meteorological layers.
+
+```python
+import asyncio
+
+from env_canada import ECMap
+
+# Create a map with rain radar layer
+map_coords = ECMap(coordinates=(50, -100), layer="rain")
+
+# Get the latest image with the specified layer
+latest_png = asyncio.run(map_coords.get_latest_frame())
+
+# Get an animated GIF with the specified layer
+animated_gif = asyncio.run(map_coords.get_loop())
+
+# Customize the map appearance
+custom_map = ECMap(
+    coordinates=(50, -100),
+    layer="snow",
+    width=1200,
+    height=800,
+    radius=300,
+    layer_opacity=80,
+    legend=True,
+    timestamp=True,
+    language="french",
+)
+```
+
+Available layers include:
+
+- `rain`: Precipitation rain radar
+- `snow`: Precipitation snow radar
+- `precip_type`: Surface precipitation type
+
+Additional configuration options:
+
+- `width`/`height`: Image dimensions (default: 800x800)
+- `radius`: Map radius in km around coordinates (default: 200km)
+- `layer_opacity`: Layer transparency 0-100% (default: 65%)
+- `legend`: Show legend (default: True)
+- `timestamp`: Show timestamp (default: True)
+- `language`: "english" or "french" (default: "english")
+
+> **Note**: ECMap automatically discovers available legend styles from Environment Canada's WMS capabilities, ensuring compatibility with any future style changes.
+
 ## Air Quality Health Index (AQHI)
 
 `ECAirQuality` provides Environment Canada [air quality](https://weather.gc.ca/airquality/pages/index_e.html) data.

{env_canada-0.10.1 → env_canada-0.11.0}/env_canada/__init__.py

@@ -3,6 +3,7 @@ __all__ = [
     "ECHistorical",
     "ECHistoricalRange",
     "ECHydro",
+    "ECMap",
     "ECRadar",
     "ECWeather",
     "ECWeatherUpdateFailed",
@@ -12,4 +13,5 @@ from .ec_aqhi import ECAirQuality
 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-0.11.0/env_canada/constants.py

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

env_canada-0.10.1/env_canada/ec_radar.py → env_canada-0.11.0/env_canada/ec_map.py

@@ -2,9 +2,8 @@ import asyncio
 import logging
 import math
 import os
-from datetime import date, timedelta
+from datetime import timedelta
 from io import BytesIO
-from typing import cast
 
 import dateutil.parser
 import voluptuous as vol
@@ -16,12 +15,14 @@ from PIL import Image, ImageDraw, ImageFont
 from .constants import USER_AGENT
 from .ec_cache import Cache
 
+LOG = logging.getLogger(__name__)
+
 ATTRIBUTION = {
     "english": "Data provided by Environment Canada",
     "french": "Données fournies par Environnement Canada",
 }
 
-__all__ = ["ECRadar"]
+__all__ = ["ECMap"]
 
 # Natural Resources Canada
 
@@ -36,17 +37,17 @@ basemap_params = {
     "format": "image/png",
 }
 
-# Mapbox Proxy
-
-backup_map_url = (
-    "https://0wmiyoko9f.execute-api.ca-central-1.amazonaws.com/mapbox-proxy"
-)
 
 # Environment Canada
 
-precip_layers = {"rain": "RADAR_1KM_RRAI", "snow": "RADAR_1KM_RSNO"}
+# Common WMS layers available from Environment Canada
+
+wms_layers = {
+    "rain": "RADAR_1KM_RRAI",
+    "snow": "RADAR_1KM_RSNO",
+    "precip_type": "Radar_1km_SfcPrecipType",
+}
 
-legend_style = {"rain": "RADARURPPRECIPR", "snow": "RADARURPPRECIPS14"}
 
 geomet_url = "https://geo.weather.gc.ca/geomet"
 capabilities_params = {
@@ -57,12 +58,13 @@ capabilities_params = {
 }
 wms_namespace = {"wms": "http://www.opengis.net/wms"}
 dimension_xpath = './/wms:Layer[wms:Name="{layer}"]/wms:Dimension'
-radar_params = {
+map_params = {
     "service": "WMS",
     "version": "1.3.0",
     "request": "GetMap",
     "crs": "EPSG:4326",
     "format": "image/png",
+    "transparent": "true",
 }
 legend_params = {
     "service": "WMS",
@@ -71,11 +73,12 @@ legend_params = {
     "sld_version": "1.1.0",
     "format": "image/png",
 }
-radar_interval = timedelta(minutes=6)
+image_interval = timedelta(minutes=6)
 
 timestamp_label = {
     "rain": {"english": "Rain", "french": "Pluie"},
     "snow": {"english": "Snow", "french": "Neige"},
+    "precip_type": {"english": "Precipitation", "french": "Précipitation"},
 }
 
 
@@ -114,9 +117,9 @@ async def _get_resource(url, params, bytes=True):
         return await response.text()
 
 
-class ECRadar:
+class ECMap:
     def __init__(self, **kwargs):
-        """Initialize the radar object."""
+        """Initialize the map object."""
 
         init_schema = vol.Schema(
             {
@@ -129,12 +132,10 @@ class ECRadar:
                 vol.Required("height", default=800): vol.All(int, vol.Range(min=10)),
                 vol.Required("legend", default=True): bool,
                 vol.Required("timestamp", default=True): bool,
-                vol.Required("radar_opacity", default=65): vol.All(
+                vol.Required("layer_opacity", default=65): vol.All(
                     int, vol.Range(0, 100)
                 ),
-                vol.Optional("precip_type"): vol.Any(
-                    None, vol.In(["rain", "snow", "auto"])
-                ),
+                vol.Required("layer", default="rain"): vol.In(wms_layers.keys()),
                 vol.Optional("language", default="english"): vol.In(
                     ["english", "french"]
                 ),
@@ -145,8 +146,8 @@ class ECRadar:
         self.language = kwargs["language"]
         self.metadata = {"attribution": ATTRIBUTION[self.language]}
 
-        self._precip_type_setting = kwargs.get("precip_type")
-        self._precip_type_actual = self.precip_type[1]
+        # Get layer
+        self.layer = kwargs["layer"]
 
         # Get map parameters
         self.image = None
@@ -158,30 +159,14 @@ class ECRadar:
             "width": self.width,
             "height": self.height,
         }
-        self.radar_opacity = kwargs["radar_opacity"]
+        self.layer_opacity = kwargs["layer_opacity"]
 
         # Get overlay parameters
         self.show_legend = kwargs["legend"]
         self.show_timestamp = kwargs["timestamp"]
 
         self._font = None
-
-    @property
-    def precip_type(self):
-        # NOTE: this is a breaking change for this lib; HA doesn't use this so not breaking for that
-        if self._precip_type_setting in ["rain", "snow"]:
-            return (self._precip_type_setting, self._precip_type_setting)
-        self._precip_type_actual = (
-            "rain" if date.today().month in range(4, 11) else "snow"
-        )
-        return ("auto", self._precip_type_actual)
-
-    @precip_type.setter
-    def precip_type(self, user_input):
-        if user_input not in ["rain", "snow", "auto"]:
-            raise ValueError("precip_type must be 'rain', 'snow', or 'auto'")
-        self._precip_type_setting = user_input
-        self._precip_type_actual = self.precip_type[1]
+        self.timestamp = None
 
     async def _get_basemap(self):
         """Fetch the background map image."""
@@ -189,25 +174,63 @@ class ECRadar:
             return base_bytes
 
         basemap_params.update(self.map_params)
-        for map_url in [basemap_url, backup_map_url]:
-            try:
-                base_bytes = await _get_resource(map_url, basemap_params)
-                return Cache.add("basemap", base_bytes, timedelta(days=7))
+        try:
+            base_bytes = await _get_resource(basemap_url, basemap_params)
+            return Cache.add("basemap", base_bytes, timedelta(days=7))
+        except ClientConnectorError as e:
+            LOG.warning("Map from %s could not be retrieved: %s", basemap_url, e)
+            return None
+
+    async def _get_style_for_layer(self):
+        """Extract the appropriate style name from capabilities XML."""
+        capabilities_cache_key = f"capabilities-{self.layer}"
+
+        if not (capabilities_xml := Cache.get(capabilities_cache_key)):
+            capabilities_params["layer"] = wms_layers[self.layer]
+            capabilities_xml = await _get_resource(
+                geomet_url, capabilities_params, bytes=True
+            )
+            Cache.add(capabilities_cache_key, capabilities_xml, timedelta(minutes=5))
 
-            except ClientConnectorError as e:
-                logging.warning("Map from %s could not be retrieved: %s", map_url, e)
+        # Parse for style information
+        root = et.fromstring(capabilities_xml)
+        layer_xpath = f'.//wms:Layer[wms:Name="{wms_layers[self.layer]}"]/wms:Style'
+
+        styles = root.findall(layer_xpath, namespaces=wms_namespace)
+        if styles:
+            # Choose style based on language preference
+            for style in styles:
+                style_name = style.find("wms:Name", namespaces=wms_namespace)
+                if style_name is not None:
+                    name = style_name.text
+                    # Prefer language-specific style if available
+                    if self.language == "french" and name.endswith("_Fr"):
+                        return name
+                    elif self.language == "english" and not name.endswith("_Fr"):
+                        return name
+
+            # Fallback to first available style
+            first_style = styles[0].find("wms:Name", namespaces=wms_namespace)
+            if first_style is not None:
+                return first_style.text
+
+        # If no styles found, raise an error
+        raise ValueError(f"No styles found for layer {self.layer}")
 
     async def _get_legend(self):
-        """Fetch legend image."""
+        """Fetch legend image for the layer."""
 
-        legend_cache_key = f"legend-{self._precip_type_actual}"
+        legend_cache_key = f"legend-{self.layer}"
         if legend := Cache.get(legend_cache_key):
             return legend
 
+        # Dynamically determine style
+        style_name = await self._get_style_for_layer()
+
         legend_params.update(
             dict(
-                layer=precip_layers[self._precip_type_actual],
-                style=legend_style[self._precip_type_actual],
+                layer=wms_layers[self.layer],
+                style=style_name,
             )
         )
         try:
@@ -215,23 +238,23 @@ class ECRadar:
             return Cache.add(legend_cache_key, legend, timedelta(days=7))
 
         except ClientConnectorError:
-            logging.warning("Legend could not be retrieved")
+            LOG.warning("Legend could not be retrieved")
             return None
 
     async def _get_dimensions(self):
-        """Get time range of available radar images."""
+        """Get time range of available images for the layer."""
 
-        capabilities_cache_key = f"capabilities-{self._precip_type_actual}"
+        capabilities_cache_key = f"capabilities-{self.layer}"
 
         if not (capabilities_xml := Cache.get(capabilities_cache_key)):
-            capabilities_params["layer"] = precip_layers[self._precip_type_actual]
+            capabilities_params["layer"] = wms_layers[self.layer]
             capabilities_xml = await _get_resource(
                 geomet_url, capabilities_params, bytes=True
             )
             Cache.add(capabilities_cache_key, capabilities_xml, timedelta(minutes=5))
 
         dimension_string = et.fromstring(capabilities_xml).find(
-            dimension_xpath.format(layer=precip_layers[self._precip_type_actual]),
+            dimension_xpath.format(layer=wms_layers[self.layer]),
             namespaces=wms_namespace,
         )
         if dimension_string is not None:
@@ -243,39 +266,65 @@ class ECRadar:
                 return (start, end)
         return None
 
-    async def _get_radar_image(self, frame_time):
+    async def _get_layer_image(self, frame_time):
+        """Fetch image for the layer at a specific time."""
+        time = frame_time.strftime("%Y-%m-%dT%H:%M:00Z")
+        layer_cache_key = f"layer-{self.layer}-{time}"
+
+        if img := Cache.get(layer_cache_key):
+            return img
+
+        params = dict(
+            **map_params,
+            **self.map_params,
+            layers=wms_layers[self.layer],
+            time=time,
+        )
+
+        try:
+            layer_bytes = await _get_resource(geomet_url, params)
+            return Cache.add(layer_cache_key, layer_bytes, timedelta(minutes=200))
+        except ClientConnectorError:
+            LOG.warning("Layer could not be retrieved")
+            return None
+
+    async def _create_composite_image(self, frame_time):
+        """Create a composite image from the layer."""
+
         def _create_image():
             """Contains all the PIL calls; run in another thread."""
 
-            radar_image = Image.open(BytesIO(cast(bytes, radar_bytes))).convert("RGBA")
-
-            map_image = None
+            # Start with the basemap if available
             if base_bytes:
-                map_image = Image.open(BytesIO(base_bytes)).convert("RGBA")
-
-            if legend_bytes:
-                legend_image = Image.open(BytesIO(legend_bytes)).convert("RGB")
-                legend_position = (self.width - legend_image.size[0], 0)
+                composite = Image.open(BytesIO(base_bytes)).convert("RGBA")
             else:
-                legend_image = None
-                legend_position = None
-
-            # Add transparency to radar
-            if self.radar_opacity < 100:
-                alpha = round((self.radar_opacity / 100) * 255)
-                radar_copy = radar_image.copy()
-                radar_copy.putalpha(alpha)
-                radar_image.paste(radar_copy, radar_image)
-
-            # Overlay radar on basemap
-            if map_image:
-                frame = Image.alpha_composite(map_image, radar_image)
-            else:
-                frame = radar_image
+                # Create a blank image if no basemap
+                composite = Image.new(
+                    "RGBA", (self.width, self.height), (255, 255, 255, 255)
+                )
+
+            # Add the layer with transparency
+            if layer_bytes:
+                layer_image = Image.open(BytesIO(layer_bytes)).convert("RGBA")
+
+                # Add transparency to layer
+                if self.layer_opacity < 100:
+                    alpha = round((self.layer_opacity / 100) * 255)
+                    layer_copy = layer_image.copy()
+                    layer_copy.putalpha(alpha)
+                    layer_image.paste(layer_copy, layer_image)
+
+                # Composite the layer onto the image
+                composite = Image.alpha_composite(composite, layer_image)
 
             # Add legend
-            if legend_image:
-                frame.paste(legend_image, legend_position)
+            if legend_bytes:
+                legend_image = Image.open(BytesIO(legend_bytes)).convert("RGB")
+                legend_position = (
+                    self.width - legend_image.size[0],
+                    0,
+                )
+                composite.paste(legend_image, legend_position)
 
             # Add timestamp
             if self.show_timestamp:
@@ -285,8 +334,16 @@ class ECRadar:
                     )
 
                 if self._font:
-                    label = timestamp_label[self._precip_type_actual][self.language]
-                    timestamp = f"{label} @ {frame_time.astimezone().strftime('%H:%M')}"
+                    # Create a timestamp with the layer
+                    if self.layer in timestamp_label:
+                        layer_text = timestamp_label[self.layer][self.language]
+                    else:
+                        layer_text = self.layer
+
+                    timestamp = (
+                        f"{layer_text} @ {frame_time.astimezone().strftime('%H:%M')}"
+                    )
+
                     text_box = Image.new(
                         "RGBA", self._font.getbbox(timestamp)[2:], "white"
                     )
@@ -297,52 +354,54 @@ class ECRadar:
                     double_box = text_box.resize(
                         (text_box.width * 2, text_box.height * 2)
                     )
-                    frame.paste(double_box)
-                    frame = frame.quantize()
+                    composite.paste(double_box)
+                    composite = composite.quantize()
 
             # Convert frame to PNG for return
             img_byte_arr = BytesIO()
-            frame.save(img_byte_arr, format="PNG")
+            composite.save(img_byte_arr, format="PNG")
 
-            # Time is tuned for 3h radar image
             return Cache.add(
-                f"radar-{time}", img_byte_arr.getvalue(), timedelta(minutes=200)
+                f"composite-{time}", img_byte_arr.getvalue(), timedelta(minutes=200)
             )
 
         time = frame_time.strftime("%Y-%m-%dT%H:%M:00Z")
+        cache_key = f"composite-{time}"
 
-        if img := Cache.get(f"radar-{time}"):
+        if img := Cache.get(cache_key):
             return img
 
+        # Get the basemap
         base_bytes = await self._get_basemap()
-        legend_bytes = await self._get_legend() if self.show_legend else None
 
-        params = dict(
-            **radar_params,
-            **self.map_params,
-            layers=precip_layers[self._precip_type_actual],
-            time=time,
-        )
-        radar_bytes = await _get_resource(geomet_url, params)
+        # Get the layer image and legend
+        layer_bytes = await self._get_layer_image(frame_time)
+        legend_bytes = None
+        if self.show_legend:
+            legend_bytes = await self._get_legend()
+
         return await asyncio.get_event_loop().run_in_executor(None, _create_image)
 
     async def get_latest_frame(self):
-        """Get the latest image from Environment Canada."""
+        """Get the latest image with the specified layer."""
         dimensions = await self._get_dimensions()
         if not dimensions:
             return None
-        return await self._get_radar_image(frame_time=dimensions[1])
+
+        return await self._create_composite_image(frame_time=dimensions[1])
 
     async def update(self):
         self.image = await self.get_loop()
 
     async def get_loop(self, fps=5):
-        """Build an animated GIF of recent radar images."""
+        """Build an animated GIF of recent images with the specified layer."""
 
         def create_gif():
             """Assemble animated GIF."""
             duration = 1000 / fps
-            imgs = [Image.open(BytesIO(img)).convert("RGBA") for img in radar_layers]
+            imgs = [
+                Image.open(BytesIO(img)).convert("RGBA") for img in composite_frames
+            ]
             gif = BytesIO()
             imgs[0].save(
                 gif,
@@ -355,23 +414,26 @@ class ECRadar:
             return gif.getvalue()
 
         # Without this cache priming the tasks below each compete to load map/legend
-        # at the same time, resulting in them getting retrieved for each radar image.
+        # at the same time, resulting in them getting retrieved for each image.
         await self._get_basemap()
-        await self._get_legend() if self.show_legend else None
+        if self.show_legend:
+            await self._get_legend()
 
+        # Use the layer to determine the time dimensions
         timespan = await self._get_dimensions()
         if not timespan:
-            logging.error("Cannot retrieve radar times.")
+            LOG.error("Cannot retrieve image times.")
             return None
 
         tasks = []
         curr = timespan[0]
         while curr <= timespan[1]:
-            tasks.append(self._get_radar_image(frame_time=curr))
-            curr = curr + radar_interval
-        radar_layers = await asyncio.gather(*tasks)
+            tasks.append(self._create_composite_image(frame_time=curr))
+            curr = curr + image_interval
+        composite_frames = await asyncio.gather(*tasks)
 
+        # Repeat the last frame 3 times to make it pause at the end
         for _ in range(3):
-            radar_layers.append(radar_layers[-1])
+            composite_frames.append(composite_frames[-1])
 
         return await asyncio.get_running_loop().run_in_executor(None, create_gif)

env_canada-0.11.0/env_canada/ec_radar.py

@@ -0,0 +1,95 @@
+from datetime import date
+
+from .ec_map import ECMap
+
+__all__ = ["ECRadar"]
+
+
+class ECRadar:
+    def __init__(self, **kwargs):
+        """Initialize the radar object."""
+
+        # Extract ECRadar-specific parameters
+        precip_type = kwargs.pop("precip_type", None)
+        radar_opacity = kwargs.pop("radar_opacity", 65)
+
+        # Rename radar_opacity to layer_opacity for ECMap
+        kwargs["layer_opacity"] = radar_opacity
+
+        # Set up precip type logic
+        self._precip_type_setting = precip_type
+        self._precip_type_actual = self.precip_type[1]
+
+        # Map the actual precipitation type to the layer
+        kwargs["layer"] = self._precip_type_actual
+
+        # Create the underlying ECMap instance
+        self._map = ECMap(**kwargs)
+
+        # Expose common properties for backward compatibility
+        self.language = self._map.language
+        self.metadata = self._map.metadata
+        self.image = self._map.image
+        self.width = self._map.width
+        self.height = self._map.height
+        self.bbox = self._map.bbox
+        self.map_params = self._map.map_params
+        self.show_legend = self._map.show_legend
+        self.show_timestamp = self._map.show_timestamp
+        self.timestamp = getattr(self._map, "timestamp", None)
+
+    @property
+    def precip_type(self):
+        """Get precipitation type as (setting, actual) tuple for backward compatibility."""
+        if self._precip_type_setting in ["rain", "snow"]:
+            return (self._precip_type_setting, self._precip_type_setting)
+        self._precip_type_actual = (
+            "rain" if date.today().month in range(4, 11) else "snow"
+        )
+        return ("auto", self._precip_type_actual)
+
+    @precip_type.setter
+    def precip_type(self, user_input):
+        """Set precipitation type."""
+        if user_input not in ["rain", "snow", "auto"]:
+            raise ValueError("precip_type must be 'rain', 'snow', or 'auto'")
+        self._precip_type_setting = user_input
+        self._precip_type_actual = self.precip_type[1]
+        # Update the underlying map layer
+        self._map.layer = self._precip_type_actual
+
+    @property
+    def radar_opacity(self):
+        """Get radar opacity for backward compatibility."""
+        return self._map.layer_opacity
+
+    @radar_opacity.setter
+    def radar_opacity(self, value):
+        """Set radar opacity for backward compatibility."""
+        self._map.layer_opacity = value
+
+    async def get_latest_frame(self):
+        """Get the latest radar image from Environment Canada."""
+        return await self._map.get_latest_frame()
+
+    async def update(self):
+        """Update the radar image."""
+        await self._map.update()
+        self.image = self._map.image
+
+    async def get_loop(self, fps=5):
+        """Build an animated GIF of recent radar images."""
+        return await self._map.get_loop(fps)
+
+    # Expose internal methods for backward compatibility if needed
+    async def _get_dimensions(self):
+        """Get time range of available radar images."""
+        return await self._map._get_dimensions()
+
+    async def _get_basemap(self):
+        """Fetch the background map image."""
+        return await self._map._get_basemap()
+
+    async def _get_legend(self):
+        """Fetch legend image."""
+        return await self._map._get_legend()

{env_canada-0.10.1 → env_canada-0.11.0}/env_canada/ec_weather.py

@@ -1,8 +1,11 @@
+import copy
 import csv
 import logging
 import re
 from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
+from urllib.parse import urljoin
+
 import voluptuous as vol
 from aiohttp import (
     ClientConnectorDNSError,
@@ -20,7 +23,7 @@ from .constants import USER_AGENT
 
 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"
+WEATHER_BASE_URL = "https://dd.weather.gc.ca/citypage_weather/{province}/{hour}/"
 
 CLIENT_TIMEOUT = ClientTimeout(10)
 
@@ -228,9 +231,16 @@ def validate_station(station):
     """Check that the station ID is well-formed."""
     if station is None:
         return
-    if not re.fullmatch(r"[A-Z]{2}/s0000\d{3}", station):
-        raise vol.Invalid('Station ID must be of the form "XX/s0000###"')
-    return station
+    # Accept either full format "XX/s0000###" or simplified 1-3 digit format
+    if not (
+        re.fullmatch(r"[A-Z]{2}/s0000\d{3}", station)
+        or re.fullmatch(r"s0000\d{3}", station)
+        or re.fullmatch(r"\d{1,3}", station)
+    ):
+        raise vol.Invalid(
+            'Station ID must be of the form "XX/s0000###", "s0000###" or 1-3 digits'
+        )
+    return station[-3:]
 
 
 def _parse_timestamp(time_str: str | None) -> datetime | None:
@@ -267,8 +277,16 @@ async def get_ec_sites():
     return sites
 
 
+def find_province_for_station(site_list, station_number):
+    """Find the province code for a given station number."""
+    for site in site_list:
+        if site["Codes"] == f"s0000{station_number.zfill(3)}":
+            return site["Province Codes"]
+    return None
+
+
 def closest_site(site_list, lat, lon):
-    """Return the province/site_code of the closest station to our lat/lon."""
+    """Return the (province_code, station_number) tuple of the closest station to our lat/lon."""
 
     def site_distance(site):
         """Calculate distance to a site."""
@@ -276,7 +294,55 @@ def closest_site(site_list, lat, lon):
 
     closest = min(site_list, key=site_distance)
 
-    return "{}/{}".format(closest["Province Codes"], closest["Codes"])
+    # Extract station number from "s0000###" format
+    station_number = closest["Codes"][5:]  # Remove "s0000" prefix
+    return (closest["Province Codes"], station_number)
+
+
+async def discover_weather_file_url(session, province_code, station_number, language):
+    """Discover the URL for the most recent weather file."""
+    # Convert language to the file suffix format
+    lang_suffix = "en" if language == "english" else "fr"
+
+    # Start with current UTC hour and work backwards
+    current_utc = datetime.now(timezone.utc)
+
+    for hours_back in range(3):  # Check current hour and 2 hours back
+        check_time = current_utc - timedelta(hours=hours_back)
+        hour_str = f"{check_time.hour:02d}"
+
+        # Construct directory URL
+        directory_url = WEATHER_BASE_URL.format(province=province_code, hour=hour_str)
+
+        try:
+            LOG.debug("Checking directory: %s", directory_url)
+            response = await session.get(
+                directory_url,
+                headers={"User-Agent": USER_AGENT},
+                timeout=CLIENT_TIMEOUT,
+            )
+            html_content = await response.text()
+
+            # Parse HTML directory listing to find matching files
+            station_pattern = f"s0000{station_number.zfill(3)}"
+            file_pattern = rf'href="([^"]*MSC_CitypageWeather_{station_pattern}_{lang_suffix}\.xml)"'
+
+            matches = re.findall(file_pattern, html_content)
+
+            if matches:
+                # Sort by filename (which includes timestamp) and get the most recent
+                matches.sort(reverse=True)
+                latest_file = matches[0]
+                return urljoin(directory_url, latest_file)
+
+        except (ClientConnectorDNSError, TimeoutError, ClientResponseError) as err:
+            LOG.debug("Failed to check directory %s: %s", directory_url, err)
+            continue
+
+    # If no file found in recent hours, raise exception
+    raise ec_exc.UnknownStationId(
+        f"No recent weather data found for station {station_number} in province {province_code}"
+    )
 
 
 class ECWeather:
@@ -321,7 +387,8 @@ class ECWeather:
         self.site_list = []
 
         if "station_id" in kwargs and kwargs["station_id"] is not None:
-            self.station_id = kwargs["station_id"]
+            # Station ID will be converted to tuple (province_code, station_number) during update()
+            self.station_id = kwargs["station_id"]  # Store raw input temporarily
             self.lat = None
             self.lon = None
         else:
@@ -356,13 +423,27 @@ class ECWeather:
         if not self.site_list:
             self.site_list = await get_ec_sites()
             if self.station_id:
-                stn = self.station_id.split("/")
-                if len(stn) == 2:
-                    for site in self.site_list:
-                        if stn[1] == site["Codes"] and stn[0] == site["Province Codes"]:
-                            self.lat = site["Latitude"]
-                            self.lon = site["Longitude"]
-                            break
+                # Convert raw station input to tuple (province_code, station_number)
+                if isinstance(self.station_id, str):
+                    station_number = (
+                        self.station_id
+                    )  # Already normalized by validate_station
+                    province_code = find_province_for_station(
+                        self.site_list, station_number
+                    )
+                    if province_code is None:
+                        raise ec_exc.UnknownStationId
+                    self.station_id = (province_code, station_number)
+
+                # Find lat/lon for the station
+                for site in self.site_list:
+                    if (
+                        site["Codes"] == f"s0000{self.station_id[1].zfill(3)}"
+                        and site["Province Codes"] == self.station_id[0]
+                    ):
+                        self.lat = site["Latitude"]
+                        self.lon = site["Longitude"]
+                        break
                 if not self.lat:
                     raise ec_exc.UnknownStationId
             else:
@@ -377,8 +458,14 @@ class ECWeather:
         # Get weather data
         try:
             async with ClientSession(raise_for_status=True) as session:
+                # Discover the URL for the most recent weather file
+                weather_url = await discover_weather_file_url(
+                    session, self.station_id[0], self.station_id[1], self.language
+                )
+                LOG.debug("Using weather URL: %s", weather_url)
+
                 response = await session.get(
-                    WEATHER_URL.format(self.station_id, self.language[0]),
+                    weather_url,
                     headers={"User-Agent": USER_AGENT},
                     timeout=CLIENT_TIMEOUT,
                 )
@@ -390,6 +477,8 @@ class ECWeather:
                 err,
                 f"Unable to retrieve weather '{err.request_info.url}': {err.message} ({err.status})",
             )
+        except ec_exc.UnknownStationId as err:
+            return self.handle_error(err, f"Unable to discover weather file: {err}")
 
         try:
             weather_tree = et.fromstring(bytes(weather_xml, encoding="utf-8"))
@@ -436,7 +525,7 @@ class ECWeather:
                         try:
                             condition["value"] = int(float(element.text))
                         except ValueError:
-                            condition["value"] = int(0)
+                            condition["value"] = 0
                     elif meta["type"] == "float":
                         try:
                             condition["value"] = float(element.text)
@@ -466,7 +555,7 @@ class ECWeather:
             }
 
         # Update alerts
-        self.alerts = ALERTS_INIT[self.language].copy()
+        self.alerts = copy.deepcopy(ALERTS_INIT[self.language])
         alert_elements = weather_tree.findall("./warnings/event")
         for alert in alert_elements:
             title = alert.attrib.get("description")

{env_canada-0.10.1 → env_canada-0.11.0/env_canada.egg-info}/PKG-INFO

@@ -1,36 +1,16 @@
 Metadata-Version: 2.4
 Name: env_canada
-Version: 0.10.1
+Version: 0.11.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>
-License: Copyright (c) 2018 The Python Packaging Authority
-        
-        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
-        
+License-Expression: MIT
 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: 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.11
 Description-Content-Type: text/markdown
@@ -69,31 +49,45 @@ This package provides access to various data sources published by [Environment a
 
 ## Weather Observations and Forecasts
 
-`ECWeather` provides current conditions and forecasts. It automatically determines which weather station to use based on latitude/longitude provided. It is also possible to specify a specific station code of the form `AB/s0000123` based on those listed in [this CSV file](https://dd.weather.gc.ca/citypage_weather/docs/site_list_towns_en.csv). For example:
+`ECWeather` provides current conditions and forecasts. It automatically determines which weather station to use based on latitude/longitude provided. It is also possible to specify a station code in multiple flexible formats:
+
+- **Full format**: `"AB/s0000123"` (province code and full station ID)
+- **Station ID only**: `"s0000123"` (station ID without province - province is resolved automatically)
+- **Numeric only**: `"123"` (just the station number - province is resolved automatically)
+
+Station codes are based on those listed in [this CSV file](https://dd.weather.gc.ca/citypage_weather/docs/site_list_towns_en.csv). For example:
 
 ```python
 import asyncio
 
 from env_canada import ECWeather
 
-ec_en = ECWeather(coordinates=(50, -100))
-ec_fr = ECWeather(station_id="ON/s0000430", language="french")
+# Using coordinates (automatic station selection)
+ec_coords = ECWeather(coordinates=(50, -100))
+
+# Using station ID - multiple formats supported:
+ec_full = ECWeather(station_id="ON/s0000430", language="french")  # Full format
+ec_station = ECWeather(station_id="s0000430")  # Station ID only
+ec_numeric = ECWeather(station_id="430")  # Numeric only
 
-asyncio.run(ec_en.update())
+asyncio.run(ec_coords.update())
 
 # current conditions
-ec_en.conditions
+ec_coords.conditions
 
 # daily forecasts
-ec_en.daily_forecasts
+ec_coords.daily_forecasts
 
 # hourly forecasts
-ec_en.hourly_forecasts
+ec_coords.hourly_forecasts
 
 # alerts
-ec_en.alerts
+ec_coords.alerts
 ```
 
+> [!NOTE]
+> As of version 0.11.0, `ECWeather` automatically handles Environment Canada's new timestamped weather file URL structure (effective June 2025). The library dynamically discovers the most recent weather files, ensuring continued functionality during Environment Canada's infrastructure changes.
+
 ## Weather Radar
 
 `ECRadar` provides Environment Canada meteorological [radar imagery](https://weather.gc.ca/radar/index_e.html).
@@ -110,6 +104,55 @@ animated_gif = asyncio.run(radar_coords.get_loop())
 latest_png = asyncio.run(radar_coords.get_latest_frame())
 ```
 
+## Weather Maps
+
+`ECMap` provides Environment Canada WMS weather map imagery with support for various meteorological layers.
+
+```python
+import asyncio
+
+from env_canada import ECMap
+
+# Create a map with rain radar layer
+map_coords = ECMap(coordinates=(50, -100), layer="rain")
+
+# Get the latest image with the specified layer
+latest_png = asyncio.run(map_coords.get_latest_frame())
+
+# Get an animated GIF with the specified layer
+animated_gif = asyncio.run(map_coords.get_loop())
+
+# Customize the map appearance
+custom_map = ECMap(
+    coordinates=(50, -100),
+    layer="snow",
+    width=1200,
+    height=800,
+    radius=300,
+    layer_opacity=80,
+    legend=True,
+    timestamp=True,
+    language="french",
+)
+```
+
+Available layers include:
+
+- `rain`: Precipitation rain radar
+- `snow`: Precipitation snow radar
+- `precip_type`: Surface precipitation type
+
+Additional configuration options:
+
+- `width`/`height`: Image dimensions (default: 800x800)
+- `radius`: Map radius in km around coordinates (default: 200km)
+- `layer_opacity`: Layer transparency 0-100% (default: 65%)
+- `legend`: Show legend (default: True)
+- `timestamp`: Show timestamp (default: True)
+- `language`: "english" or "french" (default: "english")
+
+> **Note**: ECMap automatically discovers available legend styles from Environment Canada's WMS capabilities, ensuring compatibility with any future style changes.
+
 ## Air Quality Health Index (AQHI)
 
 `ECAirQuality` provides Environment Canada [air quality](https://weather.gc.ca/airquality/pages/index_e.html) data.

{env_canada-0.10.1 → env_canada-0.11.0}/env_canada.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ env_canada/ec_cache.py
 env_canada/ec_exc.py
 env_canada/ec_historical.py
 env_canada/ec_hydro.py
+env_canada/ec_map.py
 env_canada/ec_radar.py
 env_canada/ec_weather.py
 env_canada.egg-info/PKG-INFO

{env_canada-0.10.1 → env_canada-0.11.0}/pyproject.toml

@@ -1,11 +1,11 @@
 [build-system]
-requires = ["setuptools>=64"]
+requires = ["setuptools>=77.0"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "env_canada"
 description="A package to access meteorological data from Environment Canada"
-version="0.10.1"
+version="0.11.0"
 authors = [
   {name = "Michael Davie", email = "michael.davie@gmail.com"},
 ]
@@ -13,11 +13,10 @@ maintainers = [
     {name = "Michael Davie", email = "michael.davie@gmail.com"},
 ]
 readme = "README.md"
-license = {file = "LICENSE"}
+license = "MIT"
 requires-python = ">=3.11"
 classifiers = [
     "Programming Language :: Python :: 3",
-    "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
 ]
 dependencies = [

env_canada-0.10.1/env_canada/constants.py

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