ucapi 0.6.0__tar.gz → 0.7.0__tar.gz

{ucapi-0.6.0 → ucapi-0.7.0}/CHANGELOG.md

@@ -11,6 +11,16 @@ _Changes in the next release_
 
 ---
 
+## v0.7.0 - 2026-05-10
+### Added
+- Add requests for supported entity types, version and localization. Only send available entities with supported entity types by @albaintor and @kennymc-c ([#47](https://github.com/unfoldedcircle/integration-python-library/pull/47)).
+
+### Changed
+- Improved WS msg processing with dedicated consumer, producer and router tasks with asyncio queues ([#47](https://github.com/unfoldedcircle/integration-python-library/pull/47)).
+- Sanitize log messages to prevent sensitive information exposure ([#56](https://github.com/unfoldedcircle/integration-python-library/pull/56)).
+- Log WebSocket messages as JSON data instead of a Python dict ([#58](https://github.com/unfoldedcircle/integration-python-library/pull/58)).
+- Updated GitHub actions and test dependencies.
+
 ## v0.6.0 - 2026-04-10
 ### Breaking Changes
 - Renamed `MediaType` to `MediaContentType` and changed enums to lowercase. See media-player entity documentation for more information ([#50](https://github.com/unfoldedcircle/integration-python-library/pull/50)).

{ucapi-0.6.0/ucapi.egg-info → ucapi-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucapi
-Version: 0.6.0
+Version: 0.7.0
 Summary: Python wrapper for the Unfolded Circle Integration API
 Author-email: Unfolded Circle ApS <hello@unfoldedcircle.com>
 License: MPL-2.0

ucapi-0.7.0/scripts/git-tag.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""
+Git tag release script to simplify creating git tags with changelog since last release.
+Copyright (c) 2026 Unfolded Circle.
+"""
+
+import os
+import subprocess
+import sys
+import tempfile
+import re
+import json
+
+
+def run_command(command, check=True):
+    """Run a shell command and return the output."""
+    try:
+        result = subprocess.run(
+            command, shell=True, check=check, capture_output=True, text=True
+        )
+        return result.stdout.strip()
+    except subprocess.CalledProcessError as e:
+        print(f"Error running command: {command}")
+        print(f"Stdout: {e.stdout}")
+        print(f"Stderr: {e.stderr}")
+        if check:
+            sys.exit(1)
+        return None
+
+
+def get_latest_tag():
+    """Get the latest git tag."""
+    return run_command("git describe --tags --abbrev=0", check=False)
+
+
+def get_commits_since(tag):
+    """Get commits since the specified tag."""
+    format_str = '--pretty=format:"%s|%an"'
+    if tag:
+        return run_command(f"git log {tag}..HEAD {format_str}")
+    else:
+        return run_command(f"git log {format_str}")
+
+
+def is_valid_semver(tag):
+    """Check if the version is a valid semver format (X.Y.Z)."""
+    return re.match(r"^\d+\.\d+\.\d+$", tag) is not None
+
+
+import argparse
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Git tag script to simplify creating git tags."
+    )
+    parser.add_argument(
+        "version", help="The new version in semver format (e.g., 0.21.0)"
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true", help="Do not create or push the tag"
+    )
+    args = parser.parse_args()
+
+    version = args.version
+    dry_run = args.dry_run
+    if not is_valid_semver(version):
+        print(f"Error: Version '{version}' is not in valid semver format (X.Y.Z)")
+        sys.exit(1)
+
+    new_tag = f"v{version}"
+
+    # Check if tag already exists
+    existing_tags = run_command("git tag").split("\n")
+    if new_tag in existing_tags:
+        print(f"Error: Tag '{new_tag}' already exists.")
+        sys.exit(1)
+
+    latest_tag = get_latest_tag()
+    print(f"Latest tag: {latest_tag}")
+
+    if latest_tag:
+        commits = get_commits_since(latest_tag)
+    else:
+        commits = get_commits_since(None)
+
+    if not commits:
+        print("No commits since last tag.")
+        sys.exit(0)
+
+    # Process commits
+    formatted_pr_commits = []
+    formatted_other_commits = []
+
+    for line in commits.split("\n"):
+        if not line:
+            continue
+        parts = line.split("|")
+        if len(parts) < 2:
+            continue
+        message = parts[0]
+        _author = parts[1]
+
+        # Extract PR number if present
+        pr_match = re.search(r"\(#(\d+)\)", message)
+        if pr_match:
+            pr_num = pr_match.group(1)
+            # Remove the (#num) part from message
+            clean_message = re.sub(r"\s*\(#\d+\)", "", message).strip()
+            formatted_line = f"{clean_message} in #{pr_num}"
+            formatted_pr_commits.append(formatted_line)
+        else:
+            formatted_line = f"{message}"
+            formatted_other_commits.append(formatted_line)
+
+    initial_message = f"Release {new_tag}\n\n"
+    if formatted_pr_commits:
+        initial_message += "Pull Requests:\n"
+        for line in formatted_pr_commits:
+            initial_message += f"- {line}\n"
+        initial_message += "\n"
+
+    if formatted_other_commits:
+        initial_message += "Other Changes:\n"
+        for line in formatted_other_commits:
+            initial_message += f"- {line}\n"
+
+    # Create temporary file for editing
+    with tempfile.NamedTemporaryFile(suffix=".txt", delete=False) as tmp:
+        tmp.write(initial_message.encode("utf-8"))
+        tmp_path = tmp.name
+
+    editor = os.environ.get("EDITOR", "nano")
+    subprocess.call([editor, tmp_path])
+
+    with open(tmp_path, "r") as f:
+        tag_message = f.read().strip()
+
+    if not tag_message:
+        os.unlink(tmp_path)
+        print("Tag message is empty. Aborting.")
+        sys.exit(1)
+
+    print("\n--- Tag Message ---")
+    print(tag_message)
+    print("-------------------\n")
+
+    confirm = input(f"Create and push tag {new_tag}? (y/n): ")
+    if confirm.lower() == "y":
+        if dry_run:
+            print(f"[DRY-RUN] Would create annotated tag: {new_tag}")
+            print(f"[DRY-RUN] Would push tag {new_tag} to origin.")
+        else:
+            # Create annotated tag
+            run_command(f'git tag -a {new_tag} -F "{tmp_path}"')
+            print(f"Tag {new_tag} created locally.")
+
+            # Push tag
+            run_command(f"git push origin {new_tag}")
+            print(f"Tag {new_tag} pushed to origin.")
+    else:
+        print("Aborted.")
+
+    os.unlink(tmp_path)
+
+
+if __name__ == "__main__":
+    main()

{ucapi-0.6.0 → ucapi-0.7.0}/test-requirements.txt

@@ -3,7 +3,7 @@
 # Workaround: use a pre-commit hook with https://github.com/scikit-image/scikit-image/blob/main/tools/generate_requirements.py
 
 # pin pylint version: it has a tendendy for stricter rules in patch updates!
-pylint==4.0.4
+pylint==4.0.5
 flake8-docstrings
 flake8
 black

{ucapi-0.6.0 → ucapi-0.7.0}/tests/test_api.py

@@ -1,22 +1,22 @@
 import unittest
 from copy import deepcopy
 
-from ucapi.api import filter_log_msg_data
+from ucapi.api import sanitize_json_message
 from ucapi.media_player import Attributes
 
 
-class TestFilterLogMsgData(unittest.TestCase):
+class TestSanitizeJsonMessage(unittest.TestCase):
 
     def test_no_modification_when_no_msg_data(self):
         data = {}
-        result = filter_log_msg_data(data)
+        result = sanitize_json_message(data)
         self.assertEqual(result, {}, "The result should be an empty dictionary")
 
     def test_no_changes_when_media_image_url_not_present(self):
         data = {"msg_data": {"attributes": {"state": "playing", "volume": 50}}}
         original = deepcopy(data)
 
-        result = filter_log_msg_data(data)
+        result = sanitize_json_message(data)
 
         self.assertEqual(
             result,
@@ -36,9 +36,9 @@ class TestFilterLogMsgData(unittest.TestCase):
         expected_result = deepcopy(data)
         expected_result["msg_data"]["attributes"][
             Attributes.MEDIA_IMAGE_URL
-        ] = "data:***"
+        ] = "data:..."
 
-        result = filter_log_msg_data(data)
+        result = sanitize_json_message(data)
 
         self.assertEqual(
             result, expected_result, "The MEDIA_IMAGE_URL attribute should be filtered"
@@ -65,12 +65,12 @@ class TestFilterLogMsgData(unittest.TestCase):
         expected_result = deepcopy(data)
         expected_result["msg_data"][0]["attributes"][
             Attributes.MEDIA_IMAGE_URL
-        ] = "data:***"
+        ] = "data:..."
         expected_result["msg_data"][1]["attributes"][
             Attributes.MEDIA_IMAGE_URL
-        ] = "data:***"
+        ] = "data:..."
 
-        result = filter_log_msg_data(data)
+        result = sanitize_json_message(data)
 
         self.assertEqual(
             result,
@@ -88,8 +88,48 @@ class TestFilterLogMsgData(unittest.TestCase):
         }
         original_data = deepcopy(data)
 
-        filter_log_msg_data(data)
+        sanitize_json_message(data)
 
         self.assertEqual(
             data, original_data, "The input data should not be modified by the function"
         )
+
+    def test_generic_sensitive_keys_redaction(self):
+        sensitive_keys = [
+            "token",
+            "token_id",
+            "access_token",
+            "refresh_token",
+            "id_token",
+            "authorization_code",
+            "client_secret",
+            "secret",
+            "auth_url",
+            "client_data",
+            "password",
+        ]
+
+        for key in sensitive_keys:
+            msg = {key: "sensitive-value", "other": "public-value"}
+            sanitized = sanitize_json_message(msg)
+            self.assertEqual(
+                sanitized[key], "***REDACTED***", f"{key} should be redacted"
+            )
+            self.assertEqual(
+                sanitized["other"], "public-value", "public fields should remain intact"
+            )
+
+    def test_recursive_redaction(self):
+        msg = {
+            "level1": {
+                "token": "secret1",
+                "level2": {"secret": "secret2", "public": "data"},
+            },
+            "array": [{"refresh_token": "secret3"}, "plain-string"],
+        }
+        sanitized = sanitize_json_message(msg)
+        self.assertEqual(sanitized["level1"]["token"], "***REDACTED***")
+        self.assertEqual(sanitized["level1"]["level2"]["secret"], "***REDACTED***")
+        self.assertEqual(sanitized["level1"]["level2"]["public"], "data")
+        self.assertEqual(sanitized["array"][0]["refresh_token"], "***REDACTED***")
+        self.assertEqual(sanitized["array"][1], "plain-string")

{ucapi-0.6.0 → ucapi-0.7.0}/ucapi/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.6.0'
-__version_tuple__ = version_tuple = (0, 6, 0)
+__version__ = version = '0.7.0'
+__version_tuple__ = version_tuple = (0, 7, 0)
 
-__commit_id__ = commit_id = 'g755510031'
+__commit_id__ = commit_id = 'gf6e6e4a0e'

{ucapi-0.6.0 → ucapi-0.7.0}/ucapi/api.py

@@ -78,6 +78,18 @@ class _VoiceSessionContext:
     handler_task: asyncio.Task | None = None
 
 
+@dataclass(slots=True)
+class _WsContext:
+    """Websocket context."""
+
+    incoming: asyncio.Queue[str | bytes | None]
+    outgoing: asyncio.Queue[str | None]
+    pending: dict[int, asyncio.Future]
+    consumer_task: asyncio.Task | None = None
+    producer_task: asyncio.Task | None = None
+    router_task: asyncio.Task | None = None
+
+
 # pylint: disable=too-many-public-methods, too-many-lines
 class IntegrationAPI:
     """Integration API to communicate with Remote Two/3."""
@@ -107,12 +119,18 @@ class IntegrationAPI:
         self._available_entities = Entities("available", self._loop)
         self._configured_entities = Entities("configured", self._loop)
 
+        self._req_id = 1  # Request ID counter for outgoing requests
+
         self._voice_handler: VoiceStreamHandler | None = None
         self._voice_session_timeout: int = self.DEFAULT_VOICE_SESSION_TIMEOUT_S
         # Active voice sessions
         self._voice_sessions: dict[VoiceSessionKey, _VoiceSessionContext] = {}
         # Enforce: at most one active session per entity_id (across all websockets)
         self._voice_session_by_entity: dict[str, VoiceSessionKey] = {}
+        # Websocket context with incoming & outgoing queues and handlers
+        self._ws_contexts: dict[Any, _WsContext] = {}
+        # Supported entity types
+        self._supported_entity_types: list[str] | None = None
 
         # Setup event loop
         asyncio.set_event_loop(self._loop)
@@ -129,9 +147,10 @@ class IntegrationAPI:
         self, driver_path: str, setup_handler: uc.SetupHandler | None = None
     ):
         """
-        Load driver configuration and start integration-API WebSocket server.
+        Load driver configuration and start the integration-API WebSocket server.
 
-        :param driver_path: path to configuration file
+        :param driver_path: path to the configuration file. If it is not an absolute
+               path, the current working directory is used.
         :param setup_handler: optional driver setup handler if the driver metadata
                contains a setup_data_schema object
         """
@@ -214,40 +233,74 @@ class IntegrationAPI:
             await asyncio.Future()
 
     async def _handle_ws(self, websocket) -> None:
+        # Initialize incoming and outgoing queues
+        incoming: asyncio.Queue[str | bytes | None] = asyncio.Queue(maxsize=100)
+        outgoing: asyncio.Queue[str | None] = asyncio.Queue(maxsize=100)
+
+        ctx = _WsContext(
+            incoming=incoming,
+            outgoing=outgoing,
+            pending={},
+        )
+
+        self._clients.add(websocket)
+        self._ws_contexts[websocket] = ctx
+
         try:
-            self._clients.add(websocket)
             _LOG.info("WS: Client added: %s", websocket.remote_address)
 
+            ctx.consumer_task = self._loop.create_task(
+                self._ws_consumer(websocket, ctx)
+            )
+            ctx.producer_task = self._loop.create_task(
+                self._ws_producer(websocket, ctx)
+            )
+            ctx.router_task = self._loop.create_task(self._ws_router(websocket, ctx))
+
             # authenticate on connection
             await self._authenticate(websocket, True)
-
             self._events.emit(uc.Events.CLIENT_CONNECTED, websocket=websocket)
+            tasks = [
+                t
+                for t in [ctx.consumer_task, ctx.producer_task, ctx.router_task]
+                if t is not None
+            ]
+            done, pending = await asyncio.wait(
+                tasks,
+                return_when=asyncio.FIRST_COMPLETED,
+            )
 
-            async for message in websocket:
-                # Distinguish between text (str) and binary (bytes-like) messages
-                if isinstance(message, str):
-                    # JSON text message
-                    await self._process_ws_message(websocket, message)
-                elif isinstance(message, (bytes, bytearray, memoryview)):
-                    # Binary message (protobuf in future)
-                    await self._process_ws_binary_message(websocket, bytes(message))
-                else:
-                    _LOG.warning(
-                        "[%s] WS: Unsupported message type %s",
+            if pending:
+                # graceful shutdown: wait a bit for pending tasks to process sentinel 'None'
+                _LOG.debug("[%s] WS: Draining tasks", websocket.remote_address)
+                await asyncio.wait(pending, timeout=1.0)
+
+            for task in pending:
+                task.cancel()
+
+            results = await asyncio.gather(*done, *pending, return_exceptions=True)
+            for result in results:
+                if isinstance(result, Exception) and not isinstance(
+                    result, asyncio.CancelledError
+                ):
+                    _LOG.error(
+                        "[%s] WS: Exception in task",
                         websocket.remote_address,
-                        type(message).__name__,
+                        exc_info=result,
                     )
 
         except ConnectionClosedOK:
             _LOG.info("[%s] WS: Connection closed", websocket.remote_address)
 
         except websockets.exceptions.ConnectionClosedError as e:
-            # no idea why they made code & reason deprecated...
+            close = e.rcvd or e.sent
+            code = getattr(close, "code", None)
+            reason = getattr(close, "reason", None)
             _LOG.info(
-                "[%s] WS: Connection closed with error %d: %s",
+                "[%s] WS: Connection closed with error %s: %s",
                 websocket.remote_address,
-                e.code,
-                e.reason,
+                code,
+                reason,
             )
 
         except websockets.exceptions.WebSocketException as e:
@@ -258,22 +311,103 @@ class IntegrationAPI:
             )
 
         finally:
-            # Cleanup any active voice sessions associated with this websocket
-            keys_to_cleanup = [k for k in self._voice_sessions if k[0] is websocket]
-            for key in keys_to_cleanup:
-                try:
-                    await self._cleanup_voice_session(key, VoiceEndReason.REMOTE)
-                except Exception as ex:  # pylint: disable=W0718
-                    _LOG.exception(
-                        "[%s] WS: Error during voice session cleanup for session_id=%s: %s",
+            await self._cleanup_ws(websocket)
+
+    async def _ws_consumer(self, websocket, ctx: _WsContext) -> None:
+        """Route incoming message (requests or events from remote or responses to driver)."""
+        try:
+            async for raw_message in websocket:
+                if isinstance(raw_message, str):
+                    try:
+                        data = json.loads(raw_message)
+                    except json.JSONDecodeError:
+                        _LOG.warning(
+                            "[%s] WS: Invalid JSON message: %s",
+                            websocket.remote_address,
+                            raw_message,
+                        )
+                        continue
+
+                    kind: str | None = None
+                    if isinstance(data, dict):
+                        kind = data.get("kind")
+
+                    # Handle the response to a previous driver request
+                    if kind == "resp":
+                        self._handle_pending_response(websocket, data)
+                    # Otherwise handle the json request
+                    else:
+                        await ctx.incoming.put(data)
+                # Handle the binary message
+                elif isinstance(raw_message, (bytes, bytearray, memoryview)):
+                    await ctx.incoming.put(bytes(raw_message))
+                else:
+                    _LOG.warning(
+                        "[%s] WS: Unsupported message type %s",
                         websocket.remote_address,
-                        key[1],
-                        ex,
+                        type(raw_message).__name__,
                     )
+        finally:
+            await ctx.incoming.put(None)
+            await ctx.outgoing.put(None)
+
+    async def _ws_producer(self, websocket, ctx: _WsContext) -> None:
+        """Route outgoing messages."""
+        try:
+            while True:
+                msg = await ctx.outgoing.get()
+                if msg is None:
+                    break
+                await websocket.send(msg)
+        except (ConnectionClosedOK, websockets.exceptions.ConnectionClosedError):
+            pass
+
+    async def _ws_router(self, websocket, ctx: _WsContext) -> None:
+        """Route incoming requests."""
+        while True:
+            message = await ctx.incoming.get()
+            if message is None:
+                break
+            if isinstance(message, dict):
+                await self._process_ws_message(websocket, message)
+            elif isinstance(message, bytes):
+                await self._process_ws_binary_message(websocket, message)
+            else:
+                _LOG.warning(
+                    "[%s] WS: Unsupported routed message type %s",
+                    websocket.remote_address,
+                    type(message).__name__,
+                )
+
+    def _get_ws_context(self, websocket) -> _WsContext | None:
+        return self._ws_contexts.get(websocket)
+
+    async def _enqueue_ws_payload(self, websocket, payload: dict[str, Any]) -> None:
+        ctx = self._get_ws_context(websocket)
+        if ctx is None or websocket not in self._clients:
+            _LOG.error("Error sending payload: connection no longer established")
+            return
 
-            self._clients.remove(websocket)
-            _LOG.info("[%s] WS: Client removed", websocket.remote_address)
-            self._events.emit(uc.Events.CLIENT_DISCONNECTED, websocket=websocket)
+        if _LOG.isEnabledFor(logging.DEBUG):
+            _LOG.debug(
+                "[%s] <-: %s",
+                websocket.remote_address,
+                json.dumps(sanitize_json_message(payload)),
+            )
+
+        match payload.get("kind"):
+            case "event":
+                try:
+                    ctx.outgoing.put_nowait(json.dumps(payload))
+                except asyncio.QueueFull:
+                    _LOG.warning(
+                        "[%s] Outgoing queue full, dropping event",
+                        websocket.remote_address,
+                    )
+            case "req":
+                ctx.outgoing.put_nowait(json.dumps(payload))
+            case _:
+                await ctx.outgoing.put(json.dumps(payload))
 
     async def _send_ok_result(
         self, websocket, req_id: int, msg_data: dict[str, Any] | list | None = None
@@ -312,7 +446,7 @@ class IntegrationAPI:
         """
         await self._send_ws_response(websocket, req_id, "result", msg_data, status_code)
 
-    # pylint: disable=R0917
+    # pylint: disable=too-many-positional-arguments
     async def _send_ws_response(
         self,
         websocket,
@@ -340,16 +474,7 @@ class IntegrationAPI:
             "msg": msg,
             "msg_data": msg_data if msg_data is not None else {},
         }
-
-        if websocket in self._clients:
-            data_dump = json.dumps(data)
-            if _LOG.isEnabledFor(logging.DEBUG):
-                _LOG.debug(
-                    "[%s] ->: %s", websocket.remote_address, filter_log_msg_data(data)
-                )
-            await websocket.send(data_dump)
-        else:
-            _LOG.error("Error sending response: connection no longer established")
+        await self._enqueue_ws_payload(websocket, data)
 
     async def _broadcast_ws_event(
         self, msg: str, msg_data: dict[str, Any], category: uc.EventCategory
@@ -365,17 +490,13 @@ class IntegrationAPI:
         :param category: event category
         """
         data = {"kind": "event", "msg": msg, "msg_data": msg_data, "cat": category}
-        data_dump = json.dumps(data)
-
         for websocket in self._clients.copy():
-            if _LOG.isEnabledFor(logging.DEBUG):
-                _LOG.debug(
-                    "[%s] =>: %s", websocket.remote_address, filter_log_msg_data(data)
-                )
             try:
-                await websocket.send(data_dump)
-            except websockets.exceptions.WebSocketException:
-                pass
+                await self._enqueue_ws_payload(websocket, data)
+            except Exception:  # pylint: disable=broad-exception-caught
+                _LOG.exception(
+                    "Failed to enqueue broadcast for %s", websocket.remote_address
+                )
 
     async def _send_ws_event(
         self, websocket, msg: str, msg_data: dict[str, Any], category: uc.EventCategory
@@ -392,35 +513,121 @@ class IntegrationAPI:
             websockets.ConnectionClosed: When the connection is closed.
         """
         data = {"kind": "event", "msg": msg, "msg_data": msg_data, "cat": category}
-        data_dump = json.dumps(data)
+        await self._enqueue_ws_payload(websocket, data)
 
-        if websocket in self._clients:
-            if _LOG.isEnabledFor(logging.DEBUG):
-                _LOG.debug(
-                    "[%s] ->: %s", websocket.remote_address, filter_log_msg_data(data)
-                )
-            await websocket.send(data_dump)
-        else:
-            _LOG.error("Error sending event: connection no longer established")
-
-    async def _process_ws_message(self, websocket, message) -> None:
-        _LOG.debug("[%s] <-: %s", websocket.remote_address, message)
+    async def _process_ws_message(self, websocket, data: dict[str, Any]) -> None:
+        if _LOG.isEnabledFor(logging.DEBUG):
+            _LOG.debug(
+                "[%s] ->: %s",
+                websocket.remote_address,
+                json.dumps(sanitize_json_message(data)),
+            )
 
-        data = json.loads(message)
         kind = data["kind"]
-        req_id = data["id"] if "id" in data else None
+        req_id = data.get("id")
         msg = data["msg"]
-        msg_data = data["msg_data"] if "msg_data" in data else None
+        msg_data = data.get("msg_data")
 
         if kind == "req":
             if req_id is None:
                 _LOG.warning(
-                    "Ignoring request message with missing 'req_id': %s", message
+                    "Ignoring request message with missing 'id': %s",
+                    data,
                 )
-            else:
-                await self._handle_ws_request_msg(websocket, msg, req_id, msg_data)
+                return
+            await self._handle_ws_request_msg(websocket, msg, req_id, msg_data)
         elif kind == "event":
             await self._handle_ws_event_msg(websocket, msg, msg_data)
+        else:
+            _LOG.warning(
+                "[%s] WS: Unsupported routed message kind %s",
+                websocket.remote_address,
+                kind,
+            )
+
+    def _handle_pending_response(self, websocket, data: dict[str, Any]) -> None:
+        """Resolve the response message that corresponds to a pending request from the driver."""
+        resp_id = data.get("req_id", data.get("id"))
+        if resp_id is None:
+            _LOG.warning(
+                "[%s] WS: Received resp without req_id/id: %s",
+                websocket.remote_address,
+                data,
+            )
+            return
+
+        ctx = self._get_ws_context(websocket)
+        if ctx is None:
+            _LOG.debug("[%s] WS: No context for resp", websocket.remote_address)
+            return
+
+        fut = ctx.pending.get(int(resp_id))
+        if fut is None:
+            _LOG.debug(
+                "[%s] WS: Unmatched resp_id=%s (not pending). msg=%s",
+                websocket.remote_address,
+                resp_id,
+                data.get("msg"),
+            )
+            return
+
+        if not fut.done():
+            fut.set_result(data)
+
+    async def _ws_request(
+        self,
+        websocket,
+        msg: str,
+        msg_data: dict[str, Any] | None = None,
+        *,
+        timeout: float = 10.0,
+    ) -> dict[str, Any]:
+        """
+        Send a request over websocket and await the matching response.
+
+        - Uses a Future stored in self._ws_pending[websocket][req_id]
+        - Reader task (_handle_ws -> _process_ws_message) completes the future on 'resp'
+        - Raises TimeoutError on timeout
+        :param websocket: client connection
+        :param msg: event message name
+        :param msg_data: message data payload
+        :param timeout: timeout for message
+        """
+        # Ensure per-socket structures exist (in case you call before _handle_ws init)
+        ctx = self._get_ws_context(websocket)
+        if ctx is None:
+            raise ConnectionError("WebSocket context not found")
+
+        # Allocate req_id safely
+        req_id = self._req_id
+        self._req_id += 1
+
+        fut = self._loop.create_future()
+        ctx.pending[req_id] = fut
+
+        try:
+            payload: dict[str, Any] = {"kind": "req", "id": req_id, "msg": msg}
+            if msg_data is not None:
+                payload["msg_data"] = msg_data
+
+            await self._enqueue_ws_payload(websocket, payload)
+
+            # Await response from client until given timeout
+            resp = await asyncio.wait_for(fut, timeout=timeout)
+            return resp
+
+        except asyncio.TimeoutError as ex:
+            _LOG.error(
+                "[%s] Timeout waiting for response to %s (req_id=%s) %s",
+                websocket.remote_address,
+                msg,
+                req_id,
+                ex,
+            )
+            raise ex
+        finally:
+            # Cleanup pending future entry
+            ctx.pending.pop(req_id, None)
 
     async def _process_ws_binary_message(self, websocket, data: bytes) -> None:
         """Process a binary WebSocket message using protobuf IntegrationMessage.
@@ -431,7 +638,7 @@ class IntegrationAPI:
         """
         if _LOG.isEnabledFor(logging.DEBUG):
             _LOG.debug(
-                "[%s] <-: <binary %d bytes>", websocket.remote_address, len(data)
+                "[%s] ->: <binary %d bytes>", websocket.remote_address, len(data)
             )
 
         # Parse IntegrationMessage from bytes
@@ -462,6 +669,30 @@ class IntegrationAPI:
                 kind,
             )
 
+    async def _cleanup_ws(self, websocket) -> None:
+        ctx = self._ws_contexts.pop(websocket, None)
+
+        keys_to_cleanup = [k for k in self._voice_sessions if k[0] is websocket]
+        for key in keys_to_cleanup:
+            try:
+                await self._cleanup_voice_session(key, VoiceEndReason.REMOTE)
+            except Exception as ex:  # pylint: disable=broad-exception-caught
+                _LOG.exception(
+                    "[%s] WS: Error during voice session cleanup for session_id=%s: %s",
+                    websocket.remote_address,
+                    key[1],
+                    ex,
+                )
+
+        if ctx is not None:
+            for fut in ctx.pending.values():
+                if not fut.done():
+                    fut.set_exception(ConnectionError("WebSocket disconnected"))
+
+        self._clients.discard(websocket)
+        _LOG.info("[%s] WS: Client removed", websocket.remote_address)
+        self._events.emit(uc.Events.CLIENT_DISCONNECTED, websocket=websocket)
+
     async def _on_remote_voice_begin(self, websocket, msg: RemoteVoiceBegin) -> None:
         """Handle a RemoteVoiceBegin protobuf message.
 
@@ -702,13 +933,7 @@ class IntegrationAPI:
                 {"state": self.device_state},
             )
         elif msg == uc.WsMessages.GET_AVAILABLE_ENTITIES:
-            available_entities = self._available_entities.get_all()
-            await self._send_ws_response(
-                websocket,
-                req_id,
-                uc.WsMsgEvents.AVAILABLE_ENTITIES,
-                {"available_entities": available_entities},
-            )
+            await self._get_available_entities(websocket, req_id)
         elif msg == uc.WsMessages.GET_ENTITY_STATES:
             entity_states = await self._configured_entities.get_states()
             await self._send_ws_response(
@@ -1351,10 +1576,108 @@ class IntegrationAPI:
         """
         self._events.remove_all_listeners(event)
 
+    async def get_supported_entity_types(
+        self, websocket, *, timeout: float = 5.0
+    ) -> list[str]:
+        """Request supported entity types from client and return msg_data."""
+        resp = await self._ws_request(
+            websocket,
+            "get_supported_entity_types",
+            timeout=timeout,
+        )
+        if resp.get("msg") != "supported_entity_types":
+            _LOG.debug(
+                "[%s] Unexpected resp msg for get_supported_entity_types: %s",
+                websocket.remote_address,
+                resp.get("msg"),
+            )
+        return resp.get("msg_data", [])
+
+    async def get_version(
+        self, websocket, *, timeout: float = 5.0
+    ) -> dict[str, Any] | None:
+        """Request client version and return msg_data."""
+        resp = await self._ws_request(
+            websocket,
+            "get_version",
+            timeout=timeout,
+        )
+        if resp.get("msg") != "version":
+            _LOG.debug(
+                "[%s] Unexpected resp msg for get_version: %s",
+                websocket.remote_address,
+                resp.get("msg"),
+            )
+
+        return resp.get("msg_data")
+
+    async def get_localization_cfg(
+        self, websocket, *, timeout: float = 5.0
+    ) -> dict[str, Any] | None:
+        """Request localization config and return msg_data."""
+        resp = await self._ws_request(
+            websocket,
+            "get_localization_cfg",
+            timeout=timeout,
+        )
+
+        if resp.get("msg") != "localization_cfg":
+            _LOG.debug(
+                "[%s] Unexpected resp msg for get_localization_cfg: %s",
+                websocket.remote_address,
+                resp.get("msg"),
+            )
+
+        return resp.get("msg_data")
+
+    async def _update_supported_entity_types(
+        self, websocket, *, timeout: float = 5.0
+    ) -> None:
+        """Update supported entity types by remote."""
+        await asyncio.sleep(0)
+        try:
+            self._supported_entity_types = await self.get_supported_entity_types(
+                websocket, timeout=timeout
+            )
+            _LOG.debug(
+                "[%s] Supported entity types %s",
+                websocket.remote_address,
+                self._supported_entity_types,
+            )
+        except Exception as ex:  # pylint: disable=W0718
+            _LOG.error(
+                "[%s] Unable to retrieve entity types %s",
+                websocket.remote_address,
+                ex,
+            )
+
+    async def _get_available_entities(self, websocket, req_id) -> None:
+        if self._supported_entity_types is None:
+            # Request supported entity types from remote
+            await self._update_supported_entity_types(websocket)
+        available_entities = self._available_entities.get_all()
+        if self._supported_entity_types:
+            available_entities = [
+                entity
+                for entity in available_entities
+                if entity.get("entity_type") in self._supported_entity_types
+            ]
+        await self._send_ws_response(
+            websocket,
+            req_id,
+            uc.WsMsgEvents.AVAILABLE_ENTITIES,
+            {"available_entities": available_entities},
+        )
+
     ##############
     # Properties #
     ##############
 
+    @property
+    def clients(self) -> set:
+        """Return all clients."""
+        return self._clients.copy()
+
     @property
     def client_count(self) -> int:
         """Return number of WebSocket clients."""
@@ -1462,46 +1785,83 @@ def local_hostname() -> str:
     )
 
 
-def filter_log_msg_data(data: dict[str, Any]) -> dict[str, Any]:
+_REDACTED_VALUE = "***REDACTED***"
+_SENSITIVE_KEYS = {
+    "token",
+    "token_id",
+    "access_token",
+    "refresh_token",
+    "id_token",
+    "authorization_code",
+    "client_secret",
+    "secret",
+    "auth_url",
+    "client_data",
+    "password",
+}
+
+
+def _filter_base64_images(json_data: Any) -> Any:
+    """
+    Filter out base64 encoded images from a JSON object.
+
+    **Attention:** the provided JSON object is modified in-place!
+
+    :param json_data: The JSON object to filter.
+    :returns: The filtered JSON object.
+    """
+    if json_data and isinstance(json_data, dict) and "msg_data" in json_data:
+        msg_data = json_data["msg_data"]
+        if isinstance(msg_data, list):
+            for item in msg_data:
+                if (
+                    isinstance(item, dict)
+                    and "attributes" in item
+                    and isinstance(item["attributes"], dict)
+                    and item["attributes"]
+                    .get(MediaAttr.MEDIA_IMAGE_URL, "")
+                    .startswith("data:")
+                ):
+                    item["attributes"][MediaAttr.MEDIA_IMAGE_URL] = "data:..."
+        elif (
+            isinstance(msg_data, dict)
+            and "attributes" in msg_data
+            and isinstance(msg_data["attributes"], dict)
+            and msg_data["attributes"]
+            .get(MediaAttr.MEDIA_IMAGE_URL, "")
+            .startswith("data:")
+        ):
+            msg_data["attributes"][MediaAttr.MEDIA_IMAGE_URL] = "data:..."
+    return json_data
+
+
+def sanitize_json_message(data: Any) -> Any:
     """
-    Filter attribute fields to exclude for log messages in the given msg data dict.
+    Sanitizes a JSON message by redacting sensitive fields such as tokens and secrets.
+
+    Base64 encoded images starting with `data:` are removed in `msg_data.attributes.media_image_url`
+    fields to limit log output.
 
-    - Attributes are filtered in `data["msg_data"]`:
-      - dict object: key `attributes`
-      - list object: every list item `attributes`
-    - Filtered attributes: `MEDIA_IMAGE_URL`
+    The original message is not modified, the returned redacted message is a deepcopy.
 
-    :param data: the message data dict
-    :return: copy of the message data dict with filtered attributes
+    :param data: The JSON object to be sanitized.
+    :return: The sanitized JSON object with sensitive information redacted.
     """
     # do not modify the original dict
-    log_upd = deepcopy(data)
-    if not log_upd:
+    json_upd = deepcopy(data)
+    if not json_upd:
         return {}
 
-    # filter out base64 encoded images in the media player's media_image_url attribute
-    if "msg_data" in log_upd:
-        if (
-            "attributes" in log_upd["msg_data"]
-            and MediaAttr.MEDIA_IMAGE_URL in log_upd["msg_data"]["attributes"]
-            and (
-                media_image_url := log_upd["msg_data"]["attributes"][
-                    MediaAttr.MEDIA_IMAGE_URL
-                ]
-            )
-            and media_image_url.startswith("data:")
-        ):
-            log_upd["msg_data"]["attributes"][MediaAttr.MEDIA_IMAGE_URL] = "data:***"
-        elif isinstance(log_upd["msg_data"], list):
-            for item in log_upd["msg_data"]:
-                if (
-                    "attributes" in item
-                    and MediaAttr.MEDIA_IMAGE_URL in item["attributes"]
-                    and (
-                        media_image_url := item["attributes"][MediaAttr.MEDIA_IMAGE_URL]
-                    )
-                    and media_image_url.startswith("data:")
-                ):
-                    item["attributes"][MediaAttr.MEDIA_IMAGE_URL] = "data:***"
+    def sanitize_for_logging(value: Any) -> Any:
+        if value and isinstance(value, (dict, list)):
+            if isinstance(value, list):
+                return [sanitize_for_logging(item) for item in value]
+
+            for k, v in value.items():
+                if k in _SENSITIVE_KEYS:
+                    value[k] = _REDACTED_VALUE
+                else:
+                    value[k] = sanitize_for_logging(v)
+        return value
 
-    return log_upd
+    return sanitize_for_logging(_filter_base64_images(json_upd))

{ucapi-0.6.0 → ucapi-0.7.0/ucapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucapi
-Version: 0.6.0
+Version: 0.7.0
 Summary: Python wrapper for the Unfolded Circle Integration API
 Author-email: Unfolded Circle ApS <hello@unfoldedcircle.com>
 License: MPL-2.0

{ucapi-0.6.0 → ucapi-0.7.0}/ucapi.egg-info/SOURCES.txt

@@ -19,6 +19,7 @@ examples/setup_flow.py
 examples/voice.json
 examples/voice.py
 scripts/compile_protos.py
+scripts/git-tag.py
 tests/test_api.py
 tests/test_media_player.py
 tests/test_paging.py