feat(statistics): initial support

sunweg/api.py

@@ -1,20 +1,21 @@
 """API Helper."""
 import json
-from datetime import datetime
+from datetime import date, datetime
 from typing import Any
 
 from requests import Response, session
 
 from .const import (
     SUNWEG_INVERTER_DETAIL_PATH,
     SUNWEG_LOGIN_PATH,
+    SUNWEG_MONTH_STATS_PATH,
     SUNWEG_PLANT_DETAIL_PATH,
     SUNWEG_PLANT_LIST_PATH,
     SUNWEG_URL,
 )
 from .device import MPPT, Inverter, Phase, String
 from .plant import Plant
-from .util import Status
+from .util import ProductionStats, Status
 
 
 class SunWegApiError(RuntimeError):
@@ -270,6 +271,51 @@ def complete_inverter(self, inverter: Inverter, retry=True) -> None:
                 self.authenticate()
                 self.complete_inverter(inverter, False)
 
+    def month_stats_production(self, year: int, month: int, plant: Plant, inverter: Inverter | None = None, retry: bool = True) -> list[ProductionStats]:
+        """
+        Retrieve month energy production statistics.
+
+        :param year: statistics year
+        :type year: int
+        :param month: statistics month
+        :type month: int
+        :param plant: statistics plant
+        :type plant: Plant
+        :param inverter: statistics inverter, None for every inverter
+        :type inverter: Inverter | None
+        :param retry: reauthenticate if token expired and retry
+        :type retry: bool
+        :return: list of daily energy production statistics
+        :rtype: list[ProductionStats]
+        """
+        return self.month_stats_production(year, month, plant.id, inverter.id if inverter is not None else None, retry)
+
+    def month_stats_production(self, year: int, month: int, plant_id: int, inverter_id: int | None = None, retry: bool = True) -> list[ProductionStats]:
+        """
+        Retrieve month energy production statistics.
+
+        :param year: statistics year
+        :type year: int
+        :param month: statistics month
+        :type month: int
+        :param plant_id: id of statistics plant
+        :type plant_id: int
+        :param inverter_id: id of statistics inverter, None for every inverter
+        :type inverter_id: int | None
+        :param retry: reauthenticate if token expired and retry
+        :type retry: bool
+        :return: list of daily energy production statistics
+        :rtype: list[ProductionStats]
+        """
+        inverter_str:str = str(inverter_id) if inverter_id is not None else ""
+        try:
+            result = self._get(SUNWEG_MONTH_STATS_PATH + f"idusina={plant_id}&idinversor={inverter_str}&date={format(month,'02')}/{year}")
+            return [ProductionStats(datetime.strptime(item["tempoatual"],"%Y-%m-%d").date(), float(item["energiapordia"]), float(item["prognostico"])) for item in result["graficomes"]]
+        except LoginError:
+            if retry:
+                self.authenticate()
+                self.month_stats_production(year, month, plant_id, inverter_id, False)
+
     def _populate_MPPT(self, result: dict, inverter: Inverter) -> None:
         """Populate MPPT information inside a inverter."""
         for str_mppt in result["stringmppt"]:

sunweg/const.py

@@ -14,3 +14,5 @@
 """SunWEG API plant details path"""
 SUNWEG_INVERTER_DETAIL_PATH = "inversores/view?id="
 """SunWEG API inverter details path"""
+SUNWEG_MONTH_STATS_PATH = "usinas/getgraficomes?"
+"""SunWEG API month history path"""

sunweg/util.py

@@ -1,4 +1,5 @@
 """Sunweg API util."""
+from datetime import date
 from enum import Enum
 
 
@@ -8,3 +9,38 @@ class Status(Enum):
     OK = 0
     WARN = 2
     ERROR = 1
+
+class ProductionStats:
+    """Energy production statistics"""
+    def __init__(self, date:date, production:float, prognostic:float) -> None:
+        """
+        Initialize energy production statistics.
+        
+        :param date: statistics date
+        :type date: date
+        :param production: statistics production in kWh
+        :type production: float
+        :param prognostic: statistics expected production in kWh
+        """
+        self._date = date
+        self._production = production
+        self._prognostic = prognostic
+
+    @property
+    def date(self) -> date:
+        """Get date."""
+        return self._date
+
+    @property
+    def production(self) -> float:
+        """Get energy production in kWh."""
+        return self._production
+
+    @property
+    def prognostic(self) -> float:
+        """Get expected energy production in kWh."""
+        return self._prognostic
+
+    def __str__(self) -> str:
+        """Cast Phase to str."""
+        return str(self.__class__) + ": " + str(self.__dict__)

tests/responses/month_stats_fail_response.json

@@ -0,0 +1,4 @@
+{
+  "success": false,
+  "message": "Error message"
+}