feat: add possibility to PATCH zaehlers via v2 API w/ optional keydate (#235)

* feat: add possibility to PATCH zaehlers via v2 API w/ optional keydate

* mypy

* pylint

* copilot suggestion

nitpick] There is a redundant check for '_zaehler.boModel' immediately after asserting that it is not None. Removing this redundant check could streamline the code.

---------

Co-authored-by: Konstantin <[email protected]>

Author: hf-kklein

src/tmdsclient/client/tmdsclient.py

@@ -383,6 +383,40 @@ async def update_marktlokation(
             result = Marktlokation.model_validate(response_json)
         return result
 
+    async def update_zaehler(
+        self,
+        zaehler_id: uuid.UUID,
+        changes: list[Callable[[Zaehler], None]] | JsonPatch,
+        keydate: AwareDatetime | None = None,
+    ) -> Zaehler:
+        """
+        patch the given zaehler using the changes
+        """
+        session = await self._get_session()
+        zaehler = await self.get_zaehler(zaehler_id, keydate)
+        if zaehler is None:
+            raise ValueError(f"Zaehler with id '{zaehler_id}' not found")
+        patch_document: jsonpatch.JsonPatch
+        if isinstance(changes, list) and len(changes) > 0 and not isinstance(changes[0], dict):
+            # we assume that "not isinstance(changes[0], dict)" == isinstance(changes[0], Callable)
+            patch_document = build_json_patch_document(zaehler, changes)  # type:ignore[arg-type]
+        else:
+            # assume it's the patch itself
+            patch_document = jsonpatch.JsonPatch(changes)
+        request_url = self._config.server_url / "api" / "v2" / "Zaehler" / str(zaehler_id)
+        if keydate is not None:  # if it's None it defaults to now(UTC) on serverside anyway
+            request_url = request_url % {"aenderungsDatum": keydate.isoformat()}
+        request_uuid = uuid.uuid4()
+        _logger.debug("[%s] patching %s with body %s", str(request_uuid), request_url, str(patch_document))
+        async with session.patch(
+            request_url, json=patch_document.patch, headers={"Content-Type": "application/json-patch+json"}
+        ) as response:
+            response.raise_for_status()
+            _logger.debug("[%s] response status: %s", str(request_uuid), response.status)
+            response_json = await response.json()
+            result = Zaehler.model_validate(response_json)
+        return result
+
     async def get_messlokation(self, messlokation_id: str) -> Messlokation | None:
         """
         provide a Messlokation-ID, get the matching MeLo in return (or None, if 404)
@@ -402,12 +436,14 @@ async def get_messlokation(self, messlokation_id: str) -> Messlokation | None:
             result = Messlokation.model_validate(response_json)
         return result
 
-    async def get_zaehler(self, zaehler_id: uuid.UUID) -> Zaehler | None:
+    async def get_zaehler(self, zaehler_id: uuid.UUID, keydate: AwareDatetime | None = None) -> Zaehler | None:
         """
         provide a Zaehler-ID, get the matching Zaehler in return (or None, if 404)
         """
         session = await self._get_session()
         request_url = self._config.server_url / "api" / "Zaehler" / str(zaehler_id)
+        if keydate is not None:
+            request_url = request_url / keydate.isoformat()
         request_uuid = uuid.uuid4()
         _logger.debug("[%s] requesting %s", str(request_uuid), request_url)
         async with session.get(request_url) as response:

unittests/test_zaehler.py

@@ -1,8 +1,12 @@
 import uuid
+from datetime import UTC, datetime
 
-from aioresponses import aioresponses
+from aioresponses import CallbackResult, aioresponses
+from bo4e import Sparte
+from jsonpatch import JsonPatch  # type:ignore[import-untyped]
 
 from tmdsclient.models.zaehler import Zaehler
+from tmdsclient.models.zaehler_bo_model import Zaehlertyp
 
 
 def _get_zaehler_model() -> Zaehler:
@@ -99,3 +103,35 @@ async def test_set_zaehler_schmutzwasser_relevanz(self, tmds_client_with_default
             )
             was_set_successfully = await client.set_schmutzwasser_relevanz(zaehler_id, True)
             assert was_set_successfully is True
+
+    async def test_update_zaehler(self, tmds_client_with_default_auth) -> None:
+        zaehler = _get_zaehler_model()
+        zaehler_json = zaehler.model_dump(mode="json", by_alias=True)
+        zaehler.boModel.sparte = Sparte.WASSER
+        zaehler.boModel.zaehlertyp = Zaehlertyp.DREHSTROMZAEHLER
+        client, tmds_config = tmds_client_with_default_auth
+
+        def change_zaehlertyp_to_wasserzaehler(_zaehler: Zaehler) -> None:
+            assert _zaehler.boModel is not None
+            _zaehler.boModel.zaehlertyp = Zaehlertyp.WASSERZAEHLER
+
+        def patch_endpoint_callback(url, **kwargs):  # pylint:disable=unused-argument
+            request_body = kwargs["json"]
+            json_patch = JsonPatch(request_body)
+            modified_zaehler_json = zaehler_json.copy()
+            result = json_patch.apply(modified_zaehler_json)
+            return CallbackResult(status=200, payload=result)
+
+        with aioresponses() as mocked_tmds:
+            mocked_get_url = f"{tmds_config.server_url}api/Zaehler/{zaehler.id}/2025-01-01T00:00:00+00:00"
+            mocked_tmds.get(mocked_get_url, status=200, payload=zaehler_json)
+            # pylint:disable=line-too-long
+            mocked_patch_url = f"{tmds_config.server_url}api/v2/Zaehler/{zaehler.id}?aenderungsDatum=2025-01-01T00%253A00%253A00%252B00%253A00"
+            mocked_tmds.patch(mocked_patch_url, callback=patch_endpoint_callback)
+            actual = await client.update_zaehler(
+                zaehler.id, [change_zaehlertyp_to_wasserzaehler], datetime(2025, 1, 1, 0, 0, 0).replace(tzinfo=UTC)
+            )
+        assert isinstance(actual, Zaehler)
+        assert actual.boModel is not None
+        assert actual.boModel.zaehlertyp is not None
+        assert actual.boModel.zaehlertyp == Zaehlertyp.WASSERZAEHLER