Release 0.2.0: periods API, get_periods(), period_index for yearly reset

- Add get_periods() and Period model; optional period_index on meter/current/monthly methods
- Document per-period semantics and yearly reset in docstrings and README
- Bump version to 0.2.0

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: fjfricke

README.md

@@ -104,11 +104,15 @@ async def fetch():
 Key methods:
 - `BrunataClient.login()`
 - `BrunataClient.get_account()`
+- `BrunataClient.get_periods()` – list of dashboard periods (start/end); use to see which year a value belongs to
 - `BrunataClient.get_supported_cost_types()`
 - `BrunataClient.get_readings(...)`
-- `BrunataClient.get_monthly_consumption(cost_type=..., in_kwh=...)`
-- `BrunataClient.get_monthly_consumptions(kind, in_kwh=...)` (all matching cost types)
-- `BrunataClient.get_meter_readings()` (all `HZ..` and `WW..`, keyed by `cost_type`)
+- `BrunataClient.get_monthly_consumption(cost_type=..., in_kwh=..., period_index=...)`
+- `BrunataClient.get_monthly_consumptions(kind, in_kwh=..., period_index=...)`
+- `BrunataClient.get_meter_readings(period_index=...)` (all `HZ..` and `WW..`, keyed by `cost_type`)
+- `BrunataClient.get_current_consumption(kind, period_index=...)` (YTD for the selected period)
+
+**Periods and yearly reset:** The portal exposes data per dashboard period (usually one per calendar year). Cumulative values (meter reading, “current consumption”) are **per period** and typically **reset when a new year starts**. Default is `period_index=0` (first period, often the current year). Use `get_periods()` to list periods and `period_index` to request a specific one (e.g. `period_index=1` for the previous year). Integrations (e.g. Home Assistant) can use this to show “2024 total” vs “2025 YTD” or to handle the reset (e.g. new sensor per year or state_class per period).
 
 ## Development
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "brunata-nutzerportal-api"
-version = "0.1.4"
+version = "0.2.0"
 description = "Async client for BRUdirekt (Brunata) portal"
 authors = [
     {name = "Felix Fricke"}

src/brunata_api/__init__.py

@@ -3,7 +3,7 @@
 from importlib.metadata import PackageNotFoundError, version
 
 from .client import BrunataClient
-from .models import Reading, ReadingKind
+from .models import CurrentConsumption, MeterReading, Period, Reading, ReadingKind
 
 
 def __getattr__(name: str):  # pragma: no cover
@@ -15,5 +15,13 @@ def __getattr__(name: str):  # pragma: no cover
     raise AttributeError(name)
 
 
-__all__ = ["BrunataClient", "Reading", "ReadingKind", "__version__"]
+__all__ = [
+    "BrunataClient",
+    "CurrentConsumption",
+    "MeterReading",
+    "Period",
+    "Reading",
+    "ReadingKind",
+    "__version__",
+]
 

src/brunata_api/client.py

@@ -13,7 +13,7 @@
 import httpx
 
 from .errors import LoginError
-from .models import CurrentConsumption, MeterReading, Reading, ReadingKind
+from .models import CurrentConsumption, MeterReading, Period, Reading, ReadingKind
 
 
 def _default_headers() -> dict[str, str]:
@@ -495,16 +495,45 @@ async def get_dashboard_dates(self) -> dict[str, Any]:
         )
         return await self._dashboard_batch_get(rel)
 
+    async def get_periods(self) -> list[Period]:
+        """
+        Return all dashboard periods (e.g. calendar years) as start/end datetimes.
+
+        Useful for integrations to show "which year" a value belongs to or to request
+        a specific period via period_index. Values from meter/current consumption are
+        per-period and typically reset when a new period (e.g. new year) starts.
+        """
+        dates = await self.get_dashboard_dates()
+        results = (dates.get("d") or {}).get("results") or []
+        out: list[Period] = []
+        for p in results:
+            if not isinstance(p, dict):
+                continue
+            ab_raw = p.get("Abdatum")
+            bis_raw = p.get("Bisdatum")
+            if not isinstance(ab_raw, str) or not isinstance(bis_raw, str):
+                continue
+            start = self._sap_date_to_datetime(ab_raw)
+            end = self._sap_date_to_datetime(bis_raw)
+            if start and end:
+                out.append(Period(start=start, end=end))
+        return out
+
     @staticmethod
     def _parse_sap_number(value: str) -> float:
         # Values may be padded with spaces and use dot decimals.
         return float(value.strip().replace(",", "."))
 
-    async def get_meter_reading(self, *, cost_type: str) -> MeterReading:
+    async def get_meter_reading(
+        self, *, cost_type: str, period_index: int = 0
+    ) -> MeterReading:
         """
         Get the cumulative meter/index value (Zählerstand) for a cost type.
 
-        Uses `NP_DASHBOARD_SRV/CumuConsumptionSet`.
+        Uses `NP_DASHBOARD_SRV/CumuConsumptionSet`. Values are per dashboard period
+        (e.g. calendar year); they typically reset when a new period starts. Use
+        get_periods() to list periods and period_index to request a specific one
+        (0 = first, often the current period).
         """
         if not self._logged_in:
             await self.login()
@@ -513,12 +542,14 @@ async def get_meter_reading(self, *, cost_type: str) -> MeterReading:
 
         dates = await self.get_dashboard_dates()
         results = (dates.get("d") or {}).get("results") or []
-        if not results:
+        periods_list = [p for p in results if isinstance(p, dict)]
+        if not periods_list:
             raise LoginError("No dashboard periods found.")
-
-        period = next((p for p in results if isinstance(p, dict)), None)
-        if not period:
-            raise LoginError("No dashboard period object found.")
+        if period_index < 0 or period_index >= len(periods_list):
+            raise LoginError(
+                f"period_index {period_index} out of range (0..{len(periods_list) - 1})."
+            )
+        period = periods_list[period_index]
 
         bis_raw = period.get("Bisdatum")
         if not isinstance(bis_raw, str):
@@ -563,17 +594,21 @@ async def get_meter_reading(self, *, cost_type: str) -> MeterReading:
             kind=kind,
         )
 
-    async def get_meter_readings(self) -> dict[str, MeterReading]:
+    async def get_meter_readings(
+        self, *, period_index: int = 0
+    ) -> dict[str, MeterReading]:
         """
-        Convenience helper: return meter readings for *all* HZ.. and WW.. cost types.
+        Return meter readings for *all* HZ.. and WW.. cost types in the given period.
 
-        Output is keyed by `cost_type` (stable mapping for HA entity IDs).
+        Output is keyed by `cost_type`. Values are per-period and may reset each year.
+        Use period_index to select period (0 = first, e.g. current year).
         """
         dates = await self.get_dashboard_dates()
         results = (dates.get("d") or {}).get("results") or []
-        period = next((p for p in results if isinstance(p, dict)), None)
-        if not period:
+        periods_list = [p for p in results if isinstance(p, dict)]
+        if not periods_list or period_index < 0 or period_index >= len(periods_list):
             return {}
+        period = periods_list[period_index]
 
         unit_rows = ((period.get("Units") or {}).get("results") or [])
         all_cost_types = sorted(
@@ -587,7 +622,9 @@ async def get_meter_readings(self) -> dict[str, MeterReading]:
 
         out: dict[str, MeterReading] = {}
         for ct in wanted:
-            out[ct] = await self.get_meter_reading(cost_type=ct)
+            out[ct] = await self.get_meter_reading(
+                cost_type=ct, period_index=period_index
+            )
         return out
 
     async def get_supported_cost_types(self) -> dict[str, set[str]]:
@@ -618,9 +655,13 @@ async def get_monthly_consumption(
         *,
         cost_type: str,
         in_kwh: bool = True,
+        period_index: int | None = None,
     ) -> list[Reading]:
         """
         Fetch monthly consumption series for a given CostType (e.g. HZ01, WW01).
+
+        If period_index is None, tries all periods and returns the first with data.
+        If set, only that period is queried (0 = first, e.g. current year).
         """
         kind = ReadingKind.heating if cost_type.startswith("HZ") else ReadingKind.hot_water
         if not self._logged_in:
@@ -630,9 +671,15 @@ async def get_monthly_consumption(
 
         dates = await self.get_dashboard_dates()
         results = (dates.get("d") or {}).get("results") or []
-        periods: list[dict[str, Any]] = [p for p in results if isinstance(p, dict)]
+        periods_list: list[dict[str, Any]] = [
+            p for p in results if isinstance(p, dict)
+        ]
+        if period_index is not None:
+            if period_index < 0 or period_index >= len(periods_list):
+                return []
+            periods_list = [periods_list[period_index]]
 
-        for period in periods:
+        for period in periods_list:
             bis_raw = period.get("Bisdatum")
             if not isinstance(bis_raw, str):
                 continue
@@ -690,17 +737,19 @@ async def get_monthly_consumptions(
         kind: ReadingKind,
         *,
         in_kwh: bool = True,
+        period_index: int = 0,
     ) -> dict[str, list[Reading]]:
         """
         Fetch monthly consumption series for *all* cost types matching `kind`.
 
-        Output is keyed by `cost_type` (e.g. HZ01, HZ02, WW01...).
+        Output is keyed by `cost_type`. Use period_index to select period (0 = first).
         """
         dates = await self.get_dashboard_dates()
         results = (dates.get("d") or {}).get("results") or []
-        period = next((p for p in results if isinstance(p, dict)), None)
-        if not period:
+        periods_list = [p for p in results if isinstance(p, dict)]
+        if not periods_list or period_index < 0 or period_index >= len(periods_list):
             return {}
+        period = periods_list[period_index]
 
         unit_rows = ((period.get("Units") or {}).get("results") or [])
         all_cost_types = sorted(
@@ -715,24 +764,34 @@ async def get_monthly_consumptions(
 
         out: dict[str, list[Reading]] = {}
         for ct in wanted:
-            out[ct] = await self.get_monthly_consumption(cost_type=ct, in_kwh=in_kwh)
+            out[ct] = await self.get_monthly_consumption(
+                cost_type=ct, in_kwh=in_kwh, period_index=period_index
+            )
         return out
 
-    async def get_current_consumption(self, kind: ReadingKind) -> CurrentConsumption:
+    async def get_current_consumption(
+        self, kind: ReadingKind, *, period_index: int = 0
+    ) -> CurrentConsumption:
         """
-        Returns the value shown in the dashboard cards:
-        'aktueller Verbrauch' and 'aktueller Verbrauch vom <date>'.
+        Return the dashboard-style cumulative consumption (e.g. YTD) for the period.
 
-        Implementation: sum the monthly kWh series for the active period.
+        This is the sum of monthly kWh for the selected period, so it resets when a
+        new period (e.g. new year) starts. Use period_index to select period
+        (0 = first, often current year). as_of is the period end date.
         """
         if not self._logged_in:
             await self.login()
 
         dates = await self.get_dashboard_dates()
         results = (dates.get("d") or {}).get("results") or []
-        period = next((p for p in results if isinstance(p, dict)), None)
-        if not period:
+        periods_list = [p for p in results if isinstance(p, dict)]
+        if not periods_list:
             raise LoginError("No dashboard period found.")
+        if period_index < 0 or period_index >= len(periods_list):
+            raise LoginError(
+                f"period_index {period_index} out of range (0..{len(periods_list) - 1})."
+            )
+        period = periods_list[period_index]
 
         bis_raw = period.get("Bisdatum")
         if not isinstance(bis_raw, str):
@@ -753,7 +812,9 @@ async def get_current_consumption(self, kind: ReadingKind) -> CurrentConsumption
         else:
             cost_type = next((ct for ct in cost_types if ct.startswith("WW")), "WW01")
 
-        monthly = await self.get_monthly_consumption(cost_type=cost_type, in_kwh=True)
+        monthly = await self.get_monthly_consumption(
+            cost_type=cost_type, in_kwh=True, period_index=period_index
+        )
         total = round(sum(r.value for r in monthly), 3)
         return CurrentConsumption(
             as_of=as_of,

src/brunata_api/models.py

@@ -35,6 +35,13 @@ class MeterReading(BaseModel):
     kind: ReadingKind
 
 
+class Period(BaseModel):
+    """A dashboard period (e.g. calendar year) with start and end dates."""
+
+    start: datetime = Field(..., description="Period start (Abdatum).")
+    end: datetime = Field(..., description="Period end (Bisdatum).")
+
+
 class CurrentConsumption(BaseModel):
     """Current cumulative consumption (e.g. year-to-date) shown in the dashboard cards."""
 

tests/test_client.py

@@ -6,7 +6,7 @@
 import httpx
 
 from brunata_api.client import BrunataClient
-from brunata_api.models import MeterReading, Reading, ReadingKind
+from brunata_api.models import MeterReading, Period, Reading, ReadingKind
 
 
 def test_extract_json_objects_finds_embedded_json():
@@ -61,6 +61,31 @@ async def fake_get_dashboard_dates():
     assert out["/Date(1704067200000)/"] == {"HZ01", "WW01"}
 
 
+def test_get_periods_returns_parsed_periods_without_network():
+    client = BrunataClient(base_url="https://example.invalid", username="u", password="p")
+    client._logged_in = True  # avoid login()
+
+    async def fake_get_dashboard_dates():
+        return {
+            "d": {
+                "results": [
+                    {
+                        "Abdatum": "/Date(1704067200000)/",  # 2024-01-01
+                        "Bisdatum": "/Date(1735689599000)/",  # 2024-12-31
+                        "Units": {"results": [{"CostType": "HZ01"}]},
+                    }
+                ]
+            }
+        }
+
+    client.get_dashboard_dates = fake_get_dashboard_dates  # type: ignore[method-assign]
+    out = asyncio.run(client.get_periods())
+    assert len(out) == 1
+    assert isinstance(out[0], Period)
+    assert out[0].start.year == 2024 and out[0].start.month == 1
+    assert out[0].end.year == 2024 and out[0].end.month == 12
+
+
 def test_get_monthly_consumption_without_network():
     client = BrunataClient(base_url="https://example.invalid", username="u", password="p")
     client._logged_in = True
@@ -129,7 +154,9 @@ async def fake_get_dashboard_dates():
             }
         }
 
-    async def fake_get_meter_reading(*, cost_type: str) -> MeterReading:
+    async def fake_get_meter_reading(
+        *, cost_type: str, period_index: int = 0
+    ) -> MeterReading:
         kind = ReadingKind.heating if cost_type.startswith("HZ") else ReadingKind.hot_water
         return MeterReading(
             timestamp=datetime(2025, 1, 1, tzinfo=UTC),
@@ -170,7 +197,9 @@ async def fake_get_dashboard_dates():
 
     seen: list[tuple[str, bool]] = []
 
-    async def fake_get_monthly_consumption(*, cost_type: str, in_kwh: bool = True) -> list[Reading]:
+    async def fake_get_monthly_consumption(
+        *, cost_type: str, in_kwh: bool = True, period_index: int | None = None
+    ) -> list[Reading]:
         seen.append((cost_type, in_kwh))
         kind = ReadingKind.heating if cost_type.startswith("HZ") else ReadingKind.hot_water
         return [