pyg90alarm 1.17.2__tar.gz → 1.20.0__tar.gz

{pyg90alarm-1.17.2 → pyg90alarm-1.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: pyg90alarm
-Version: 1.17.2
+Version: 1.20.0
 Summary: G90 Alarm system protocol
 Home-page: https://github.com/hostcc/pyg90alarm
 Author: Ilia Sotnikov
@@ -33,6 +33,17 @@ Requires-Dist: asynctest; extra == "test"
 Provides-Extra: docs
 Requires-Dist: sphinx; extra == "docs"
 Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-python
+Dynamic: summary
 
 .. image::  https://github.com/hostcc/pyg90alarm/actions/workflows/main.yml/badge.svg?branch=master
    :target: https://github.com/hostcc/pyg90alarm/tree/master

{pyg90alarm-1.17.2 → pyg90alarm-1.20.0}/src/pyg90alarm/alarm.py

@@ -17,6 +17,7 @@
 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
+# pylint: disable=too-many-lines
 
 """
 Provides interface to G90 alarm panel.
@@ -68,7 +69,9 @@ from .const import (
 from .base_cmd import (G90BaseCommand, G90BaseCommandData)
 from .paginated_result import G90PaginatedResult, G90PaginatedResponse
 from .entities.sensor import (G90Sensor, G90SensorTypes)
+from .entities.sensor_list import G90SensorList
 from .entities.device import G90Device
+from .entities.device_list import G90DeviceList
 from .device_notifications import (
     G90DeviceNotifications,
 )
@@ -120,6 +123,14 @@ if TYPE_CHECKING:
             [int, str, G90RemoteButtonStates], Coroutine[None, None, None]
         ]
     ]
+    DoorOpenWhenArmingCallback = Union[
+        Callable[[int, str], None],
+        Callable[[int, str], Coroutine[None, None, None]]
+    ]
+    TamperCallback = Union[
+        Callable[[int, str], None],
+        Callable[[int, str], Coroutine[None, None, None]]
+    ]
     # Sensor-related callbacks for `G90Sensor` class - despite that class
     # stores them, the invocation is done by the `G90Alarm` class hence these
     # are defined here
@@ -131,6 +142,14 @@ if TYPE_CHECKING:
         Callable[[], None],
         Callable[[], Coroutine[None, None, None]]
     ]
+    SensorDoorOpenWhenArmingCallback = Union[
+        Callable[[], None],
+        Callable[[], Coroutine[None, None, None]]
+    ]
+    SensorTamperCallback = Union[
+        Callable[[], None],
+        Callable[[], Coroutine[None, None, None]]
+    ]
 
 
 # pylint: disable=too-many-public-methods
@@ -160,10 +179,8 @@ class G90Alarm(G90DeviceNotifications):
         )
         self._host: str = host
         self._port: int = port
-        self._sensors: List[G90Sensor] = []
-        self._sensors_lock = asyncio.Lock()
-        self._devices: List[G90Device] = []
-        self._devices_lock = asyncio.Lock()
+        self._sensors = G90SensorList(self)
+        self._devices = G90DeviceList(self)
         self._notifications: Optional[G90DeviceNotifications] = None
         self._sensor_cb: Optional[SensorCallback] = None
         self._armdisarm_cb: Optional[ArmDisarmCallback] = None
@@ -174,6 +191,10 @@ class G90Alarm(G90DeviceNotifications):
         self._remote_button_press_cb: Optional[
             RemoteButtonPressCallback
         ] = None
+        self._door_open_when_arming_cb: Optional[
+            DoorOpenWhenArmingCallback
+        ] = None
+        self._tamper_cb: Optional[TamperCallback] = None
         self._reset_occupancy_interval = reset_occupancy_interval
         self._alert_config: Optional[G90AlertConfigFlags] = None
         self._sms_alert_when_armed = False
@@ -247,109 +268,58 @@ class G90Alarm(G90DeviceNotifications):
     @property
     async def sensors(self) -> List[G90Sensor]:
         """
-        Property over new :meth:`.get_sensors` method, retained for
-        compatibility.
+        Returns the list of sensors configured in the device. Please note
+        it doesn't update those from the panel except initially when the list
+        if empty.
+
+        :return: List of sensors
         """
-        return await self.get_sensors()
+        return await self._sensors.entities
 
     async def get_sensors(self) -> List[G90Sensor]:
         """
-        Provides list of sensors configured in the device. Please note the list
-        is cached upon first call, so you need to re-instantiate the class to
-        reflect any updates there.
+        Provides list of sensors configured in the device, updating them from
+        panel on each call.
 
         :return: List of sensors
         """
-        # Use lock around the operation, to ensure no duplicated entries in the
-        # resulting list or redundant exchanges with panel are made when the
-        # method is called concurrently
-        async with self._sensors_lock:
-            if not self._sensors:
-                sensors = self.paginated_result(
-                    G90Commands.GETSENSORLIST
-                )
-                async for sensor in sensors:
-                    obj = G90Sensor(
-                        *sensor.data, parent=self, subindex=0,
-                        proto_idx=sensor.proto_idx
-                    )
-                    self._sensors.append(obj)
-
-                _LOGGER.debug(
-                    'Total number of sensors: %s', len(self._sensors)
-                )
+        return await self._sensors.update()
 
-            return self._sensors
-
-    async def find_sensor(self, idx: int, name: str) -> Optional[G90Sensor]:
+    async def find_sensor(
+        self, idx: int, name: str, exclude_unavailable: bool = True
+    ) -> Optional[G90Sensor]:
         """
         Finds sensor by index and name.
 
         :param idx: Sensor index
         :param name: Sensor name
+        :param exclude_unavailable: Flag indicating if unavailable sensors
+         should be excluded from the search
         :return: Sensor instance
         """
-        sensors = await self.get_sensors()
-
-        # Fast lookup by direct index
-        if idx < len(sensors) and sensors[idx].name == name:
-            sensor = sensors[idx]
-            _LOGGER.debug('Found sensor via fast lookup: %s', sensor)
-            return sensor
-
-        # Fast lookup failed, perform slow one over the whole sensors list
-        for sensor in sensors:
-            if sensor.index == idx and sensor.name == name:
-                _LOGGER.debug('Found sensor: %s', sensor)
-                return sensor
-
-        _LOGGER.error('Sensor not found: idx=%s, name=%s', idx, name)
-        return None
+        return await self._sensors.find(idx, name, exclude_unavailable)
 
     @property
     async def devices(self) -> List[G90Device]:
         """
-        Property over new :meth:`.get_devices` method, retained for
-        compatibility.
+        Returns the list of devices (switches) configured in the device. Please
+        note it doesn't update those from the panel except initially when
+        the list if empty.
+
+        :return: List of devices
         """
-        return await self.get_devices()
+        return await self._devices.entities
 
     async def get_devices(self) -> List[G90Device]:
         """
-        Provides list of devices (switches) configured in the device. Please
-        note the list is cached upon first call, so you need to re-instantiate
-        the class to reflect any updates there. Multi-node devices, those
+        Provides list of devices (switches) configured in the device, updating
+        them from panel on each call. Multi-node devices, those
         having multiple ports, are expanded into corresponding number of
         resulting entries.
 
         :return: List of devices
         """
-        # See `get_sensors` method for the rationale behind the lock usage
-        async with self._devices_lock:
-            if not self._devices:
-                devices = self.paginated_result(
-                    G90Commands.GETDEVICELIST
-                )
-                async for device in devices:
-                    obj = G90Device(
-                        *device.data, parent=self, subindex=0,
-                        proto_idx=device.proto_idx
-                    )
-                    self._devices.append(obj)
-                    # Multi-node devices (first node has already been added
-                    # above
-                    for node in range(1, obj.node_count):
-                        obj = G90Device(
-                            *device.data, parent=self,
-                            subindex=node, proto_idx=device.proto_idx
-                        )
-                        self._devices.append(obj)
-
-                _LOGGER.debug(
-                    'Total number of devices: %s', len(self._devices)
-                )
-
-            return self._devices
+        return await self._devices.update()
 
     @property
     async def host_info(self) -> G90HostInfo:
@@ -613,6 +583,17 @@ class G90Alarm(G90DeviceNotifications):
                 await self.set_alert_config(
                     await self.alert_config | G90AlertConfigFlags.SMS_PUSH
                 )
+
+        # Reset the tampered and door open when arming flags on all sensors
+        # having those set
+        for sensor in await self.sensors:
+            if sensor.is_tampered:
+                # pylint: disable=protected-access
+                sensor._set_tampered(False)
+            if sensor.is_door_open_when_arming:
+                # pylint: disable=protected-access
+                sensor._set_door_open_when_arming(False)
+
         G90Callback.invoke(self._armdisarm_cb, state)
 
     @property
@@ -627,7 +608,9 @@ class G90Alarm(G90DeviceNotifications):
     def armdisarm_callback(self, value: ArmDisarmCallback) -> None:
         self._armdisarm_cb = value
 
-    async def on_alarm(self, event_id: int, zone_name: str) -> None:
+    async def on_alarm(
+        self, event_id: int, zone_name: str, is_tampered: bool
+    ) -> None:
         """
         Invoked when alarm is triggered. Fires corresponding callback if set by
         the user with :attr:`.alarm_callback`.
@@ -638,16 +621,31 @@ class G90Alarm(G90DeviceNotifications):
         :param zone_name: Sensor name
         """
         sensor = await self.find_sensor(event_id, zone_name)
-        # The callback is still delivered to the caller even if the sensor
-        # isn't found, only `extra_data` is skipped. That is to ensure the
-        # important callback isn't filtered
-        extra_data = sensor.extra_data if sensor else None
-        # Invoke the sensor activity callback to set the sensor occupancy if
-        # sensor is known, but only if that isn't already set - it helps when
-        # device notifications on triggerring sensor's activity aren't receveid
-        # by a reason
-        if sensor and not sensor.occupancy:
-            await self.on_sensor_activity(event_id, zone_name, True)
+        extra_data = None
+        if sensor:
+            # The callback is still delivered to the caller even if the sensor
+            # isn't found, only `extra_data` is skipped. That is to ensure the
+            # important callback isn't filtered
+            extra_data = sensor.extra_data
+
+            # Invoke the sensor activity callback to set the sensor occupancy
+            # if sensor is known, but only if that isn't already set - it helps
+            # when device notifications on triggerring sensor's activity aren't
+            # receveid by a reason
+            if not sensor.occupancy:
+                await self.on_sensor_activity(event_id, zone_name, True)
+
+            if is_tampered:
+                # Set the tampered flag on the sensor
+                # pylint: disable=protected-access
+                sensor._set_tampered(True)
+
+                # Invoke per-sensor callback if provided
+                G90Callback.invoke(sensor.tamper_callback)
+
+        # Invoke global tamper callback if provided and the sensor is tampered
+        if is_tampered:
+            G90Callback.invoke(self._tamper_cb, event_id, zone_name)
 
         G90Callback.invoke(
             self._alarm_cb, event_id, zone_name, extra_data
@@ -718,7 +716,10 @@ class G90Alarm(G90DeviceNotifications):
 
         # Also report the event as alarm for unification, hard-coding the
         # sensor name in case of host SOS
-        await self.on_alarm(event_id, 'Host SOS' if is_host_sos else zone_name)
+        await self.on_alarm(
+            event_id, zone_name='Host SOS' if is_host_sos else zone_name,
+            is_tampered=False
+        )
 
         if not is_host_sos:
             # Also report the remote button press for SOS - the panel will not
@@ -778,6 +779,58 @@ class G90Alarm(G90DeviceNotifications):
     ) -> None:
         self._remote_button_press_cb = value
 
+    async def on_door_open_when_arming(
+        self, event_id: int, zone_name: str
+    ) -> None:
+        """
+        Invoked when door is open when arming the device. Fires corresponding
+        callback if set by the user with
+        :attr:`.door_open_when_arming_callback`.
+
+        Please note the method is for internal use by the class.
+
+        :param event_id: The index of the sensor being active when the panel
+         is being armed.
+        :param zone_name: The name of the sensor
+        """
+        _LOGGER.debug('on_door_open_when_arming: %s %s', event_id, zone_name)
+        sensor = await self.find_sensor(event_id, zone_name)
+        if sensor:
+            # Set the low battery flag on the sensor
+            # pylint: disable=protected-access
+            sensor._set_door_open_when_arming(True)
+            # Invoke per-sensor callback if provided
+            G90Callback.invoke(sensor.door_open_when_arming_callback)
+
+        G90Callback.invoke(self._door_open_when_arming_cb, event_id, zone_name)
+
+    @property
+    def door_open_when_arming_callback(
+        self
+    ) -> Optional[DoorOpenWhenArmingCallback]:
+        """
+        Door open when arming callback, which is invoked when sensor reports
+        the condition.
+        """
+        return self._door_open_when_arming_cb
+
+    @door_open_when_arming_callback.setter
+    def door_open_when_arming_callback(
+        self, value: DoorOpenWhenArmingCallback
+    ) -> None:
+        self._door_open_when_arming_cb = value
+
+    @property
+    async def tamper_callback(self) -> Optional[TamperCallback]:
+        """
+        Tamper callback, which is invoked when sensor reports the condition.
+        """
+        return self._tamper_cb
+
+    @tamper_callback.setter
+    def tamper_callback(self, value: TamperCallback) -> None:
+        self._tamper_cb = value
+
     async def listen_device_notifications(self) -> None:
         """
         Starts internal listener for device notifications/alerts.

{pyg90alarm-1.17.2 → pyg90alarm-1.20.0}/src/pyg90alarm/const.py

@@ -201,6 +201,7 @@ class G90AlertSources(IntEnum):
     """
     DEVICE = 0
     SENSOR = 1
+    TAMPER = 3
     REMOTE = 10
     RFID = 11
     DOORBELL = 12

{pyg90alarm-1.17.2 → pyg90alarm-1.20.0}/src/pyg90alarm/device_notifications.py

@@ -159,6 +159,16 @@ class G90DeviceNotifications(DatagramProtocol):
 
             return
 
+        # An open door is detected when arming
+        if notification.kind == G90NotificationTypes.DOOR_OPEN_WHEN_ARMING:
+            g90_zone_info = G90ZoneInfo(*notification.data)
+            _LOGGER.debug('Door open detected when arming: %s', g90_zone_info)
+            G90Callback.invoke(
+                self.on_door_open_when_arming,
+                g90_zone_info.idx, g90_zone_info.name
+            )
+            return
+
         _LOGGER.warning('Unknown notification received from %s:%s:'
                         ' kind %s, data %s',
                         addr[0], addr[1], notification.kind, notification.data)
@@ -259,11 +269,15 @@ class G90DeviceNotifications(DatagramProtocol):
                 )
             # Regular alarm
             else:
-                _LOGGER.debug('Alarm: %s', alert.zone_name)
+                is_tampered = alert.state == G90AlertStates.TAMPER
+                _LOGGER.debug(
+                    'Alarm: %s, is tampered: %s', alert.zone_name, is_tampered
+                )
                 G90Callback.invoke(
                     self.on_alarm,
-                    alert.event_id, alert.zone_name
+                    alert.event_id, alert.zone_name, is_tampered
                 )
+
             handled = True
 
         # Host SOS
@@ -372,6 +386,16 @@ class G90DeviceNotifications(DatagramProtocol):
         :param name: Name of the sensor.
         """
 
+    async def on_door_open_when_arming(
+        self, event_id: int, zone_name: str
+    ) -> None:
+        """
+        Invoked when door open is detected when panel is armed.
+
+        :param event_id: Index of the sensor.
+        :param zone_name: Name of the sensor that reports door open.
+        """
+
     async def on_door_open_close(
         self, event_id: int, zone_name: str, is_open: bool
     ) -> None:
@@ -391,7 +415,9 @@ class G90DeviceNotifications(DatagramProtocol):
         :param zone_name: Name of the sensor that reports low battery.
         """
 
-    async def on_alarm(self, event_id: int, zone_name: str) -> None:
+    async def on_alarm(
+        self, event_id: int, zone_name: str, is_tampered: bool
+    ) -> None:
         """
         Invoked when device triggers the alarm.
 

pyg90alarm-1.20.0/src/pyg90alarm/entities/base_entity.py

@@ -0,0 +1,83 @@
+# Copyright (c) 2025 Ilia Sotnikov
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""
+Base entity.
+"""
+from abc import ABC, abstractmethod
+# `Self` has been introduced in Python 3.11, need to use `typing_extensions`
+# for earlier versions
+try:
+    from typing import Self  # type: ignore[attr-defined,unused-ignore]
+except ImportError:
+    from typing_extensions import Self
+
+
+class G90BaseEntity(ABC):
+    """
+    Base entity class.
+
+    Contains minimal set of method for :class:`.G90BaseList` class
+    """
+    @abstractmethod
+    def update(
+        self,
+        obj: Self  # pylint: disable=used-before-assignment
+    ) -> None:
+        """
+        Update the entity from another one.
+
+        :param obj: Object to update from.
+        """
+
+    @property
+    @abstractmethod
+    def is_unavailable(self) -> bool:
+        """
+        Check if the entity is unavailable.
+
+        :return: True if the entity is unavailable.
+        """
+
+    @is_unavailable.setter
+    @abstractmethod
+    def is_unavailable(self, value: bool) -> None:
+        """
+        Set the entity as unavailable.
+
+        :param value: Value to set.
+        """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """
+        Get the name of the entity.
+
+        :return: Name of the entity.
+        """
+
+    @property
+    @abstractmethod
+    def index(self) -> int:
+        """
+        Get the index of the entity.
+
+        :return: Index of the entity.
+        """

pyg90alarm-1.20.0/src/pyg90alarm/entities/base_list.py

@@ -0,0 +1,165 @@
+# Copyright (c) 2025 Ilia Sotnikov
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""
+Base entity list.
+"""
+from abc import ABC, abstractmethod
+from typing import (
+    List, AsyncGenerator, Optional, TypeVar, Generic, cast, TYPE_CHECKING,
+)
+import asyncio
+import logging
+
+from .base_entity import G90BaseEntity
+if TYPE_CHECKING:
+    from ..alarm import G90Alarm
+else:
+    # Alias G90Alarm to object avoid circular imports
+    # (`G90Alarm` -> `G90SensorList` -> `G90BaseList` -> `G90Alarm`)
+    G90Alarm = object
+
+T = TypeVar('T', bound=G90BaseEntity)
+_LOGGER = logging.getLogger(__name__)
+
+
+class G90BaseList(Generic[T], ABC):
+    """
+    Base entity list class.
+
+    :param parent: Parent alarm panel instance.
+    """
+    def __init__(self, parent: G90Alarm) -> None:
+        self._entities: List[T] = []
+        self._lock = asyncio.Lock()
+        self._parent = parent
+
+    @abstractmethod
+    async def _fetch(self) -> AsyncGenerator[T, None]:
+        """
+        Fetch the list of entities from the panel.
+
+        :return: Async generator of entities
+        """
+        yield cast(T, None)
+
+    @property
+    async def entities(self) -> List[T]:
+        """
+        Return the list of entities.
+
+        :meth:`update` is called if the list is empty.
+
+        :return: List of entities
+        """
+        # Please see below for the explanation of the lock usage
+        async with self._lock:
+            entities = self._entities
+
+        if not entities:
+            return await self.update()
+
+        return entities
+
+    async def update(self) -> List[T]:
+        """
+        Update the list of entities from the panel.
+
+        :return: List of entities
+        """
+        # Use lock around the operation, to ensure no duplicated entries in the
+        # resulting list or redundant exchanges with panel are made when the
+        # method is called concurrently
+        async with self._lock:
+            entities = self._fetch()
+
+            non_existing_entities = self._entities.copy()
+            async for entity in entities:
+                try:
+                    existing_entity_idx = self._entities.index(entity)
+                except ValueError:
+                    existing_entity_idx = None
+
+                if existing_entity_idx is not None:
+                    existing_entity = self._entities[existing_entity_idx]
+                    # Update the existing entity with the new data
+                    _LOGGER.debug(
+                        "Updating existing entity '%s' from protocol"
+                        " data '%s'", existing_entity, entity
+                    )
+
+                    self._entities[existing_entity_idx].update(entity)
+                    non_existing_entities.remove(entity)
+                else:
+                    # Add the new entity to the list
+                    _LOGGER.debug('Adding new entity: %s', entity)
+                    self._entities.append(entity)
+
+            # Mark the entities that are no longer in the list
+            for unavailable_entity in non_existing_entities:
+                _LOGGER.debug(
+                    'Marking entity as unavailable: %s', unavailable_entity
+                )
+                unavailable_entity.is_unavailable = True
+
+            _LOGGER.debug(
+                'Total number of entities: %s, unavailable: %s',
+                len(self._entities), len(non_existing_entities)
+            )
+
+            return self._entities
+
+    async def find(
+        self, idx: int, name: str, exclude_unavailable: bool
+    ) -> Optional[T]:
+        """
+        Finds entity by index and name.
+
+        :param idx: Entity index
+        :param name: Entity name
+        :param exclude_unavailable: Exclude unavailable entities
+        :return: Entity instance
+        """
+        entities = await self.entities
+
+        found = None
+        # Fast lookup by direct index
+        if idx < len(entities) and entities[idx].name == name:
+            entity = entities[idx]
+            _LOGGER.debug('Found entity via fast lookup: %s', entity)
+            found = entity
+
+        # Fast lookup failed, perform slow one over the whole entities list
+        if not found:
+            for entity in entities:
+                if entity.index == idx and entity.name == name:
+                    _LOGGER.debug('Found entity: %s', entity)
+                    found = entity
+
+        if found:
+            if not exclude_unavailable or not found.is_unavailable:
+                return found
+
+            _LOGGER.debug(
+                'Entity is found but unavailable, will result in none returned'
+            )
+
+        _LOGGER.error('Entity not found: idx=%s, name=%s', idx, name)
+        return None