leneda-client 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

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/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/version.py

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

{leneda_client-0.2.0.dist-info → leneda_client-0.4.0.dist-info}/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+leneda/__init__.py,sha256=-BHIXBfTTbX6EKDHr2Bq7rPzsPNYrrkgs9AJqWJR_1Q,732
+leneda/client.py,sha256=RcANz6UweQ13fJHKwWP1V5dWnqSwcG4Ot9ws1grhZqQ,12250
+leneda/exceptions.py,sha256=q00gjI5VwXAMF2I1gXfQidZMzbCF6UOSo4i1Wnb-inU,460
+leneda/models.py,sha256=jdU2cIZZDExUSiSfz9zaYjJepr0m3v_x5b1fyOaEI8Q,7930
+leneda/obis_codes.py,sha256=VfsJQN1U80eZ5g1bIteDCLkkmBQ0AIkkm_zNAeM1Dog,7507
+leneda/version.py,sha256=e6aGg4sxTYiyshAbW98gDoekO-J6qYKpZNzhVZhaYUk,50
+leneda_client-0.4.0.dist-info/licenses/LICENSE,sha256=nAhDs625lK6v8oLqjWCABKBKlwxVoRDFXQvoZPfOtKQ,1062
+leneda_client-0.4.0.dist-info/METADATA,sha256=TGPWdTziOm6yt9HLE8GKtbDxUaU-N9GHcNH9vsAbdzw,3344
+leneda_client-0.4.0.dist-info/WHEEL,sha256=0CuiUZ_p9E4cD6NyLD6UG80LBXYyiSYZOKDm5lp32xk,91
+leneda_client-0.4.0.dist-info/top_level.txt,sha256=PANScm25ep7WLjKiph0fhJPb8s_sa_uLHemnBpQBaJ8,7
+leneda_client-0.4.0.dist-info/RECORD,,

{leneda_client-0.2.0.dist-info → leneda_client-0.4.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (78.1.1)
+Generator: setuptools (80.3.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

leneda_client-0.4.0.dist-info/licenses/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.dist-info/RECORD

@@ -1,9 +0,0 @@
-leneda/__init__.py,sha256=-BHIXBfTTbX6EKDHr2Bq7rPzsPNYrrkgs9AJqWJR_1Q,732
-leneda/client.py,sha256=NFZczkNkvTBZOSU5FCQ9A_TE_x4s7eX9iKrWqzeubr4,8393
-leneda/models.py,sha256=jdU2cIZZDExUSiSfz9zaYjJepr0m3v_x5b1fyOaEI8Q,7930
-leneda/obis_codes.py,sha256=VfsJQN1U80eZ5g1bIteDCLkkmBQ0AIkkm_zNAeM1Dog,7507
-leneda/version.py,sha256=K2uqgpmNuApS_OV5kcSoshVG9LFQlr-es1HuZALwCq4,50
-leneda_client-0.2.0.dist-info/METADATA,sha256=CqBEdkRXJUCOk9qSKmv9ZBNIgzov_9mroXa5v7i_pcA,1994
-leneda_client-0.2.0.dist-info/WHEEL,sha256=lTU6B6eIfYoiQJTZNc-fyaR6BpL6ehTzU3xGYxn2n8k,91
-leneda_client-0.2.0.dist-info/top_level.txt,sha256=PANScm25ep7WLjKiph0fhJPb8s_sa_uLHemnBpQBaJ8,7
-leneda_client-0.2.0.dist-info/RECORD,,