leneda-client 0.2.0__tar.gz → 0.4.0__tar.gz

leneda_client-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 fedus
+
+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.

{leneda_client-0.2.0 → leneda_client-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: leneda-client
-Version: 0.2.0
+Version: 0.4.0
 Summary: Python client for the Leneda energy data platform
 Home-page: https://github.com/fedus/leneda-client
 Author: fedus
@@ -21,6 +21,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Utilities
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Requires-Dist: requests>=2.25.0
 Requires-Dist: python-dateutil>=2.8.2
 Dynamic: author
@@ -30,6 +31,7 @@ Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
 Dynamic: keywords
+Dynamic: license-file
 Dynamic: project-url
 Dynamic: requires-dist
 Dynamic: requires-python
@@ -37,9 +39,10 @@ Dynamic: summary
 
 # Leneda API Client
 
-[![PyPI version]](https://pypi.org/project/leneda-client/)
-[![Python versions]](https://pypi.org/project/leneda-client/)
-[![License]](https://github.com/fedus/leneda-client/blob/main/LICENSE)
+[![PyPI version](https://img.shields.io/pypi/v/leneda-client.svg)](https://pypi.org/project/leneda-client/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/leneda-client)](https://pypi.org/project/leneda-client/)
+[![License](https://img.shields.io/github/license/fedus/leneda-client)](https://github.com/fedus/leneda-client/blob/main/LICENSE)
+
 
 A Python client for interacting with the Leneda energy data platform API.
 
@@ -56,3 +59,33 @@ This client provides a simple interface to the Leneda API, which allows users to
 
 ```bash
 pip install leneda-client
+```
+
+## Trying it out
+
+```bash
+$ export LENEDA_ENERGY_ID='LUXE-xx-yy-1234'
+$ export LENEDA_API_KEY='YOUR-API-KEY'
+$ python examples/basic_usage.py --metering-point LU0000012345678901234000000000000
+Example 1: Getting hourly electricity consumption data for the last 7 days
+Retrieved 514 consumption measurements
+Unit: kW
+Interval length: PT15M
+Metering point: LU0000012345678901234000000000000
+OBIS code: ObisCode.ELEC_CONSUMPTION_ACTIVE
+
+First 3 measurements:
+Time: 2025-04-18T13:30:00+00:00, Value: 0.048 kW, Type: Actual, Version: 2, Calculated: False
+Time: 2025-04-18T13:45:00+00:00, Value: 0.08 kW, Type: Actual, Version: 2, Calculated: False
+Time: 2025-04-18T14:00:00+00:00, Value: 0.08 kW, Type: Actual, Version: 2, Calculated: False
+
+Example 2: Getting monthly aggregated electricity consumption for 2025
+Retrieved 4 monthly aggregations
+Unit: kWh
+
+Monthly consumption:
+Period: 2024-12 to 2025-01, Value: 30.858 kWh, Calculated: False
+Period: 2025-01 to 2025-02, Value: 148.985 kWh, Calculated: False
+Period: 2025-02 to 2025-03, Value: 44.619 kWh, Calculated: False
+Period: 2025-03 to 2025-04, Value: 29.662 kWh, Calculated: False
+```

leneda_client-0.4.0/README.md

@@ -0,0 +1,52 @@
+# Leneda API Client
+
+[![PyPI version](https://img.shields.io/pypi/v/leneda-client.svg)](https://pypi.org/project/leneda-client/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/leneda-client)](https://pypi.org/project/leneda-client/)
+[![License](https://img.shields.io/github/license/fedus/leneda-client)](https://github.com/fedus/leneda-client/blob/main/LICENSE)
+
+
+A Python client for interacting with the Leneda energy data platform API.
+
+## Overview
+
+This client provides a simple interface to the Leneda API, which allows users to:
+
+- Retrieve metering data for specific time ranges
+- Get aggregated metering data (hourly, daily, weekly, monthly, or total)
+- Create metering data access requests
+- Use predefined OBIS code constants for easy reference
+
+## Installation
+
+```bash
+pip install leneda-client
+```
+
+## Trying it out
+
+```bash
+$ export LENEDA_ENERGY_ID='LUXE-xx-yy-1234'
+$ export LENEDA_API_KEY='YOUR-API-KEY'
+$ python examples/basic_usage.py --metering-point LU0000012345678901234000000000000
+Example 1: Getting hourly electricity consumption data for the last 7 days
+Retrieved 514 consumption measurements
+Unit: kW
+Interval length: PT15M
+Metering point: LU0000012345678901234000000000000
+OBIS code: ObisCode.ELEC_CONSUMPTION_ACTIVE
+
+First 3 measurements:
+Time: 2025-04-18T13:30:00+00:00, Value: 0.048 kW, Type: Actual, Version: 2, Calculated: False
+Time: 2025-04-18T13:45:00+00:00, Value: 0.08 kW, Type: Actual, Version: 2, Calculated: False
+Time: 2025-04-18T14:00:00+00:00, Value: 0.08 kW, Type: Actual, Version: 2, Calculated: False
+
+Example 2: Getting monthly aggregated electricity consumption for 2025
+Retrieved 4 monthly aggregations
+Unit: kWh
+
+Monthly consumption:
+Period: 2024-12 to 2025-01, Value: 30.858 kWh, Calculated: False
+Period: 2025-01 to 2025-02, Value: 148.985 kWh, Calculated: False
+Period: 2025-02 to 2025-03, Value: 44.619 kWh, Calculated: False
+Period: 2025-03 to 2025-04, Value: 29.662 kWh, Calculated: False
+```

{leneda_client-0.2.0 → leneda_client-0.4.0}/src/leneda/client.py

@@ -7,11 +7,12 @@ energy consumption and production data for electricity and gas.
 
 import json
 import logging
-from datetime import datetime
+from datetime import datetime, timedelta
 from typing import Any, Dict, List, Optional, Union
 
 import requests
 
+from .exceptions import ForbiddenException, UnauthorizedException
 from .models import (
     AggregatedMeteringData,
     MeteringData,
@@ -70,6 +71,12 @@ class LenedaClient:
 
         Returns:
             The JSON response from the API
+
+        Raises:
+            UnauthorizedException: If the API returns a 401 status code
+            ForbiddenException: If the API returns a 403 status code
+            requests.exceptions.RequestException: For other request errors
+            json.JSONDecodeError: If the response cannot be parsed as JSON
         """
         url = f"{self.BASE_URL}/{endpoint}"
 
@@ -87,6 +94,14 @@ class LenedaClient:
             )
 
             # Check for HTTP errors
+            if response.status_code == 401:
+                raise UnauthorizedException(
+                    "API authentication failed. Please check your API key and energy ID."
+                )
+            if response.status_code == 403:
+                raise ForbiddenException(
+                    "Access forbidden. This may be due to Leneda's geoblocking or other access restrictions."
+                )
             response.raise_for_status()
 
             # Parse the response
@@ -234,3 +249,72 @@ class LenedaClient:
         response_data = self._make_request(method="POST", endpoint=endpoint, json_data=data)
 
         return response_data
+
+    def probe_metering_point_obis_code(self, metering_point_code: str, obis_code: ObisCode) -> bool:
+        """
+        Probe if a metering point provides data for a specific OBIS code.
+
+        NOTE: This method is essentially a best guess since the Leneda API does not provide a way to check
+        if a metering point provides data for a specific OBIS code or whether a metering point code is valid
+
+        This method checks if a metering point provides data for the specified OBIS code by making a request
+        for aggregated metering data. If the unit property in the response is null, it indicates that either:
+        - The metering point is invalid, or
+        - The metering point does not provide data for the specified OBIS code
+
+        Args:
+            metering_point_code: The metering point code to probe
+            obis_code: The OBIS code to check for data availability
+
+        Returns:
+            bool: True if the metering point provides data for the specified OBIS code, False otherwise
+
+        Raises:
+            UnauthorizedException: If the API returns a 401 status code
+            ForbiddenException: If the API returns a 403 status code
+            requests.exceptions.RequestException: For other request errors
+        """
+        # Use arbitrary time window
+        end_date = datetime.now()
+        start_date = end_date - timedelta(weeks=4)
+
+        # Try to get aggregated data for the specified OBIS code
+        result = self.get_aggregated_metering_data(
+            metering_point_code=metering_point_code,
+            obis_code=obis_code,
+            start_date=start_date,
+            end_date=end_date,
+            aggregation_level="Month",
+            transformation_mode="Accumulation",
+        )
+
+        # Return True if we got data (unit is not None), False otherwise
+        return result.unit is not None
+
+    def get_supported_obis_codes(self, metering_point_code: str) -> List[ObisCode]:
+        """
+        Get all OBIS codes that are supported by a given metering point.
+
+        NOTE: Please see the documentation of the probe_metering_point_obis_code method about best guess
+        behaviour. If this method returns an empty list, chances are high that the metering point code
+        is invalid or that the Energy ID has no access to it.
+
+        This method probes each OBIS code defined in the ObisCode enum to determine
+        which ones are supported by the specified metering point.
+
+        Args:
+            metering_point_code: The metering point code to check
+
+        Returns:
+            List[ObisCode]: A list of OBIS codes that are supported by the metering point
+
+        Raises:
+            UnauthorizedException: If the API returns a 401 status code
+            ForbiddenException: If the API returns a 403 status code
+            requests.exceptions.RequestException: For other request errors
+        """
+        return [
+            obis_code
+            for obis_code in ObisCode
+            if self.probe_metering_point_obis_code(metering_point_code, obis_code)
+        ]

leneda_client-0.4.0/src/leneda/exceptions.py

@@ -0,0 +1,21 @@
+"""
+Custom exceptions for the Leneda API client.
+"""
+
+
+class LenedaException(Exception):
+    """Base exception for all Leneda API client exceptions."""
+
+    pass
+
+
+class UnauthorizedException(LenedaException):
+    """Raised when API authentication fails (401 Unauthorized)."""
+
+    pass
+
+
+class ForbiddenException(LenedaException):
+    """Raised when access is forbidden (403 Forbidden), typically due to geoblocking or other access restrictions."""
+
+    pass

{leneda_client-0.2.0 → leneda_client-0.4.0}/src/leneda/version.py

@@ -1,3 +1,3 @@
 """Version information."""
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"

{leneda_client-0.2.0 → leneda_client-0.4.0}/src/leneda_client.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: leneda-client
-Version: 0.2.0
+Version: 0.4.0
 Summary: Python client for the Leneda energy data platform
 Home-page: https://github.com/fedus/leneda-client
 Author: fedus
@@ -21,6 +21,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Utilities
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Requires-Dist: requests>=2.25.0
 Requires-Dist: python-dateutil>=2.8.2
 Dynamic: author
@@ -30,6 +31,7 @@ Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
 Dynamic: keywords
+Dynamic: license-file
 Dynamic: project-url
 Dynamic: requires-dist
 Dynamic: requires-python
@@ -37,9 +39,10 @@ Dynamic: summary
 
 # Leneda API Client
 
-[![PyPI version]](https://pypi.org/project/leneda-client/)
-[![Python versions]](https://pypi.org/project/leneda-client/)
-[![License]](https://github.com/fedus/leneda-client/blob/main/LICENSE)
+[![PyPI version](https://img.shields.io/pypi/v/leneda-client.svg)](https://pypi.org/project/leneda-client/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/leneda-client)](https://pypi.org/project/leneda-client/)
+[![License](https://img.shields.io/github/license/fedus/leneda-client)](https://github.com/fedus/leneda-client/blob/main/LICENSE)
+
 
 A Python client for interacting with the Leneda energy data platform API.
 
@@ -56,3 +59,33 @@ This client provides a simple interface to the Leneda API, which allows users to
 
 ```bash
 pip install leneda-client
+```
+
+## Trying it out
+
+```bash
+$ export LENEDA_ENERGY_ID='LUXE-xx-yy-1234'
+$ export LENEDA_API_KEY='YOUR-API-KEY'
+$ python examples/basic_usage.py --metering-point LU0000012345678901234000000000000
+Example 1: Getting hourly electricity consumption data for the last 7 days
+Retrieved 514 consumption measurements
+Unit: kW
+Interval length: PT15M
+Metering point: LU0000012345678901234000000000000
+OBIS code: ObisCode.ELEC_CONSUMPTION_ACTIVE
+
+First 3 measurements:
+Time: 2025-04-18T13:30:00+00:00, Value: 0.048 kW, Type: Actual, Version: 2, Calculated: False
+Time: 2025-04-18T13:45:00+00:00, Value: 0.08 kW, Type: Actual, Version: 2, Calculated: False
+Time: 2025-04-18T14:00:00+00:00, Value: 0.08 kW, Type: Actual, Version: 2, Calculated: False
+
+Example 2: Getting monthly aggregated electricity consumption for 2025
+Retrieved 4 monthly aggregations
+Unit: kWh
+
+Monthly consumption:
+Period: 2024-12 to 2025-01, Value: 30.858 kWh, Calculated: False
+Period: 2025-01 to 2025-02, Value: 148.985 kWh, Calculated: False
+Period: 2025-02 to 2025-03, Value: 44.619 kWh, Calculated: False
+Period: 2025-03 to 2025-04, Value: 29.662 kWh, Calculated: False
+```

{leneda_client-0.2.0 → leneda_client-0.4.0}/src/leneda_client.egg-info/SOURCES.txt

@@ -1,3 +1,4 @@
+LICENSE
 MANIFEST.in
 README.md
 pyproject.toml
@@ -7,6 +8,7 @@ examples/advanced_usage.py
 examples/basic_usage.py
 src/leneda/__init__.py
 src/leneda/client.py
+src/leneda/exceptions.py
 src/leneda/models.py
 src/leneda/obis_codes.py
 src/leneda/version.py

{leneda_client-0.2.0 → leneda_client-0.4.0}/tests/test_client.py

@@ -14,6 +14,10 @@ import requests
 sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
 
 from src.leneda import LenedaClient
+from src.leneda.exceptions import (
+    ForbiddenException,
+    UnauthorizedException,
+)
 from src.leneda.models import (
     AggregatedMeteringData,
     AggregatedMeteringValue,
@@ -220,9 +224,51 @@ class TestLenedaClient(unittest.TestCase):
             },
         )
 
+    @patch("requests.request")
+    def test_unauthorized_error(self, mock_request):
+        """Test handling of 401 Unauthorized errors."""
+        # Set up the mock response with 401 status
+        mock_response = MagicMock()
+        mock_response.status_code = 401
+        mock_response.content = b"Unauthorized"
+        mock_request.return_value = mock_response
+
+        # Call the method and check that it raises UnauthorizedException
+        with self.assertRaises(UnauthorizedException) as context:
+            self.client.get_metering_data(
+                "LU-METERING_POINT1",
+                ObisCode.ELEC_CONSUMPTION_ACTIVE,
+                "2023-01-01T00:00:00Z",
+                "2023-01-02T00:00:00Z",
+            )
+
+        # Check the error message
+        self.assertIn("API authentication failed", str(context.exception))
+
+    @patch("requests.request")
+    def test_forbidden_error(self, mock_request):
+        """Test handling of 403 Forbidden errors."""
+        # Set up the mock response with 403 status
+        mock_response = MagicMock()
+        mock_response.status_code = 403
+        mock_response.content = b"Forbidden"
+        mock_request.return_value = mock_response
+
+        # Call the method and check that it raises ForbiddenException
+        with self.assertRaises(ForbiddenException) as context:
+            self.client.get_metering_data(
+                "LU-METERING_POINT1",
+                ObisCode.ELEC_CONSUMPTION_ACTIVE,
+                "2023-01-01T00:00:00Z",
+                "2023-01-02T00:00:00Z",
+            )
+
+        # Check the error message
+        self.assertIn("geoblocking", str(context.exception))
+
     @patch("requests.request")
     def test_error_handling(self, mock_request):
-        """Test error handling."""
+        """Test error handling for other HTTP errors."""
         # Set up the mock response to raise an exception
         mock_request.side_effect = requests.exceptions.HTTPError("404 Client Error")
 
@@ -235,6 +281,103 @@ class TestLenedaClient(unittest.TestCase):
                 "2023-01-02T00:00:00Z",
             )
 
+    @patch("requests.request")
+    def test_probe_metering_point_obis_code_valid(self, mock_request):
+        """Test probe_metering_point_obis_code with a valid metering point and OBIS code."""
+        # Set up the mock response with valid data
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.json.return_value = {"unit": "kWh", "aggregatedTimeSeries": []}
+        mock_response.content = json.dumps(mock_response.json.return_value).encode()
+        mock_request.return_value = mock_response
+
+        # Call the method
+        result = self.client.probe_metering_point_obis_code(
+            "LU-METERING_POINT1", ObisCode.ELEC_CONSUMPTION_ACTIVE
+        )
+
+        # Check the result
+        self.assertTrue(result)
+
+        # Check that the request was made correctly
+        mock_request.assert_called_once()
+
+    @patch("requests.request")
+    def test_probe_metering_point_obis_code_invalid(self, mock_request):
+        """Test probe_metering_point_obis_code with an invalid metering point or unsupported OBIS code."""
+        # Set up the mock response with null unit
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.json.return_value = {"unit": None, "aggregatedTimeSeries": []}
+        mock_response.content = json.dumps(mock_response.json.return_value).encode()
+        mock_request.return_value = mock_response
+
+        # Call the method
+        result = self.client.probe_metering_point_obis_code(
+            "INVALID-METERING-POINT", ObisCode.ELEC_CONSUMPTION_ACTIVE
+        )
+
+        # Check the result
+        self.assertFalse(result)
+
+        # Check that the request was made correctly
+        mock_request.assert_called_once()
+
+    @patch("requests.request")
+    def test_get_supported_obis_codes(self, mock_request):
+        """Test getting supported OBIS codes for a metering point."""
+
+        # Set up the mock response to return different results for different OBIS codes
+        def mock_response_side_effect(*args, **kwargs):
+            mock_response = MagicMock()
+            mock_response.status_code = 200
+
+            # Check which OBIS code is being probed
+            obis_code = kwargs.get("params", {}).get("obisCode")
+            if obis_code == ObisCode.ELEC_CONSUMPTION_ACTIVE.value:
+                mock_response.json.return_value = {"unit": "kWh", "aggregatedTimeSeries": []}
+            elif obis_code == ObisCode.ELEC_PRODUCTION_ACTIVE.value:
+                mock_response.json.return_value = {"unit": "kWh", "aggregatedTimeSeries": []}
+            else:
+                mock_response.json.return_value = {"unit": None, "aggregatedTimeSeries": []}
+
+            mock_response.content = json.dumps(mock_response.json.return_value).encode()
+            return mock_response
+
+        mock_request.side_effect = mock_response_side_effect
+
+        # Call the method
+        result = self.client.get_supported_obis_codes("LU-METERING_POINT1")
+
+        # Check the result
+        self.assertIsInstance(result, list)
+        self.assertEqual(len(result), 2)  # We expect 2 supported OBIS codes
+        self.assertIn(ObisCode.ELEC_CONSUMPTION_ACTIVE, result)
+        self.assertIn(ObisCode.ELEC_PRODUCTION_ACTIVE, result)
+
+        # Check that the request was made for each OBIS code
+        self.assertEqual(mock_request.call_count, len(ObisCode))
+
+    @patch("requests.request")
+    def test_get_supported_obis_codes_none(self, mock_request):
+        """Test getting supported OBIS codes when none are supported."""
+        # Set up the mock response to return null unit for all OBIS codes
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.json.return_value = {"unit": None, "aggregatedTimeSeries": []}
+        mock_response.content = json.dumps(mock_response.json.return_value).encode()
+        mock_request.return_value = mock_response
+
+        # Call the method
+        result = self.client.get_supported_obis_codes("INVALID-METERING-POINT")
+
+        # Check the result
+        self.assertIsInstance(result, list)
+        self.assertEqual(len(result), 0)  # No supported OBIS codes
+
+        # Check that the request was made for each OBIS code
+        self.assertEqual(mock_request.call_count, len(ObisCode))
+
 
 if __name__ == "__main__":
     unittest.main()

leneda_client-0.2.0/README.md

@@ -1,21 +0,0 @@
-# Leneda API Client
-
-[![PyPI version]](https://pypi.org/project/leneda-client/)
-[![Python versions]](https://pypi.org/project/leneda-client/)
-[![License]](https://github.com/fedus/leneda-client/blob/main/LICENSE)
-
-A Python client for interacting with the Leneda energy data platform API.
-
-## Overview
-
-This client provides a simple interface to the Leneda API, which allows users to:
-
-- Retrieve metering data for specific time ranges
-- Get aggregated metering data (hourly, daily, weekly, monthly, or total)
-- Create metering data access requests
-- Use predefined OBIS code constants for easy reference
-
-## Installation
-
-```bash
-pip install leneda-client