ucapi-framework 1.9.1__tar.gz → 1.9.3__tar.gz

{ucapi_framework-1.9.1 → ucapi_framework-1.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucapi-framework
-Version: 1.9.1
+Version: 1.9.3
 Summary: ucapi framework that provides core functionality for building integrations.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{ucapi_framework-1.9.1 → ucapi_framework-1.9.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ucapi-framework"
-version = "1.9.1"
+version = "1.9.3"
 description = "ucapi framework that provides core functionality for building integrations."
 readme = "README.md"
 requires-python = ">=3.11"

{ucapi_framework-1.9.1 → ucapi_framework-1.9.3}/tests/test_discovery.py

@@ -451,28 +451,87 @@ class TestMDNSDiscovery:
 
     @pytest.mark.asyncio
     async def test_discover_with_zeroconf(self):
-        """Test mDNS discovery with mocked zeroconf."""
+        """Test mDNS discovery with mocked zeroconf async classes."""
         mock_service_info = Mock()
         mock_service_info.name = "test-device._test._tcp.local."
         mock_service_info.server = "Test Device"
         mock_service_info.addresses = [b"\xc0\xa8\x01\x64"]  # 192.168.1.100 as bytes
         mock_service_info.port = 8080
 
-        mock_zeroconf = Mock()
-        mock_service_browser = Mock()
+        # ServiceListener must be a real class so Listener can inherit from it
+        class MockServiceListener:
+            pass
+
+        # Track the Listener instance created inside discover()
+        captured_listener: dict = {}
+
+        # Mock AsyncZeroconf
+        mock_aiozc = AsyncMock()
+        mock_aiozc.zeroconf = Mock()
+        mock_aiozc.async_get_service_info = AsyncMock(return_value=mock_service_info)
+        mock_aiozc.async_close = AsyncMock()
+
+        # Mock AsyncServiceBrowser – capture the listener so we can call add_service
+        def mock_browser_init(zc, service_type, listener):
+            captured_listener["obj"] = listener
+            browser = Mock()
+            browser.async_cancel = AsyncMock()
+            return browser
 
         mock_zeroconf_module = Mock()
-        mock_zeroconf_module.Zeroconf.return_value = mock_zeroconf
-        mock_zeroconf_module.ServiceBrowser.return_value = mock_service_browser
+        mock_zeroconf_module.ServiceListener = MockServiceListener
+
+        mock_asyncio_module = Mock()
+        mock_asyncio_module.AsyncZeroconf = Mock(return_value=mock_aiozc)
+        mock_asyncio_module.AsyncServiceBrowser = Mock(side_effect=mock_browser_init)
+
+        with (
+            patch.dict(
+                "sys.modules",
+                {
+                    "zeroconf": mock_zeroconf_module,
+                    "zeroconf.asyncio": mock_asyncio_module,
+                },
+            ),
+            patch("asyncio.sleep", new_callable=AsyncMock) as mock_sleep,
+        ):
+
+            async def trigger_discovery(*args, **kwargs):
+                listener = captured_listener.get("obj")
+                if listener:
+                    listener.add_service(
+                        mock_aiozc.zeroconf,
+                        "_test._tcp.local.",
+                        "test-device._test._tcp.local.",
+                    )
+
+            mock_sleep.side_effect = trigger_discovery
 
-        with patch.dict("sys.modules", {"zeroconf": mock_zeroconf_module}):
             discovery = ConcreteMDNSDiscovery(
                 service_type="_test._tcp.local.", timeout=1
             )
             devices = await discovery.discover()
 
-            # Due to asyncio sleep and mocking complexity, this is more of a structure test
-            assert isinstance(devices, list)
+            assert len(devices) == 1
+            assert devices[0].identifier == "test-device._test._tcp.local."
+            assert devices[0].name == "Test Device"
+            mock_aiozc.async_get_service_info.assert_called_once_with(
+                "_test._tcp.local.", "test-device._test._tcp.local."
+            )
+
+    @pytest.mark.asyncio
+    async def test_discover_handles_import_error(self):
+        """Test that discover handles missing zeroconf gracefully."""
+        discovery = ConcreteMDNSDiscovery(service_type="_test._tcp.local.", timeout=1)
+
+        def mock_import(name, *args, **kwargs):
+            if name in ("zeroconf", "zeroconf.asyncio"):
+                raise ImportError(f"No module named '{name}'")
+            return __import__(name, *args, **kwargs)
+
+        with patch("builtins.__import__", side_effect=mock_import):
+            devices = await discovery.discover()
+            assert devices == []
 
 
 class TestNetworkScanDiscovery:

{ucapi_framework-1.9.1 → ucapi_framework-1.9.3}/ucapi_framework/__init__.py

@@ -48,6 +48,7 @@ from .migration import (
 )
 from .helpers import (
     find_orphaned_entities,
+    find_unused_activity_entities,
     EntityAttributes,
     ButtonAttributes,
     ClimateAttributes,
@@ -126,6 +127,7 @@ __all__ = [
     "SensorEntity",
     "SwitchEntity",
     "VoiceAssistantEntity",
+    "find_unused_activity_entities",
 ]
 
 __version__ = "1.9.1"

{ucapi_framework-1.9.1 → ucapi_framework-1.9.3}/ucapi_framework/discovery.py

@@ -34,6 +34,7 @@ for integrations that don't use them. Install only what you need:
 :license: Mozilla Public License Version 2.0, see LICENSE for more details.
 """
 
+import asyncio
 import logging
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
@@ -356,40 +357,44 @@ class MDNSDiscovery(BaseDiscovery):
 
         try:
             try:
-                from zeroconf import ServiceBrowser, ServiceListener, Zeroconf  # type: ignore[import-not-found]
+                from zeroconf import ServiceListener  # type: ignore[import-not-found]
+                from zeroconf.asyncio import AsyncServiceBrowser, AsyncZeroconf
             except ImportError as err:
                 raise ImportError(
                     "zeroconf package is required for mDNS discovery. "
                     "Install it with: pip install zeroconf"
                 ) from err
 
-            import asyncio
-
-            zeroconf = Zeroconf()
-            discovered = []
+            discovered_names: list[tuple[str, str]] = []
 
             class Listener(ServiceListener):
-                def add_service(self, zc: Zeroconf, type_: str, name: str) -> None:
-                    info = zc.get_service_info(type_, name)
-                    if info:
-                        discovered.append(info)
+                """Listener for mDNS service discovery events."""
 
-                def remove_service(self, zc: Zeroconf, type_: str, name: str) -> None:
-                    pass
+                def add_service(self, zc, type_: str, name: str) -> None:
+                    discovered_names.append((type_, name))
 
-                def update_service(self, zc: Zeroconf, type_: str, name: str) -> None:
+                def remove_service(self, zc, type_: str, name: str) -> None:
                     pass
 
-            browser = ServiceBrowser(zeroconf, self.service_type, Listener())
-
-            # Wait for discovery timeout
-            await asyncio.sleep(self.timeout)
+                def update_service(self, zc, type_: str, name: str) -> None:
+                    pass
 
-            browser.cancel()
-            zeroconf.close()
+            aiozc = AsyncZeroconf()
+            try:
+                browser = AsyncServiceBrowser(
+                    aiozc.zeroconf, self.service_type, Listener()
+                )
+                await asyncio.sleep(self.timeout)
+                await browser.async_cancel()
+                discovered = [
+                    info
+                    for type_, name in discovered_names
+                    if (info := await aiozc.async_get_service_info(type_, name))
+                ]
+            finally:
+                await aiozc.async_close()
 
             self._discovered_devices.clear()
-
             for service_info in discovered:
                 device = self.parse_mdns_service(service_info)
                 if device:
@@ -399,10 +404,8 @@ class MDNSDiscovery(BaseDiscovery):
                 "mDNS discovery complete: found %d device(s)",
                 len(self._discovered_devices),
             )
-
         except Exception as err:  # pylint: disable=broad-exception-caught
             _LOG.error("mDNS discovery error: %s", err)
-
         return self._discovered_devices
 
     @abstractmethod

{ucapi_framework-1.9.1 → ucapi_framework-1.9.3}/ucapi_framework/helpers.py

@@ -294,3 +294,166 @@ async def find_orphaned_entities(
     except Exception as err:  # pylint: disable=broad-except
         _LOG.error("Unexpected error while scanning for orphaned entities: %s", err)
         return orphaned_entities
+
+
+def _extract_used_entity_ids(activity: dict[str, Any]) -> set[str]:
+    """
+    Extract all entity IDs that are actively used in an activity's sequences,
+    button_mapping, and user_interface.
+
+    :param activity: Full activity dict from GET /api/activities/{id}
+    :return: Set of entity_id strings that are referenced
+    """
+    used: set[str] = set()
+    options = activity.get("options", {})
+
+    # sequences: on/off lists of steps; each step may have command.entity_id
+    sequences = options.get("sequences", {})
+    for steps in sequences.values():
+        if not isinstance(steps, list):
+            continue
+        for step in steps:
+            cmd = step.get("command", {})
+            if isinstance(cmd, dict) and cmd.get("entity_id"):
+                used.add(cmd["entity_id"])
+
+    # button_mapping: list of {short_press, long_press} each with entity_id
+    for mapping in options.get("button_mapping", []):
+        for press_key in ("short_press", "long_press"):
+            press = mapping.get(press_key, {})
+            if isinstance(press, dict) and press.get("entity_id"):
+                used.add(press["entity_id"])
+
+    # user_interface: pages → items; entity IDs hide in several fields
+    ui = options.get("user_interface", {})
+    for page in ui.get("pages", []):
+        for item in page.get("items", []):
+            # Direct command entity
+            cmd = item.get("command", {})
+            if isinstance(cmd, dict) and cmd.get("entity_id"):
+                used.add(cmd["entity_id"])
+            # media_player_id
+            if item.get("media_player_id"):
+                used.add(item["media_player_id"])
+            # sensor_id
+            sensor = item.get("sensor", {})
+            if isinstance(sensor, dict) and sensor.get("sensor_id"):
+                used.add(sensor["sensor_id"])
+            # select_id
+            select = item.get("select", {})
+            if isinstance(select, dict) and select.get("select_id"):
+                used.add(select["select_id"])
+
+    return used
+
+
+async def find_unused_activity_entities(
+    remote_url: str,
+    pin: str | None = None,
+    api_key: str | None = None,
+) -> list[dict[str, Any]]:
+    """
+    Find entities included in activities that are never actually used.
+
+    An entity is "unused" when it appears in ``included_entities`` but has no
+    reference in sequences, button_mapping, or user_interface (commands, media
+    player widgets, sensor widgets, or select widgets).
+
+    Authentication can be done via PIN (Basic Auth) or API key (Bearer token).
+    One of ``pin`` or ``api_key`` must be provided.
+
+    :param remote_url: The Remote's base URL (e.g., "http://192.168.1.100")
+    :param pin: Remote's web-configurator PIN for Basic Auth
+    :param api_key: Remote's API key for Bearer token authentication
+    :return: List of dicts with activity context and the unused entity info
+    :raises ValueError: If neither pin nor api_key is provided
+    """
+    if not pin and not api_key:
+        raise ValueError("Either pin or api_key must be provided for authentication")
+
+    _LOG.info("Scanning for unused activity entities on Remote at %s", remote_url)
+
+    headers = {"Content-Type": "application/json"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+
+    auth = None
+    if pin and not api_key:
+        auth = aiohttp.BasicAuth(login="web-configurator", password=pin)
+
+    unused: list[dict[str, Any]] = []
+
+    try:
+        async with aiohttp.ClientSession() as session:
+            activities_url = f"{remote_url}/api/activities?limit=100"
+            async with session.get(
+                activities_url,
+                headers=headers,
+                auth=auth,
+                timeout=aiohttp.ClientTimeout(total=30),
+            ) as resp:
+                if resp.status != 200:
+                    _LOG.error("Failed to fetch activities: HTTP %d", resp.status)
+                    return unused
+                activities_list = await resp.json()
+                _LOG.info(
+                    "Found %d activities to scan for unused entities",
+                    len(activities_list),
+                )
+
+            for activity_summary in activities_list:
+                activity_id = activity_summary.get("entity_id")
+                if not activity_id:
+                    continue
+
+                activity_url = f"{remote_url}/api/activities/{activity_id}"
+                async with session.get(
+                    activity_url,
+                    headers=headers,
+                    auth=auth,
+                    timeout=aiohttp.ClientTimeout(total=30),
+                ) as resp:
+                    if resp.status != 200:
+                        _LOG.warning(
+                            "Failed to fetch activity %s: HTTP %d",
+                            activity_id,
+                            resp.status,
+                        )
+                        continue
+                    activity = await resp.json()
+
+                activity_name = activity_summary.get("name") or activity.get("name", {})
+                options = activity.get("options", {})
+                included_entities = options.get("included_entities", [])
+
+                if not included_entities:
+                    continue
+
+                included_ids = {
+                    e["entity_id"] for e in included_entities if e.get("entity_id")
+                }
+                used_ids = _extract_used_entity_ids(activity)
+                truly_unused = included_ids - used_ids
+
+                for entity in included_entities:
+                    eid = entity.get("entity_id")
+                    if eid in truly_unused:
+                        record = {
+                            k: v
+                            for k, v in entity.items()
+                            if k not in ("entity_commands", "simple_commands")
+                        }
+                        record["activity_id"] = activity_id
+                        record["activity_name"] = activity_name
+                        unused.append(record)
+                        _LOG.debug("Unused entity %s in activity %s", eid, activity_id)
+
+        _LOG.info("Found %d unused activity entities", len(unused))
+        return unused
+
+    except aiohttp.ClientError as err:
+        _LOG.error("Network error while scanning for unused entities: %s", err)
+        return unused
+    except Exception as err:  # pylint: disable=broad-except
+        _LOG.error("Unexpected error while scanning for unused entities: %s", err)
+        return unused

{ucapi_framework-1.9.1 → ucapi_framework-1.9.3}/ucapi_framework.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucapi-framework
-Version: 1.9.1
+Version: 1.9.3
 Summary: ucapi framework that provides core functionality for building integrations.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown