Add an option to disable PII masking in get_diagnostic_data (enabled by default) (#1975)

This pull request updates the `get_diagnostic_data` method in the
`pyoverkiz` client to allow users to optionally retrieve unmasked
diagnostic data, and adds comprehensive tests to ensure the new behavior
works as intended. By default, sensitive data is still masked, but users
can now explicitly request the raw data if needed.

**Enhancements to diagnostic data retrieval:**

* The `get_diagnostic_data` method in `pyoverkiz/client.py` now accepts
a `mask_sensitive_data` parameter (defaulting to `True`), allowing
callers to choose whether to receive masked (redacted) or raw diagnostic
data. The method's docstring has been updated to reflect this new
behavior.

**Testing improvements:**

* Added `test_get_diagnostic_data_redacted_by_default` to verify that
diagnostic data is masked by default and that the obfuscation function
is called.
* Added `test_get_diagnostic_data_without_masking` to ensure that when
`mask_sensitive_data=False` is passed, the raw diagnostic data is
returned and the obfuscation function is not called.

Author: iMicknl

pyoverkiz/client.py

@@ -333,19 +333,23 @@ async def get_setup(self, refresh: bool = False) -> Setup:
         return setup
 
     @retry_on_auth_error
-    async def get_diagnostic_data(self) -> JSON:
+    async def get_diagnostic_data(self, mask_sensitive_data: bool = True) -> JSON:
         """Get all data about the connected user setup.
 
             -> gateways data (serial number, activation state, ...): <gateways/gateway>
             -> setup location: <location>
             -> house places (rooms and floors): <place>
             -> setup devices: <devices>.
 
-        This data will be masked to not return any confidential or PII data.
+        By default, this data is masked to not return confidential or PII data.
+        Set `mask_sensitive_data` to `False` to return the raw setup payload.
         """
         response = await self._get("setup")
 
-        return obfuscate_sensitive_data(response)
+        if mask_sensitive_data:
+            return obfuscate_sensitive_data(response)
+
+        return response
 
     @retry_on_auth_error
     async def get_devices(self, refresh: bool = False) -> list[Device]:

tests/test_client.py

@@ -325,6 +325,44 @@ async def test_get_diagnostic_data(self, client: OverkizClient, fixture_name: st
             diagnostics = await client.get_diagnostic_data()
             assert diagnostics
 
+    @pytest.mark.asyncio
+    async def test_get_diagnostic_data_redacted_by_default(self, client: OverkizClient):
+        """Ensure diagnostics are redacted when no argument is provided."""
+        with open(
+            os.path.join(CURRENT_DIR, "fixtures/setup/setup_tahoma_1.json"),
+            encoding="utf-8",
+        ) as setup_mock:
+            resp = MockResponse(setup_mock.read())
+
+        with (
+            patch.object(aiohttp.ClientSession, "get", return_value=resp),
+            patch(
+                "pyoverkiz.client.obfuscate_sensitive_data",
+                return_value={"masked": True},
+            ) as obfuscate,
+        ):
+            diagnostics = await client.get_diagnostic_data()
+            assert diagnostics == {"masked": True}
+            obfuscate.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_get_diagnostic_data_without_masking(self, client: OverkizClient):
+        """Ensure diagnostics can be returned without masking when requested."""
+        with open(
+            os.path.join(CURRENT_DIR, "fixtures/setup/setup_tahoma_1.json"),
+            encoding="utf-8",
+        ) as setup_mock:
+            raw_setup = setup_mock.read()
+            resp = MockResponse(raw_setup)
+
+        with (
+            patch.object(aiohttp.ClientSession, "get", return_value=resp),
+            patch("pyoverkiz.client.obfuscate_sensitive_data") as obfuscate,
+        ):
+            diagnostics = await client.get_diagnostic_data(mask_sensitive_data=False)
+            assert diagnostics == json.loads(raw_setup)
+            obfuscate.assert_not_called()
+
     @pytest.mark.parametrize(
         "fixture_name, exception, status_code",
         [