PyMetno 0.12.0__tar.gz → 0.14.0__tar.gz

pymetno-0.14.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include pytest.ini
+include requirements-test.txt

{PyMetno-0.12.0 → pymetno-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: PyMetno
-Version: 0.12.0
+Version: 0.14.0
 Summary: A library to communicate with the met.no api
 Home-page: https://github.com/Danielhiversen/pyMetno/
 Author: Daniel Hjelseth Høyer
@@ -16,3 +16,10 @@ License-File: LICENSE
 Requires-Dist: xmltodict
 Requires-Dist: aiohttp>=3.0.6
 Requires-Dist: async_timeout>=3.0.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: summary

{PyMetno-0.12.0 → pymetno-0.14.0}/PyMetno.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: PyMetno
-Version: 0.12.0
+Version: 0.14.0
 Summary: A library to communicate with the met.no api
 Home-page: https://github.com/Danielhiversen/pyMetno/
 Author: Daniel Hjelseth Høyer
@@ -16,3 +16,10 @@ License-File: LICENSE
 Requires-Dist: xmltodict
 Requires-Dist: aiohttp>=3.0.6
 Requires-Dist: async_timeout>=3.0.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: summary

{PyMetno-0.12.0 → pymetno-0.14.0}/PyMetno.egg-info/SOURCES.txt

@@ -1,10 +1,15 @@
 LICENSE
 MANIFEST.in
 README.md
+pytest.ini
+requirements-test.txt
 setup.py
 PyMetno.egg-info/PKG-INFO
 PyMetno.egg-info/SOURCES.txt
 PyMetno.egg-info/dependency_links.txt
 PyMetno.egg-info/requires.txt
 PyMetno.egg-info/top_level.txt
-metno/__init__.py
+metno/__init__.py
+metno/cache.py
+metno/exceptions.py
+tests/test_fetch.py

pymetno-0.14.0/README.md

@@ -0,0 +1,71 @@
+# pyMetno [![Build Status](https://travis-ci.org/Danielhiversen/pyMetno.svg?branch=master)](https://travis-ci.org/Danielhiversen/pyMetno)
+Python library to talk to the met.no api
+
+[Buy me a coffee :)](http://paypal.me/dahoiv)
+
+
+## Fetching Locationforecast data
+
+Pass an `aiohttp.ClientSession` to `MetWeatherData` and keep the session open
+for the lifetime of the client:
+
+```python
+import aiohttp
+from metno import MetNoError, MetWeatherData
+
+async def forecast():
+    async with aiohttp.ClientSession(headers={"User-Agent": "my-app/1.0 contact@example.com"}) as session:
+        weather = MetWeatherData({"lat": 60, "lon": 10, "altitude": 0}, session)
+        try:
+            await weather.fetch_data()
+        except MetNoError as error:
+            print(error, weather.next_fetch_at)
+            return None
+        return weather.data
+```
+
+`await fetch_data()` returns `True` on success and raises `MetNoError` on
+failure. Subclasses distinguish `MetNoHttpError` (with a `status` attribute),
+`MetNoPayloadError` (JSON, schema or an unexpected 304), `MetNoTimeoutError`,
+and `MetNoTransportError`. The legacy `await fetching_data(*args)` continues
+to return `True` or `False`. Both APIs expose the latest typed failure through
+`last_error`, clear it on success, and propagate task cancellation. The client
+does not log fetch failures; callers can choose their own reporting policy.
+A valid HTTP 203 response succeeds and follows the normal cache policy. Each
+received 203 logs a deprecation warning as required by the
+[MET terms of service](https://api.met.no/doc/TermsOfService); cache hits do not
+repeat the warning.
+
+A successful download or 304 revalidation is cached for **at least three
+hours**, for all geographic regions. A later valid HTTP `Expires` extends that
+deadline. Explicit/manual calls obey the same cache policy. `next_fetch_at`
+is an aware UTC datetime for the next permitted attempt, or `None` before
+fetching. Revalidation sends the exact `Last-Modified` value as
+`If-Modified-Since`; a 304 reuses the validated body without decoding a body.
+The timeout covers response acquisition, body reading and JSON decoding.
+Invalid responses leave the last known good representation and its validator
+intact; invalid new bodies never supply validators.
+
+Each client keeps an in-memory cache keyed by the endpoint and normalized
+request: latitude/longitude rounded to four decimal places and altitude
+truncated to an integer (`msl` remains a constructor alias for altitude).
+Different keys have independent bodies, validators, errors and deadlines;
+returning to a key reuses its cache. Requests on a client are serialized to
+avoid concurrent duplicate downloads. Nothing is shared across clients or
+persisted, and the client starts no background work.
+
+Failures schedule a later attempt instead of retrying inside the call.
+Backoff begins at **60 seconds**, doubles after consecutive failures, adds
+positive random jitter of up to 10%, and caps the total delay at **one hour**.
+This cooldown also applies to non-transient HTTP failures to avoid repeated
+manual calls. Later valid `Retry-After` (seconds or HTTP-date), `Expires`, and
+an existing cache deadline take precedence. Successful downloading or
+revalidation resets backoff. Calls during a failure cooldown return `False`
+or raise the same typed error, even when older usable data is still present.
+The caller decides when to call again; no sleeps or retry loops are started.
+
+## Tests
+
+```sh
+uv run --no-project --with-requirements requirements-test.txt --with aiohttp --with async-timeout python -m pytest
+```

{PyMetno-0.12.0 → pymetno-0.14.0}/metno/__init__.py

@@ -2,12 +2,23 @@
 import asyncio
 import datetime
 import logging
+import math
 
+from collections.abc import Mapping
 from typing import Any, List
 
 import aiohttp
 import async_timeout
 
+from .cache import CacheEntry
+from .exceptions import (
+    MetNoError,
+    MetNoHttpError,
+    MetNoPayloadError,
+    MetNoTimeoutError,
+    MetNoTransportError,
+)
+
 try:
     import ciso8601
 except ImportError:
@@ -83,16 +94,115 @@ TIMEOUT = 30
 _LOGGER = logging.getLogger(__name__)
 
 
+def _utcnow():
+    """Return an aware UTC clock value."""
+    return datetime.datetime.now(datetime.timezone.utc)
+
+
+def _normalize_params(urlparams):
+    """Use the same precision for request identity and wire parameters."""
+    return {
+        "lat": str(round(float(urlparams["lat"]), 4) or 0.0),
+        "lon": str(round(float(urlparams["lon"]), 4) or 0.0),
+        "altitude": str(int(float(urlparams.get("altitude", urlparams.get("msl", 0))))),
+    }
+
+
+_INSTANT_NUMERIC_FIELDS = (
+    "air_temperature",
+    "air_pressure_at_sea_level",
+    "relative_humidity",
+    "dew_point_temperature",
+    "ultraviolet_index_clear_sky",
+    "wind_speed",
+    "wind_speed_of_gust",
+    "wind_from_direction",
+    "fog_area_fraction",
+    "cloud_area_fraction",
+    "cloud_area_fraction_low",
+    "cloud_area_fraction_medium",
+    "cloud_area_fraction_high",
+)
+_PERIOD_NUMERIC_FIELDS = (
+    "precipitation_amount",
+    "precipitation_amount_max",
+    "precipitation_amount_min",
+    "probability_of_precipitation",
+    "probability_of_thunder",
+)
+
+
+def _validate_numeric_details(details, fields):
+    """Require present weather measurements to be finite numbers."""
+    for field in fields:
+        if field in details:
+            value = details[field]
+            if (
+                isinstance(value, bool)
+                or not isinstance(value, (int, float))
+                or not math.isfinite(value)
+            ):
+                raise ValueError(f"Invalid numeric weather value: {field}")
+
+
+def _validate_payload(payload):
+    """Require usable timestamped instant data, leaving weather fields optional."""
+    try:
+        if not isinstance(payload, Mapping) or not isinstance(payload["properties"], Mapping):
+            raise ValueError("Missing forecast properties")
+        timeseries = payload["properties"]["timeseries"]
+        if not isinstance(timeseries, list) or not timeseries:
+            raise ValueError("Missing forecast timeseries")
+        previous_timestamp = None
+        for entry in timeseries:
+            if not isinstance(entry, Mapping) or not isinstance(entry["time"], str):
+                raise ValueError("Invalid forecast entry")
+            timestamp = parse_datetime(entry["time"])
+            if (
+                not isinstance(timestamp, datetime.datetime)
+                or timestamp.tzinfo is None
+                or timestamp.utcoffset() is None
+            ):
+                raise ValueError("Forecast timestamp must include a timezone")
+            if previous_timestamp is not None and timestamp < previous_timestamp:
+                raise ValueError("Forecast timestamps are out of order")
+            previous_timestamp = timestamp
+            data = entry["data"]
+            if not isinstance(data, Mapping) or not isinstance(data["instant"], Mapping):
+                raise ValueError("Missing instant data")
+            instant_details = data["instant"]["details"]
+            if not isinstance(instant_details, Mapping):
+                raise ValueError("Missing instant details")
+            _validate_numeric_details(instant_details, _INSTANT_NUMERIC_FIELDS)
+            for period in ("next_1_hours", "next_6_hours", "next_12_hours"):
+                if period not in data:
+                    continue
+                forecast = data[period]
+                if not isinstance(forecast, Mapping):
+                    raise ValueError("Invalid forecast period")
+                if "details" in forecast:
+                    details = forecast["details"]
+                    if not isinstance(details, Mapping):
+                        raise ValueError("Invalid forecast details")
+                    _validate_numeric_details(details, _PERIOD_NUMERIC_FIELDS)
+                if "summary" in forecast:
+                    summary = forecast["summary"]
+                    if not isinstance(summary, Mapping):
+                        raise ValueError("Invalid forecast summary")
+                    if "symbol_code" in summary and not isinstance(
+                        summary["symbol_code"], str
+                    ):
+                        raise ValueError("Invalid weather symbol")
+    except (KeyError, TypeError, ValueError, OverflowError) as error:
+        raise MetNoPayloadError("Invalid Locationforecast representation") from error
+
+
 class MetWeatherData:
     """Representation of met weather data."""
 
     def __init__(self, urlparams, websession=None, api_url=DEFAULT_API_URL):
         """Initialize the Weather object."""
-        urlparams = {"lat": str(round(float(urlparams['lat']), 4)),
-                     "lon": str(round(float(urlparams['lon']), 4)),
-                     "altitude": str(int(float(urlparams.get('altitude', urlparams.get('msl', 0))))),
-                     }
-        self._urlparams = urlparams
+        self._urlparams = _normalize_params(urlparams)
         self._api_url = api_url
         if websession is None:
 
@@ -104,32 +214,112 @@ class MetWeatherData:
         else:
             self._websession = websession
         self.data = None
+        self._cache = {}
+        self._fetch_lock = asyncio.Lock()
+
+    def _entry(self):
+        params = _normalize_params(self._urlparams)
+        key = (self._api_url, tuple(sorted(params.items())))
+        return self._cache.setdefault(key, CacheEntry())
+
+    @property
+    def last_error(self):
+        """Return the current request's most recent typed failure, if any."""
+        return self._entry().last_error
+
+    @property
+    def next_fetch_at(self):
+        """Return the current request's earliest next attempt as aware UTC."""
+        return self._entry().next_fetch_at
 
     async def fetching_data(self, *_):
-        """Get the latest data from met.no."""
+        """Return success for usable fresh data, retaining the legacy boolean API."""
         try:
-            async with async_timeout.timeout(TIMEOUT):
-                resp = await self._websession.get(self._api_url, params=self._urlparams)
-            if resp.status >= 400:
-                _LOGGER.error("%s returned %s", self._api_url, resp.status)
-                return False
-            self.data = await resp.json()
-        except (asyncio.TimeoutError, aiohttp.ClientError) as err:
-            _LOGGER.error("Access to %s returned error '%s'", self._api_url, type(err).__name__)
-            return False
-        except ValueError:
-            _LOGGER.exception("Unable to parse json response from %s", self._api_url)
+            await self.fetch_data()
+        except MetNoError:
             return False
         return True
 
+    async def fetch_data(self) -> bool:
+        """Return True for a fetched/cached forecast, raising typed failures."""
+        async with self._fetch_lock:
+            params = _normalize_params(self._urlparams)
+            api_url = self._api_url
+            key = (api_url, tuple(sorted(params.items())))
+            entry = self._cache.setdefault(key, CacheEntry())
+            self.data = entry.data
+            now = _utcnow()
+            if entry.next_fetch_at is not None and now < entry.next_fetch_at:
+                if entry.last_error is not None:
+                    raise entry.last_error.with_traceback(None)
+                return True
+            request_headers = {}
+            if entry.data is not None and entry.last_modified is not None:
+                request_headers["If-Modified-Since"] = entry.last_modified
+            response_headers = {}
+            try:
+                async with async_timeout.timeout(TIMEOUT):
+                    async with self._websession.get(
+                        api_url, params=params, headers=request_headers
+                    ) as response:
+                        response_headers = response.headers
+                        if response.status == 203:
+                            _LOGGER.warning("%s is deprecated (HTTP 203)", api_url)
+                        if response.status == 304:
+                            if entry.data is None:
+                                raise MetNoPayloadError("HTTP 304 without a cached representation")
+                            payload = entry.data
+                            last_modified = response.headers.get("Last-Modified", entry.last_modified)
+                        elif response.status not in (200, 203):
+                            raise MetNoHttpError(response.status)
+                        else:
+                            try:
+                                payload = await response.json()
+                            except (ValueError, UnicodeError, aiohttp.ContentTypeError) as error:
+                                raise MetNoPayloadError("Invalid Locationforecast JSON") from error
+                            _validate_payload(payload)
+                            last_modified = response.headers.get("Last-Modified")
+            except MetNoError as error:
+                entry.failed(_utcnow(), response_headers, error)
+                raise
+            except asyncio.TimeoutError as error:
+                failure = MetNoTimeoutError("Locationforecast request timed out")
+                entry.failed(_utcnow(), response_headers, failure)
+                raise failure from error
+            except aiohttp.ClientError as error:
+                if isinstance(error, aiohttp.ClientResponseError):
+                    status = getattr(error, "status", None)
+                    if status is None:
+                        status = error.code
+                    if status >= 400:
+                        failure = MetNoHttpError(status)
+                        entry.failed(_utcnow(), error.headers or response_headers, failure)
+                        raise failure from error
+                failure = MetNoTransportError("Locationforecast transport failed")
+                entry.failed(_utcnow(), response_headers, failure)
+                raise failure from error
+            entry.data = payload
+            entry.last_modified = last_modified
+            entry.succeeded(_utcnow(), response_headers)
+            self.data = payload
+            return True
+
     def get_current_weather(self):
         """Get the current weather data from met.no."""
-        try:
-            timeseries = self.data["properties"]["timeseries"]
-            now = parse_datetime(timeseries[0]["time"])
-        except (TypeError, KeyError, IndexError):
-            now = datetime.datetime.now(datetime.timezone.utc)
-        return self.get_weather(now, hourly=True)
+        if self.data is None:
+            return {}
+        timestamps = [
+            parse_datetime(entry["time"]).astimezone(datetime.timezone.utc)
+            for entry in self.data["properties"]["timeseries"]
+        ]
+        now = _utcnow().astimezone(datetime.timezone.utc)
+        if not timestamps or now > max(timestamps):
+            return {}
+        current = max(
+            (timestamp for timestamp in timestamps if timestamp <= now),
+            default=min(timestamps),
+        )
+        return self.get_weather(current, hourly=True)
 
     def get_forecast(self, time_zone, hourly=False, range_start=1, range_stop=None):
         """Get the forecast weather data from met.no."""
@@ -167,6 +357,7 @@ class MetWeatherData:
         daily_windspeed = []
         daily_windgust = []
         daily_dew_point = []
+        daily_uv_index = []
         entries = []
 
         for time_entry in self.data["properties"]["timeseries"]:
@@ -194,6 +385,9 @@ class MetWeatherData:
             dew_point = get_data("dew_point_temperature", [time_entry])
             if dew_point is not None:
                 daily_dew_point.append(dew_point)
+            uv_index = get_data("ultraviolet_index_clear_sky", [time_entry])
+            if uv_index is not None:
+                daily_uv_index.append(uv_index)
 
             if time.astimezone() <= timestamp:
                 entries.append(time_entry)
@@ -214,6 +408,7 @@ class MetWeatherData:
             res["wind_gust"] = get_data("wind_speed_of_gust", entries)
             res["cloudiness"] = get_data("cloud_area_fraction", entries)
             res["dew_point"] = get_data("dew_point_temperature", entries)
+            res["uv_index"] = get_data("ultraviolet_index_clear_sky", entries)
         else:
             res["temperature"] = (
                 None if daily_temperatures == [] else max(daily_temperatures)
@@ -236,6 +431,9 @@ class MetWeatherData:
             res["dew_point"] = (
                 None if daily_dew_point == [] else max(daily_dew_point)
             )
+            res["uv_index"] = (
+                None if daily_uv_index == [] else max(daily_uv_index)
+            )
 
         return res
 
@@ -283,6 +481,7 @@ def get_data(param: str, data: List[dict]) -> Any:
                     "air_pressure_at_sea_level",
                     "relative_humidity",
                     "dew_point_temperature",
+                    "ultraviolet_index_clear_sky",
             ):
                 new_state = instant_details[param]
             elif param in ("wind_speed", "wind_speed_of_gust"):

pymetno-0.14.0/metno/cache.py

@@ -0,0 +1,71 @@
+"""Instance cache records and conservative server deadline handling."""
+
+import datetime
+from email.utils import parsedate_to_datetime
+import random
+
+MIN_FETCH_INTERVAL = datetime.timedelta(hours=3)
+RETRY_BASE_SECONDS = 60
+RETRY_MAX_SECONDS = 3600
+UTC = datetime.timezone.utc
+
+
+class CacheEntry:
+    """State belonging to one normalized endpoint and location."""
+
+    def __init__(self):
+        self.data = None
+        self.last_modified = None
+        self.next_fetch_at = None
+        self.last_error = None
+        self.failures = 0
+
+    def succeeded(self, now, headers):
+        """Apply freshness metadata after validation or revalidation."""
+        self.next_fetch_at = max(
+            now + MIN_FETCH_INTERVAL, http_date(headers.get("Expires")) or now
+        )
+        self.last_error = None
+        self.failures = 0
+
+    def failed(self, now, headers, error):
+        """Schedule a later attempt without replacing a valid representation."""
+        self.failures = min(self.failures + 1, 7)
+        jitter_fraction = 0.1
+        base = min(
+            RETRY_MAX_SECONDS / (1 + jitter_fraction),
+            RETRY_BASE_SECONDS * 2 ** (self.failures - 1),
+        )
+        delay = base + random.uniform(0.001, base * jitter_fraction)
+        self.next_fetch_at = max(
+            self.next_fetch_at or now,
+            now + datetime.timedelta(seconds=delay),
+            http_date(headers.get("Expires")) or now,
+            retry_after(headers.get("Retry-After"), now) or now,
+        )
+        self.last_error = error
+
+
+def http_date(value):
+    """Parse an HTTP date, ignoring malformed or out-of-range headers."""
+    if not value:
+        return None
+    try:
+        parsed = parsedate_to_datetime(value)
+        if parsed.tzinfo is None:
+            return None
+        return parsed.astimezone(UTC)
+    except (TypeError, ValueError, OverflowError):
+        return None
+
+
+def retry_after(value, now):
+    """Support both delay-seconds and HTTP-date Retry-After values."""
+    if not value:
+        return None
+    if value.isascii() and value.isdecimal():
+        try:
+            return now + datetime.timedelta(seconds=int(value))
+        except (ValueError, OverflowError):
+            return None
+    return http_date(value)

pymetno-0.14.0/metno/exceptions.py

@@ -0,0 +1,25 @@
+"""Typed failures from the Locationforecast client."""
+
+
+class MetNoError(Exception):
+    """Base exception for a failed forecast fetch."""
+
+
+class MetNoHttpError(MetNoError):
+    """The server returned an unsuccessful HTTP status."""
+
+    def __init__(self, status):
+        self.status = status
+        super().__init__("Locationforecast returned HTTP {}".format(status))
+
+
+class MetNoPayloadError(MetNoError):
+    """The response does not contain a usable forecast representation."""
+
+
+class MetNoTimeoutError(MetNoError):
+    """Response acquisition or body reading exceeded the timeout."""
+
+
+class MetNoTransportError(MetNoError):
+    """The forecast request failed at the transport layer."""

pymetno-0.14.0/pytest.ini

@@ -0,0 +1,3 @@
+[pytest]
+asyncio_mode = auto
+asyncio_default_fixture_loop_scope = function

pymetno-0.14.0/requirements-test.txt

@@ -0,0 +1,2 @@
+pytest>=8
+pytest-asyncio>=0.24

{PyMetno-0.12.0 → pymetno-0.14.0}/setup.py

@@ -4,7 +4,7 @@ setup(
     name = 'PyMetno',
     packages = ['metno'],
     install_requires=['xmltodict', "aiohttp>=3.0.6", "async_timeout>=3.0.0"],
-    version = '0.12.0',
+    version = '0.14.0',
     description = 'A library to communicate with the met.no api',
     author='Daniel Hjelseth Høyer',
     url='https://github.com/Danielhiversen/pyMetno/',