pyopenweathermap 0.2.2__tar.gz → 0.3.0__tar.gz

pyopenweathermap-0.3.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: pyopenweathermap
+Version: 0.3.0
+Summary: lib for OpenWeatherMap for Home Assistant
+License: MIT
+License-File: LICENSE
+Keywords: homeassistant,owm,openweathermap
+Author: Evgeny
+Author-email: iam@freekode.org
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Dist: aiohttp (>=3.9.5,<4.0.0)
+Project-URL: Homepage, https://github.com/freekode/pyopenweathermap
+Project-URL: Repository, https://github.com/freekode/pyopenweathermap
+Description-Content-Type: text/markdown
+
+# pyopenweathermap
+
+Python library for OpenWeatherMap API for Home Assistant.
+
+## One Call API
+
+Use `create_owm_client(api_key, 'v3.0')` for the combined One Call 3.0
+endpoint, or `create_owm_client(api_key, 'v4.0')` for the separate One Call 4.0
+endpoints. Both accept `units` (default `metric`) and `lang` (default `en`),
+and expose `await client.get_weather(lat, lon)` returning a `WeatherReport`.
+The current/forecast 2.5 and air-pollution clients remain available.
+
+The 4.0 adapter requests `current`, `timeline/1min`, `timeline/1h`, and
+`timeline/1day`, then converts their `data` arrays to the existing report
+models. It returns up to 60 minute records, 48 hourly records, and 8 daily
+records. Missing optional weather fields keep the existing converter defaults;
+empty data arrays produce empty report sections. Malformed envelopes/records
+raise `RequestError`, and a failed endpoint/page fails the report rather than
+silently returning partially refreshed weather.
+
+### Pagination and request budget
+
+A typical complete 4.0 report uses **six HTTP requests**: current, minutely,
+three hourly pages (20 + 20 + 8 returned records), and daily. Each page is a
+separate API call; check account entitlement and budget before enabling 4.0.
+Short pages can require additional requests. The adapter follows `next` only
+while it needs records within the requested count/time horizon, stops on an
+empty page, removes overlapping records, and rejects repeated links or pages
+that make no progress. Daily records are capped at eight; it does not fetch the
+full longer-range 4.0 outlook. Requests are sequential and stop at the first
+error. No automatic retry is performed.
+
+Only HTTPS pagination links to the same OpenWeather host and timeline endpoint
+are accepted. Client coordinates, key, units, and language are preserved on
+all pages. HTTP redirects are not followed, and request URL debug logs redact
+`appid`. `validate_key()` uses one 4.0 current request (or the legacy 3.0 key
+validation call); authorization errors return `False`, and other request errors
+are propagated.
+
+### Daily precipitation caveat
+
+The [migration guide](https://openweathermap.org/api/one-call-3-migration#daily)
+describes 4.0 daily `rain` and `snow` as scalar daily totals in mm, while the
+[reference](https://openweathermap.org/api/one-call-4#daily_parameter) also lists
+hourly-shaped `rain.1h` and `snow.1h` objects. This adapter accepts nonnegative
+numeric daily totals and defaults absent fields to zero. It raises a descriptive
+`RequestError` for an object or other unsupported value. An hourly rate cannot
+safely be labeled or multiplied into a daily total. The 3.0 converter behavior
+is unchanged. Confirm this ambiguity with a sanitized live response before
+claiming production validation.
+
+Reference: [One Call 4.0 endpoints and pagination](https://openweathermap.org/api/one-call-4).
+Weather alerts and 15-minute forecasts are outside the existing report model.
+
+## Development and testing
+
+Use Python 3.11+ and Poetry (`poetry install`). The project uses `poetry.lock`.
+The default suite and CI are offline and do not require an API key:
+
+```sh
+poetry run pytest
+poetry run pytest -m 'not network'
+poetry build
+```
+
+Fixtures are synthetic, source-labeled contract examples, not recordings of
+successful authenticated calls. Unmarked tests block socket connections and
+DNS. Run credentialed smoke tests only when you have approved account access,
+4.0 entitlement, and a request budget; they are explicitly opt-in:
+
+```sh
+# Supply OWM_API_KEY through your local environment, not source control.
+poetry run pytest -m network
+```
+
+The existing skipped legacy smoke tests remain skipped. Offline tests establish
+adapter behavior against the published contract; they do not verify an account's
+entitlement, actual provider responses, Home Assistant integration, or deployment.
+

pyopenweathermap-0.3.0/README.md

@@ -0,0 +1,78 @@
+# pyopenweathermap
+
+Python library for OpenWeatherMap API for Home Assistant.
+
+## One Call API
+
+Use `create_owm_client(api_key, 'v3.0')` for the combined One Call 3.0
+endpoint, or `create_owm_client(api_key, 'v4.0')` for the separate One Call 4.0
+endpoints. Both accept `units` (default `metric`) and `lang` (default `en`),
+and expose `await client.get_weather(lat, lon)` returning a `WeatherReport`.
+The current/forecast 2.5 and air-pollution clients remain available.
+
+The 4.0 adapter requests `current`, `timeline/1min`, `timeline/1h`, and
+`timeline/1day`, then converts their `data` arrays to the existing report
+models. It returns up to 60 minute records, 48 hourly records, and 8 daily
+records. Missing optional weather fields keep the existing converter defaults;
+empty data arrays produce empty report sections. Malformed envelopes/records
+raise `RequestError`, and a failed endpoint/page fails the report rather than
+silently returning partially refreshed weather.
+
+### Pagination and request budget
+
+A typical complete 4.0 report uses **six HTTP requests**: current, minutely,
+three hourly pages (20 + 20 + 8 returned records), and daily. Each page is a
+separate API call; check account entitlement and budget before enabling 4.0.
+Short pages can require additional requests. The adapter follows `next` only
+while it needs records within the requested count/time horizon, stops on an
+empty page, removes overlapping records, and rejects repeated links or pages
+that make no progress. Daily records are capped at eight; it does not fetch the
+full longer-range 4.0 outlook. Requests are sequential and stop at the first
+error. No automatic retry is performed.
+
+Only HTTPS pagination links to the same OpenWeather host and timeline endpoint
+are accepted. Client coordinates, key, units, and language are preserved on
+all pages. HTTP redirects are not followed, and request URL debug logs redact
+`appid`. `validate_key()` uses one 4.0 current request (or the legacy 3.0 key
+validation call); authorization errors return `False`, and other request errors
+are propagated.
+
+### Daily precipitation caveat
+
+The [migration guide](https://openweathermap.org/api/one-call-3-migration#daily)
+describes 4.0 daily `rain` and `snow` as scalar daily totals in mm, while the
+[reference](https://openweathermap.org/api/one-call-4#daily_parameter) also lists
+hourly-shaped `rain.1h` and `snow.1h` objects. This adapter accepts nonnegative
+numeric daily totals and defaults absent fields to zero. It raises a descriptive
+`RequestError` for an object or other unsupported value. An hourly rate cannot
+safely be labeled or multiplied into a daily total. The 3.0 converter behavior
+is unchanged. Confirm this ambiguity with a sanitized live response before
+claiming production validation.
+
+Reference: [One Call 4.0 endpoints and pagination](https://openweathermap.org/api/one-call-4).
+Weather alerts and 15-minute forecasts are outside the existing report model.
+
+## Development and testing
+
+Use Python 3.11+ and Poetry (`poetry install`). The project uses `poetry.lock`.
+The default suite and CI are offline and do not require an API key:
+
+```sh
+poetry run pytest
+poetry run pytest -m 'not network'
+poetry build
+```
+
+Fixtures are synthetic, source-labeled contract examples, not recordings of
+successful authenticated calls. Unmarked tests block socket connections and
+DNS. Run credentialed smoke tests only when you have approved account access,
+4.0 entitlement, and a request budget; they are explicitly opt-in:
+
+```sh
+# Supply OWM_API_KEY through your local environment, not source control.
+poetry run pytest -m network
+```
+
+The existing skipped legacy smoke tests remain skipped. Offline tests establish
+adapter behavior against the published contract; they do not verify an account's
+entitlement, actual provider responses, Home Assistant integration, or deployment.

{pyopenweathermap-0.2.2 → pyopenweathermap-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pyopenweathermap"
-version = "0.2.2"
+version = "0.3.0"
 description = "lib for OpenWeatherMap for Home Assistant"
 authors = ["Evgeny <iam@freekode.org>"]
 license = "MIT"
@@ -26,6 +26,7 @@ requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
 
 [tool.pytest.ini_options]
+addopts = "-m 'not network'"
 markers = [
     "network: tests that require network access"
 ]

pyopenweathermap-0.3.0/src/pyopenweathermap/client/onecall_client.py

@@ -0,0 +1,175 @@
+from collections.abc import Callable
+from math import isfinite
+from typing import TypeVar
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+from .owm_abstract_client import OWMClient
+from ..data_converter import DataConverter
+from ..exception import RequestError, UnauthorizedError
+from ..weather import WeatherReport
+from ..air_pollution import AirPollutionReport
+
+API_URL = 'https://api.openweathermap.org/data/3.0/onecall'
+V4_API_URL = 'https://api.openweathermap.org/data/4.0/onecall'
+WeatherT = TypeVar('WeatherT')
+
+
+class OWMOneCallClient(OWMClient):
+    def __init__(self, api_key, api_version, units="metric", lang='en'):
+        super().__init__()
+        self.api_key = api_key
+        self.api_version = api_version
+        self.units = units
+        self.lang = lang
+
+    async def get_weather(self, lat, lon) -> WeatherReport:
+        if self.api_version == 'v4.0':
+            return await self._get_v4_weather(lat, lon)
+
+        json_response = await self.http_client.request(self._get_url(lat, lon))
+        current, minutely, hourly, daily = None, [], [], []
+        if json_response.get('current') is not None:
+            current = DataConverter.onecall_to_current_weather(json_response['current'])
+        if json_response.get('minutely') is not None:
+            minutely = [DataConverter.onecall_to_minutely_weather_forecast(item) for item in json_response['minutely']]
+        if json_response.get('hourly') is not None:
+            hourly = [DataConverter.onecall_to_hourly_weather_forecast(item) for item in json_response['hourly']]
+        if json_response.get('daily') is not None:
+            daily = [DataConverter.onecall_to_daily_weather_forecast(item) for item in json_response['daily']]
+
+        return WeatherReport(current, minutely, hourly, daily)
+
+    async def _get_v4_weather(self, lat, lon) -> WeatherReport:
+        response = await self.http_client.request(self._get_url(lat, lon))
+        rows = self._v4_data(response)
+        current = self._convert_v4(rows[0], DataConverter.onecall_to_current_weather) if rows else None
+        # Keep the legacy report horizon. Requests are sequential so failures do
+        # not leave other billable requests running in the background.
+        minutely = await self._v4_forecast(
+            lat, lon, 'timeline/1min', 60, 60,
+            DataConverter.onecall_to_minutely_weather_forecast,
+        )
+        hourly = await self._v4_forecast(
+            lat, lon, 'timeline/1h', 48, 3600,
+            DataConverter.onecall_to_hourly_weather_forecast,
+        )
+        daily = await self._v4_forecast(
+            lat, lon, 'timeline/1day', 8, 86400,
+            DataConverter.onecall_to_daily_weather_forecast,
+        )
+        return WeatherReport(current, minutely, hourly, daily)
+
+    async def _v4_forecast(
+        self, lat, lon, endpoint, count, interval, converter: Callable[[dict], WeatherT],
+    ) -> list[WeatherT]:
+        url = self._get_url(lat, lon, endpoint)
+        visited = set()
+        result: list[WeatherT] = []
+        last_dt = None
+        end_dt = None
+        while len(result) < count:
+            # Canonicalize query order so a reordered repeated link also stops.
+            identity = (urlsplit(url).path, tuple(sorted(parse_qsl(urlsplit(url).query))))
+            if identity in visited:
+                raise RequestError('Repeated One Call 4.0 pagination link')
+            visited.add(identity)
+            response = await self.http_client.request(url)
+            rows = self._v4_data(response)
+            if not rows:
+                break
+            previous_dt = None
+            added = 0
+            for row in rows:
+                dt = row.get('dt')
+                if not isinstance(dt, int) or isinstance(dt, bool):
+                    raise RequestError('Invalid One Call 4.0 forecast timestamp')
+                if previous_dt is not None and dt < previous_dt:
+                    raise RequestError('Unordered One Call 4.0 forecast page')
+                previous_dt = dt
+                if end_dt is None:
+                    end_dt = dt + count * interval
+                if dt >= end_dt:
+                    return result
+                if last_dt is not None and dt <= last_dt:
+                    continue  # Pagination may overlap at the page boundary.
+                if endpoint == 'timeline/1day':
+                    self._validate_v4_daily_precipitation(row)
+                result.append(self._convert_v4(row, converter))
+                last_dt = dt
+                added += 1
+                if len(result) == count:
+                    return result
+            next_url = response.get('next')
+            if next_url is None or next_url == '':
+                break
+            if not added:
+                raise RequestError('One Call 4.0 pagination made no progress')
+            # Every continued page adds a record, so even changing links cannot
+            # cause unbounded requests. Stop at the count/time horizon above.
+            url = self._v4_next_url(next_url, lat, lon, endpoint)
+        return result
+
+    @staticmethod
+    def _v4_data(response):
+        if not isinstance(response, dict) or not isinstance(response.get('data'), list):
+            raise RequestError('Invalid One Call 4.0 response: expected a data array')
+        if any(not isinstance(row, dict) for row in response['data']):
+            raise RequestError('Invalid One Call 4.0 response: expected data objects')
+        return response['data']
+
+    @staticmethod
+    def _convert_v4(row, converter: Callable[[dict], WeatherT]) -> WeatherT:
+        try:
+            return converter(row)
+        except (KeyError, TypeError, ValueError, IndexError, OverflowError, OSError) as error:
+            raise RequestError('Invalid One Call 4.0 weather record') from error
+
+    @staticmethod
+    def _validate_v4_daily_precipitation(row):
+        # The migration guide specifies daily scalar totals, but the reference
+        # also lists rain.1h/snow.1h. Never mislabel an hourly rate as a daily total.
+        for field in ('rain', 'snow'):
+            value = row.get(field, 0)
+            if (not isinstance(value, (int, float)) or isinstance(value, bool)
+                    or (isinstance(value, float) and not isfinite(value)) or value < 0):
+                raise RequestError(
+                    f'Unsupported One Call 4.0 daily {field}: expected a numeric daily total'
+                )
+
+    def _v4_next_url(self, next_url, lat, lon, endpoint):
+        if not isinstance(next_url, str):
+            raise RequestError('Invalid One Call 4.0 pagination link')
+        try:
+            parts = urlsplit(next_url)
+        except ValueError as error:
+            raise RequestError('Invalid One Call 4.0 pagination link') from error
+        expected = urlsplit(f'{V4_API_URL}/{endpoint}')
+        if (parts.scheme != 'https' or parts.netloc != expected.netloc
+                or parts.path != expected.path or parts.fragment):
+            raise RequestError('Unsafe One Call 4.0 pagination link')
+        query = dict(parse_qsl(parts.query, keep_blank_values=True))
+        # Some documented links omit units/lang. Preserve the caller's options
+        # and location/key even if a next link omits or changes them.
+        query.update(self._query_params(lat, lon))
+        return urlunsplit(parts._replace(query=urlencode(query)))
+
+    async def get_air_pollution(self, lat, lon) -> AirPollutionReport:
+        raise NotImplementedError('One Call client does not have get_air_pollution()')
+
+    async def validate_key(self) -> bool:
+        url = self._get_url(50.06, 14.44)
+        if self.api_version != 'v4.0':
+            url += '&exclude=current,minutely,hourly,daily,alerts'
+        try:
+            await self.http_client.request(url)
+            return True
+        except UnauthorizedError:
+            return False
+
+    def _query_params(self, lat, lon):
+        return {'lat': lat, 'lon': lon, 'appid': self.api_key,
+                'units': self.units, 'lang': self.lang}
+
+    def _get_url(self, lat, lon, endpoint='current'):
+        api_url = f'{V4_API_URL}/{endpoint}' if self.api_version == 'v4.0' else API_URL
+        return f'{api_url}?{urlencode(self._query_params(lat, lon))}'

{pyopenweathermap-0.2.2 → pyopenweathermap-0.3.0}/src/pyopenweathermap/client/owm_client_factory.py

@@ -9,7 +9,7 @@ def create_owm_client(api_key, api_type, units="metric", lang='en'):
     logger = logging.getLogger(__name__)
     
     logger.info('Initializing OWMClient with api type: ' + str(api_type))
-    if api_type == 'v3.0':
+    if api_type == 'v3.0' or api_type == 'v4.0':
         return OWMOneCallClient(api_key, api_type, units, lang)
     if api_type == 'current' or api_type == 'forecast':
         return OWMFreeClient(api_key, api_type, units, lang)

pyopenweathermap-0.3.0/src/pyopenweathermap/http_client.py

@@ -0,0 +1,46 @@
+import logging
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+from aiohttp import ClientSession, ContentTypeError
+
+from .exception import UnauthorizedError, RequestError, TooManyRequestsError
+
+
+class HttpClient:
+    request_timeout: int
+    logger = logging.getLogger(__name__)
+
+    def __init__(self, request_timeout=20):
+        self.request_timeout = request_timeout
+
+    async def request(self, url):
+        parts = urlsplit(url)
+        safe_query = urlencode([(key, '[redacted]' if key == 'appid' else value)
+                                for key, value in parse_qsl(parts.query)])
+        self.logger.debug('Requesting url: %s', urlunsplit(parts._replace(query=safe_query)))
+        async with ClientSession() as session:
+            try:
+                async with session.get(url=url, timeout=self.request_timeout, allow_redirects=False) as response:
+                    try:
+                        response_json = await response.json()
+                    except (ValueError, ContentTypeError):
+                        # aiohttp content-type errors contain the credentialed
+                        # request URL. Do not expose it through exception chains.
+                        if response.status == 200:
+                            raise RequestError('Invalid JSON response') from None
+                        response_json = {}
+                    if response.status == 200:
+                        return response_json
+                    message = response_json.get('message') if isinstance(response_json, dict) else None
+                    message = message or f'HTTP status code: {response.status}'
+                    if response.status == 401:
+                        raise UnauthorizedError(message)
+                    if response.status == 429:
+                        raise TooManyRequestsError(message)
+                    raise RequestError(message)
+            except RequestError:
+                raise
+            except TimeoutError:
+                raise RequestError('Request timeout') from None
+            except Exception as error:
+                raise RequestError(f'Request failed: {type(error).__name__}') from None

pyopenweathermap-0.2.2/PKG-INFO

@@ -1,23 +0,0 @@
-Metadata-Version: 2.3
-Name: pyopenweathermap
-Version: 0.2.2
-Summary: lib for OpenWeatherMap for Home Assistant
-License: MIT
-Keywords: homeassistant,owm,openweathermap
-Author: Evgeny
-Author-email: iam@freekode.org
-Requires-Python: >=3.11,<4.0
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: aiohttp (>=3.9.5,<4.0.0)
-Project-URL: Homepage, https://github.com/freekode/pyopenweathermap
-Project-URL: Repository, https://github.com/freekode/pyopenweathermap
-Description-Content-Type: text/markdown
-
-# pyopenweathermap
-
-Python library for OpenWeatherMap API for Home Assistant
-

pyopenweathermap-0.2.2/README.md

@@ -1,3 +0,0 @@
-# pyopenweathermap
-
-Python library for OpenWeatherMap API for Home Assistant

pyopenweathermap-0.2.2/src/pyopenweathermap/client/onecall_client.py

@@ -1,52 +0,0 @@
-from .owm_abstract_client import OWMClient
-from ..data_converter import DataConverter
-from ..exception import UnauthorizedError
-from ..weather import WeatherReport
-from ..air_pollution import AirPollutionReport
-
-API_URL = 'https://api.openweathermap.org/data/3.0/onecall'
-
-
-class OWMOneCallClient(OWMClient):
-    def __init__(self, api_key, api_version, units="metric", lang='en'):
-        super().__init__()
-        self.api_key = api_key
-        self.api_version = api_version
-        self.units = units
-        self.lang = lang
-
-    async def get_weather(self, lat, lon) -> WeatherReport:
-        url = self._get_url(lat, lon)
-        json_response = await self.http_client.request(url)
-
-        current, minutely, hourly, daily = None, [], [], []
-        if json_response.get('current') is not None:
-            current = DataConverter.onecall_to_current_weather(json_response['current'])
-        if json_response.get('minutely') is not None:
-            minutely = [DataConverter.onecall_to_minutely_weather_forecast(item) for item in json_response['minutely']]
-        if json_response.get('hourly') is not None:
-            hourly = [DataConverter.onecall_to_hourly_weather_forecast(item) for item in json_response['hourly']]
-        if json_response.get('daily') is not None:
-            daily = [DataConverter.onecall_to_daily_weather_forecast(item) for item in json_response['daily']]
-
-        return WeatherReport(current, minutely, hourly, daily)
-
-    async def get_air_pollution(self, lat, lon) -> AirPollutionReport:
-        raise NotImplementedError('free client does not have get_air_pollution()')
-
-    async def validate_key(self) -> bool:
-        url = (f"{self._get_url(50.06, 14.44)}"
-              f"&exclude=current,minutely,hourly,daily,alerts)")
-        try:
-            await self.http_client.request(url)
-            return True
-        except UnauthorizedError:
-            return False
-
-    def _get_url(self, lat, lon):
-        return (f"{API_URL}?"
-                f"lat={lat}&"
-                f"lon={lon}&"
-                f"appid={self.api_key}&"
-                f"units={self.units}&"
-                f"lang={self.lang}")

pyopenweathermap-0.2.2/src/pyopenweathermap/http_client.py

@@ -1,36 +0,0 @@
-from aiohttp import ClientSession
-
-from .exception import UnauthorizedError, RequestError, TooManyRequestsError
-import logging
-
-class HttpClient:
-    request_timeout: int
-    logger = logging.getLogger(__name__)
-
-    def __init__(self, request_timeout=20):
-        self.request_timeout = request_timeout    
-    
-    async def request(self, url):
-        self.logger.debug('Requesting url: ' + url)
-        async with ClientSession() as session:
-            try:
-                async with session.get(url=url, timeout=self.request_timeout) as response:
-                    response_json = await response.json()
-                    if response.status == 200:
-                        return response_json
-                    elif response.status == 400:
-                        raise RequestError(response_json.get('message'))
-                    elif response.status == 401:
-                        raise UnauthorizedError(response_json.get('message'))
-                    elif response.status == 404:
-                        raise RequestError(response_json.get('message'))
-                    elif response.status == 429:
-                        raise TooManyRequestsError(response_json.get('message'))
-                    else:
-                        raise RequestError("Unknown status code: {}".format(response.status))
-            except RequestError as error:
-                raise error
-            except TimeoutError:
-                raise RequestError("Request timeout")
-            except Exception as error:
-                raise RequestError(error) from error