PyHolfuy 0.2__tar.gz → 0.3__tar.gz

{pyholfuy-0.2/pyholfuy.egg-info → pyholfuy-0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyholfuy
-Version: 0.2
+Version: 0.3
 Summary: A Python library for interacting with Holfuy weather stations.
 Author-email: Håvard Dagenborg <haavardj@dagenborg.net>
 License-Expression: MIT
@@ -26,7 +26,7 @@ A Python library for talking to [Holfuy Weather Stations](https://holfuy.com/).
 
 You need an API key to access the service. To obtain one, please visit the [Holfuy API](https://api.holfuy.com/live/) pages.
 
-The Library only access live data.
+The library can only access live data.
 
 ## Example Code
 Here is an example of how to use the library.
@@ -38,10 +38,22 @@ from holfuy import HolfuyService
 
 async def main():
     async with aiohttp.ClientSession() as session:
-    s = HolfuyService("", session)
-    data = await s.fetch_data(["101"])
-    print(data)
+        s = HolfuyService("", session)
+        data = await s.fetch_data(["101"])
+        print(data)
 
 if __name__ == "__main__":
     asyncio.run(main())
 ```
+
+## Return value and errors
+
+`fetch_data()` returns `{"measurements": [...]}` with one entry per station, also when
+a single station is requested. A station the key cannot read is still listed, with
+`error` and `errorCode` instead of data.
+
+It raises, all subclasses of `holfuy.HolfuyError`:
+
+- `HolfuyAuthError`: the API key is rejected, or it has no access to any requested station.
+- `HolfuyConnectionError`: network error, timeout, or an HTTP error status.
+- `HolfuyError`: any other unexpected reply.

pyholfuy-0.3/README.md

@@ -0,0 +1,38 @@
+![Holfy Logo](https://holfuy.com/image/logo/holfuy-logo.png)
+
+# PyHolfuy
+A Python library for talking to [Holfuy Weather Stations](https://holfuy.com/).
+
+You need an API key to access the service. To obtain one, please visit the [Holfuy API](https://api.holfuy.com/live/) pages.
+
+The library can only access live data.
+
+## Example Code
+Here is an example of how to use the library.
+
+```python
+import aiohttp
+import asyncio
+from holfuy import HolfuyService
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        s = HolfuyService("", session)
+        data = await s.fetch_data(["101"])
+        print(data)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Return value and errors
+
+`fetch_data()` returns `{"measurements": [...]}` with one entry per station, also when
+a single station is requested. A station the key cannot read is still listed, with
+`error` and `errorCode` instead of data.
+
+It raises, all subclasses of `holfuy.HolfuyError`:
+
+- `HolfuyAuthError`: the API key is rejected, or it has no access to any requested station.
+- `HolfuyConnectionError`: network error, timeout, or an HTTP error status.
+- `HolfuyError`: any other unexpected reply.

{pyholfuy-0.2 → pyholfuy-0.3}/holfuy/__init__.py

@@ -15,15 +15,23 @@ from .const import (
     CONF_MODE_JSON,
     STATIONS_ALL,
 )
+from .exceptions import HolfuyAuthError, HolfuyConnectionError, HolfuyError
+
+__all__ = [
+    "HolfuyAuthError",
+    "HolfuyConnectionError",
+    "HolfuyError",
+    "HolfuyService",
+]
 
 TIMEOUT = 30
 _LOGGER = logging.getLogger(__name__)
 
-API_URL = "http://api.holfuy.com/live/"
+API_URL = "https://api.holfuy.com/live/"
 
 # noqa: E501
 #### API Description
-# URL Format:  http://api.holfuy.com/live/?s=101&pw=pass&m=JSON&tu=C&su=m/s
+# URL Format:  https://api.holfuy.com/live/?s=101&pw=pass&m=JSON&tu=C&su=m/s
 #
 # s: station(s) ID e.g. s=101 or you can get the data from more stations by one query as well (coma separated list) e.g. s=101,102,103 . If you would get all stations' data (to which you have access) by one single API call please use the "all" string -> s=all .
 # pw: password for the API access (it could be sent by a POST "pw" parameter also)
@@ -68,8 +76,16 @@ class HolfuyService:
         include_battery=False,
         include_daily=False,
         include_location=False,
-    ) -> dict[str, Any] | None:
-        """Get the latest data from Holfuy."""
+    ) -> dict[str, Any]:
+        """Get the latest data from Holfuy.
+
+        Returns {"measurements": [...]}, one entry per station. A station the key
+        cannot read is still listed, with "error" and "errorCode" instead of data.
+
+        Raises HolfuyAuthError if the key is rejected or can read none of the
+        requested stations, HolfuyConnectionError on network errors, timeouts and
+        HTTP errors, and HolfuyError on any other unexpected reply.
+        """
 
         params = {
             "pw": self._api_key,
@@ -97,29 +113,50 @@ class HolfuyService:
             params["s"] = STATIONS_ALL
 
         try:
-
-            async with asyncio.timeout(TIMEOUT):
-                resp = await self._session.get(self._api_url, params=params)
-
-            if resp.status >= 400:
-                _LOGGER.error("%s returned %s", self._api_url, resp.status)
-                return None
-
-            result = await resp.json()
-
-            # Request for a single station is not enveloped in a list of
-            # measurements objects. Make data consistent for all request types before it
-            #  is returned.
-            if stations and len(stations) == 1:
-                result = {"measurements": [result]}
-
-            return result
+            # The timeout covers the whole exchange, body included, and the
+            # context manager releases the connection back to the pool.
+            async with (
+                asyncio.timeout(TIMEOUT),
+                self._session.get(self._api_url, params=params) as resp,
+            ):
+                if resp.status >= 400:
+                    raise HolfuyConnectionError(
+                        f"Holfuy API returned HTTP {resp.status}"
+                    )
+
+                # A rejected key gets HTTP 200 with the plain text "No access".
+                if resp.content_type != "application/json":
+                    text = (await resp.text()).strip()
+                    if text.lower().startswith("no access"):
+                        raise HolfuyAuthError("Holfuy API rejected the API key")
+                    raise HolfuyError(
+                        f"Unexpected response from Holfuy API: {text[:100]!r}"
+                    )
+
+                result = await resp.json()
 
         except (TimeoutError, aiohttp.ClientError) as err:
-            _LOGGER.error(
-                "Access to %s returned error '%s'", self._api_url, type(err).__name__
-            )
-            return None
-        except ValueError:
-            _LOGGER.exception("Unable to parse json response from %s", self._api_url)
-            return None
+            # Only the type name: aiohttp messages can contain the URL, and
+            # with it the API key.
+            raise HolfuyConnectionError(
+                f"Cannot reach Holfuy API: {type(err).__name__}"
+            ) from err
+        except ValueError as err:
+            raise HolfuyError("Unable to parse JSON response from Holfuy API") from err
+
+        # Request for a single station is not enveloped in a list of
+        # measurements objects. Make data consistent for all request types before it
+        # is returned.
+        if stations and len(stations) == 1:
+            result = {"measurements": [result]}
+
+        measurements = result.get("measurements") if isinstance(result, dict) else None
+        if not isinstance(measurements, list):
+            raise HolfuyError("Unexpected response from Holfuy API: no measurements")
+
+        if measurements and all(
+            m.get("errorCode") == "no_access" for m in measurements
+        ):
+            raise HolfuyAuthError("API key has no access to the requested stations")
+
+        return result

{pyholfuy-0.2 → pyholfuy-0.3}/holfuy/const.py

@@ -1,6 +1,6 @@
 CONF_MODE_JSON = "JSON"  # We only handle JSON from the api
-CONF_MODE_XML = "CSV"
-CONF_MODE_CSV = "XML"
+CONF_MODE_XML = "XML"
+CONF_MODE_CSV = "CSV"
 
 CONF_AVERAGING_NEWEST = 0
 CONF_AVERAGING_QUARTERLY = 1
@@ -11,8 +11,8 @@ CONF_WIND_SPEED_UNIT_KMH = "km/h"
 CONF_WIND_SPEED_UNIT_MS = "m/s"
 CONF_WIND_SPEED_UNIT_MPH = "mph"
 
-CONF_TEMPERATURE_UNIT_CELSIUS = "Celsius"
-CONF_TEMPERATURE_UNIT_FAHRENHEIT = "Fahrenheit"
+CONF_TEMPERATURE_UNIT_CELSIUS = "C"
+CONF_TEMPERATURE_UNIT_FAHRENHEIT = "F"
 
 CONF_OPTION_BATT = "batt"
 CONF_OPTION_DAILY = "daily"

pyholfuy-0.3/holfuy/exceptions.py

@@ -0,0 +1,13 @@
+"""Exceptions raised by the Holfuy library."""
+
+
+class HolfuyError(Exception):
+    """Base class for all Holfuy errors, raised as is for unexpected replies."""
+
+
+class HolfuyConnectionError(HolfuyError):
+    """The API could not be reached, timed out or returned an HTTP error."""
+
+
+class HolfuyAuthError(HolfuyError):
+    """The API key was rejected, or it has no access to any requested station."""

{pyholfuy-0.2 → pyholfuy-0.3}/holfuy/test_holfuy.py

@@ -1,6 +1,6 @@
 import asyncio
 from unittest import IsolatedAsyncioTestCase, mock
-from unittest.mock import AsyncMock, patch
+from unittest.mock import AsyncMock, MagicMock, patch
 import json
 
 import aiohttp
@@ -24,7 +24,19 @@ RESP_AUTHERROR=json.loads("""
 {"measurements":[{"stationId":105,"error":"Sorry, you don't have access for this station.","errorCode":"no_access"},
 {"stationId":106,"error":"Sorry, you don't have access for this station.","errorCode":"no_access"}]}""")
 
-from holfuy import HolfuyService
+from holfuy import (
+    HolfuyAuthError,
+    HolfuyConnectionError,
+    HolfuyService,
+)
+
+
+def _get_returning(resp):
+    """Mock session.get() as an async context manager yielding resp."""
+    ctx = MagicMock()
+    ctx.__aenter__ = AsyncMock(return_value=resp)
+    ctx.__aexit__ = AsyncMock(return_value=False)
+    return MagicMock(return_value=ctx)
 
 from holfuy.const import (
     CONF_TEMPERATURE_UNIT_CELSIUS,
@@ -51,9 +63,10 @@ class TestHolfuyService(IsolatedAsyncioTestCase):
 
         mock_resp = AsyncMock()
         mock_resp.status = 200
+        mock_resp.content_type = "application/json"
         mock_resp.json = AsyncMock(return_value=mock_response)
 
-        self.session.get = AsyncMock(return_value=mock_resp)
+        self.session.get = _get_returning(mock_resp)
 
         result = await self.api.fetch_data(["142"])
 
@@ -67,7 +80,7 @@ class TestHolfuyService(IsolatedAsyncioTestCase):
         }
 
         self.session.get.assert_called_once_with(
-            "http://api.holfuy.com/live/",
+            "https://api.holfuy.com/live/",
             params=expected_params
         )
 
@@ -79,8 +92,9 @@ class TestHolfuyService(IsolatedAsyncioTestCase):
 
         mock_resp = AsyncMock()
         mock_resp.status = 200
+        mock_resp.content_type = "application/json"
         mock_resp.json = AsyncMock(return_value=mock_response)
-        self.session.get = AsyncMock(return_value= mock_resp)
+        self.session.get = _get_returning(mock_resp)
 
         result = await self.api.fetch_data(None)
 
@@ -94,7 +108,7 @@ class TestHolfuyService(IsolatedAsyncioTestCase):
         }
 
         self.session.get.assert_called_once_with(
-            "http://api.holfuy.com/live/",
+            "https://api.holfuy.com/live/",
             params=expected_params
         )
 
@@ -105,23 +119,24 @@ class TestHolfuyService(IsolatedAsyncioTestCase):
         mock_resp = AsyncMock()
         mock_resp.status = 404
 
-        self.session.get = AsyncMock(return_value=mock_resp)
+        self.session.get = _get_returning(mock_resp)
 
-        result = await self.api.fetch_data(None)
-
-        self.assertIsNone(result)
+        with self.assertRaises(HolfuyConnectionError):
+            await self.api.fetch_data(None)
 
     async def test_fetch_data_invalid_access_token(self):
         """Test handling of error responses."""
         mock_resp = AsyncMock()
         mock_resp.status = 200
+        mock_resp.content_type = "application/json"
         mock_response =  RESP_AUTHERROR
 
         mock_resp.json = AsyncMock(return_value=mock_response)
 
-        self.session.get = AsyncMock(return_value=mock_resp)
+        self.session.get = _get_returning(mock_resp)
 
-        result = await self.api.fetch_data(["105","106"])
+        with self.assertRaises(HolfuyAuthError):
+            await self.api.fetch_data(["105","106"])
 
         expected_params = {
             "pw": "test_api_key",
@@ -133,24 +148,31 @@ class TestHolfuyService(IsolatedAsyncioTestCase):
         }
 
         self.session.get.assert_called_once_with(
-            "http://api.holfuy.com/live/",
+            "https://api.holfuy.com/live/",
             params=expected_params
         )
 
-        self.assertEqual(result["measurements"][0]["stationId"], 105)
-
     async def test_fetch_data_timeout(self):
         """Test handling of timeout errors."""
-        self.session.get = AsyncMock(side_effect=asyncio.TimeoutError)
+        self.session.get = MagicMock(side_effect=asyncio.TimeoutError)
 
-        result = await self.api.fetch_data(None)
-
-        self.assertIsNone(result)
+        with self.assertRaises(HolfuyConnectionError):
+            await self.api.fetch_data(None)
 
     async def test_fetch_data_client_error(self):
         """Test handling of client errors."""
-        self.session.get = AsyncMock(side_effect=aiohttp.ClientError)
+        self.session.get = MagicMock(side_effect=aiohttp.ClientError)
 
-        result = await self.api.fetch_data(None)
+        with self.assertRaises(HolfuyConnectionError):
+            await self.api.fetch_data(None)
+
+    async def test_fetch_data_rejected_key(self):
+        """A rejected key gets HTTP 200 with a plain-text "No access" body."""
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.content_type = "text/html"
+        mock_resp.text = AsyncMock(return_value="No access")
+        self.session.get = _get_returning(mock_resp)
 
-        self.assertIsNone(result)
+        with self.assertRaises(HolfuyAuthError):
+            await self.api.fetch_data(None)

{pyholfuy-0.2 → pyholfuy-0.3/pyholfuy.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyholfuy
-Version: 0.2
+Version: 0.3
 Summary: A Python library for interacting with Holfuy weather stations.
 Author-email: Håvard Dagenborg <haavardj@dagenborg.net>
 License-Expression: MIT
@@ -26,7 +26,7 @@ A Python library for talking to [Holfuy Weather Stations](https://holfuy.com/).
 
 You need an API key to access the service. To obtain one, please visit the [Holfuy API](https://api.holfuy.com/live/) pages.
 
-The Library only access live data.
+The library can only access live data.
 
 ## Example Code
 Here is an example of how to use the library.
@@ -38,10 +38,22 @@ from holfuy import HolfuyService
 
 async def main():
     async with aiohttp.ClientSession() as session:
-    s = HolfuyService("", session)
-    data = await s.fetch_data(["101"])
-    print(data)
+        s = HolfuyService("", session)
+        data = await s.fetch_data(["101"])
+        print(data)
 
 if __name__ == "__main__":
     asyncio.run(main())
 ```
+
+## Return value and errors
+
+`fetch_data()` returns `{"measurements": [...]}` with one entry per station, also when
+a single station is requested. A station the key cannot read is still listed, with
+`error` and `errorCode` instead of data.
+
+It raises, all subclasses of `holfuy.HolfuyError`:
+
+- `HolfuyAuthError`: the API key is rejected, or it has no access to any requested station.
+- `HolfuyConnectionError`: network error, timeout, or an HTTP error status.
+- `HolfuyError`: any other unexpected reply.

{pyholfuy-0.2 → pyholfuy-0.3}/pyholfuy.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ README.md
 pyproject.toml
 holfuy/__init__.py
 holfuy/const.py
+holfuy/exceptions.py
 holfuy/test_holfuy.py
 pyholfuy.egg-info/PKG-INFO
 pyholfuy.egg-info/SOURCES.txt

{pyholfuy-0.2 → pyholfuy-0.3}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyholfuy"
-version = "0.2"
+version = "0.3"
 description = "A Python library for interacting with Holfuy weather stations."
 authors = [{name="Håvard Dagenborg", email="haavardj@dagenborg.net"}]
 license = "MIT"

pyholfuy-0.2/README.md

@@ -1,26 +0,0 @@
-![Holfy Logo](https://holfuy.com/image/logo/holfuy-logo.png)
-
-# PyHolfuy
-A Python library for talking to [Holfuy Weather Stations](https://holfuy.com/).
-
-You need an API key to access the service. To obtain one, please visit the [Holfuy API](https://api.holfuy.com/live/) pages.
-
-The Library only access live data.
-
-## Example Code
-Here is an example of how to use the library.
-
-```python
-import aiohttp
-import asyncio
-from holfuy import HolfuyService
-
-async def main():
-    async with aiohttp.ClientSession() as session:
-    s = HolfuyService("", session)
-    data = await s.fetch_data(["101"])
-    print(data)
-
-if __name__ == "__main__":
-    asyncio.run(main())
-```