pyg90alarm 1.13.0__py3-none-any.whl → 1.15.0__py3-none-any.whl

pyg90alarm/entities/sensor.py

@@ -21,48 +21,67 @@
 """
 Provides interface to sensors of G90 alarm panel.
 """
-
+from __future__ import annotations
 import logging
-from collections import namedtuple
+from dataclasses import dataclass, asdict, astuple
+from typing import (
+    Any, Optional, TYPE_CHECKING, Dict
+)
+
 from enum import IntEnum, IntFlag
-from ..definitions.sensors import SENSOR_DEFINITIONS
+from ..definitions.sensors import SENSOR_DEFINITIONS, SensorDefinition
 from ..const import G90Commands
+if TYPE_CHECKING:
+    from ..alarm import G90Alarm, SensorStateCallback, SensorLowBatteryCallback
 
-# Common protocol fields across read and write operations
-COMMON_FIELDS = [
-    'parent_name',
-    'index',
-    'room_id',
-    'type_id',
-    'subtype',
-    'timeout',
-    'user_flag_data',
-    'baudrate',
-    'protocol_id',
-    'reserved_data',
-    'node_count',
-]
-
-# Incoming (read operation) protocol fields
-INCOMING_FIELDS = COMMON_FIELDS + [
-    'mask',
-    'private_data',
-]
-
-# Outgoing (write operation) protocol fields
-OUTGOING_FIELDS = COMMON_FIELDS + [
-    'rx',
-    'tx',
-    'private_data',
-]
 
+@dataclass
+class G90SensorCommonData:  # pylint:disable=too-many-instance-attributes
+    """
+    Common protocol fields across read and write operations.
 
-class G90SensorReservedFlags(IntFlag):
+    :meta private:
     """
-    Reserved flags of the sensor.
+    parent_name: str
+    index: int
+    room_id: int
+    type_id: int
+    subtype: int
+    timeout: int
+    user_flag_data: int
+    baudrate: int
+    protocol_id: int
+    reserved_data: int
+    node_count: int
+
+
+@dataclass
+class G90SensorIncomingData(G90SensorCommonData):
+    """
+    Incoming (read operation) protocol fields.
 
     :meta private:
     """
+    mask: int
+    private_data: str
+
+
+@dataclass
+class G90SensorOutgoingData(G90SensorCommonData):
+    """
+    Outgoing (write operation) protocol fields.
+
+    :meta private:
+    """
+    rx: int  # pylint:disable=invalid-name
+    tx: int  # pylint:disable=invalid-name
+    private_data: str
+
+
+class G90SensorReservedFlags(IntFlag):
+    """
+    Reserved flags of the sensor.
+    """
     NONE = 0
     CAN_READ = 16
     CAN_READ_EXT = 32
@@ -72,8 +91,6 @@ class G90SensorReservedFlags(IntFlag):
 class G90SensorUserFlags(IntFlag):
     """
     User flags of the sensor.
-
-    :meta private:
     """
     NONE = 0
     ENABLED = 1
@@ -89,8 +106,6 @@ class G90SensorUserFlags(IntFlag):
 class G90SensorProtocols(IntEnum):
     """
     Protocol types for the sensors.
-
-    :meta private:
     """
     RF_1527 = 0
     RF_2262 = 1
@@ -104,8 +119,6 @@ class G90SensorProtocols(IntEnum):
 class G90SensorTypes(IntEnum):
     """
     Sensor types.
-
-    :meta private:
     """
     DOOR = 1
     GLASS = 2
@@ -160,23 +173,23 @@ class G90Sensor:  # pylint:disable=too-many-instance-attributes
     :param kwargs: Pass-through keyword arguments for for interpreting protocol
      fields
     """
-    def __init__(self, *args, parent, subindex, proto_idx, **kwargs):
-        self._protocol_incoming_data_kls = (
-            namedtuple('G90SensorIncomingData', INCOMING_FIELDS)
-        )
-        self._protocol_outgoing_data_kls = (
-            namedtuple('G90SensorOutgoingData', OUTGOING_FIELDS)
-        )
+    def __init__(
+        self, *args: Any, parent: G90Alarm, subindex: int, proto_idx: int,
+        **kwargs: Any
+    ) -> None:
+        self._protocol_incoming_data_kls = G90SensorIncomingData
+        self._protocol_outgoing_data_kls = G90SensorOutgoingData
         self._protocol_data = self._protocol_incoming_data_kls(*args, **kwargs)
         self._parent = parent
         self._subindex = subindex
         self._occupancy = False
-        self._state_callback = None
-        self._low_battery_callback = None
+        self._state_callback: Optional[SensorStateCallback] = None
+        self._low_battery_callback: Optional[SensorLowBatteryCallback] = None
+        self._low_battery = False
         self._proto_idx = proto_idx
-        self._extra_data = None
+        self._extra_data: Any = None
 
-        self._definition = None
+        self._definition: Optional[SensorDefinition] = None
         # Get sensor definition corresponds to the sensor type/subtype if any
         for s_def in SENSOR_DEFINITIONS:
             if (
@@ -187,184 +200,208 @@ class G90Sensor:  # pylint:disable=too-many-instance-attributes
                 break
 
     @property
-    def name(self):
+    def name(self) -> str:
         """
-        Returns sensor name, accounting for multi-channel entities (single
+        Sensor name, accounting for multi-channel entities (single
         protocol entity results in multiple :class:`.G90Sensor` instances).
 
         :return: Sensor name
-        :rtype: str
         """
         if self._protocol_data.node_count == 1:
             return self._protocol_data.parent_name
         return f'{self._protocol_data.parent_name}#{self._subindex + 1}'
 
     @property
-    def state_callback(self):
+    def state_callback(self) -> Optional[SensorStateCallback]:
         """
-        Returns state callback the sensor might have set.
+        Callback that is invoked when the sensor changes its state.
 
         :return: Sensor state callback
-        :rtype: object
         """
         return self._state_callback
 
     @state_callback.setter
-    def state_callback(self, value):
-        """
-        Sets callback for the state changes of the sensor.
-
-        :param object value: Sensor state callback
-        """
+    def state_callback(self, value: SensorStateCallback) -> None:
         self._state_callback = value
 
     @property
-    def low_battery_callback(self):
+    def low_battery_callback(self) -> Optional[SensorLowBatteryCallback]:
         """
-        Returns callback the sensor might have set for low battery condition.
+        Callback that is invoked when the sensor reports on low battery
+        condition.
 
         :return: Sensor's low battery callback
-        :rtype: object
         """
         return self._low_battery_callback
 
     @low_battery_callback.setter
-    def low_battery_callback(self, value):
-        """
-        Sets callback for the low battery condition reported by the sensor.
-
-        :param object value: Sensor's low battery callback
-        """
+    def low_battery_callback(self, value: SensorLowBatteryCallback) -> None:
         self._low_battery_callback = value
 
     @property
-    def occupancy(self):
+    def occupancy(self) -> bool:
         """
         Occupancy (occupied/not occupied, or triggered/not triggered)
         for the sensor.
 
         :return: Sensor occupancy
-        :rtype: bool
         """
         return self._occupancy
 
-    @occupancy.setter
-    def occupancy(self, value):
+    def _set_occupancy(self, value: bool) -> None:
         """
-        Sets occupancy state for the sensor.
+        Sets occupancy state of the sensor.
+        Intentionally private, as occupancy state is derived from
+        notifications/alerts.
 
-        :param bool value: Sensor occupancy
+        :param value: Occupancy state
         """
+        _LOGGER.debug(
+            "Setting occupancy for sensor index=%s: '%s' %s"
+            " (previous value: %s)",
+            self.index, self.name, value, self._occupancy
+        )
         self._occupancy = value
 
     @property
-    def protocol(self):
+    def protocol(self) -> G90SensorProtocols:
         """
-        Returns protocol type of the sensor.
+        Protocol type of the sensor.
 
         :return: Protocol type
-        :rtype: int
         """
         return G90SensorProtocols(self._protocol_data.protocol_id)
 
     @property
-    def type(self):
+    def type(self) -> G90SensorTypes:
         """
-        Returns type of the sensor.
+        Type of the sensor.
 
         :return: Sensor type
-        :rtype: int
         """
         return G90SensorTypes(self._protocol_data.type_id)
 
     @property
-    def reserved(self):
+    def subtype(self) -> int:
+        """
+        Sub-type of the sensor.
+
+        :return: Sensor sub-type
         """
-        Returns reserved flags (read/write mode) for the sensor.
+        return self._protocol_data.subtype
+
+    @property
+    def reserved(self) -> G90SensorReservedFlags:
+        """
+        Reserved flags (read/write mode) for the sensor.
 
         :return: Reserved flags
-        :rtype: int
         """
         return G90SensorReservedFlags(self._protocol_data.reserved_data)
 
     @property
-    def user_flag(self):
+    def user_flag(self) -> G90SensorUserFlags:
         """
-        Returns user flags for the sensor (disabled/enabled, arming type etc).
+        User flags for the sensor (disabled/enabled, arming type etc).
 
         :return: User flags
-        :rtype: int
         """
         return G90SensorUserFlags(self._protocol_data.user_flag_data)
 
     @property
-    def node_count(self):
+    def node_count(self) -> int:
         """
-        Returns number of nodes (channels) for the sensor.
+        Number of nodes (channels) for the sensor.
 
         :return: Number of nodes
-        :rtype: int
         """
         return self._protocol_data.node_count
 
     @property
-    def parent(self):
+    def parent(self) -> G90Alarm:
         """
-        Returns parent :class:`.G90Alarm` instance the sensor is associated
+        Parent instance of alarm panel class the sensor is associated
         with.
 
-        :return: Parent :class:`.G90Alarm` instance
-        :rtype: :class:`.G90Alarm`
+        :return: Parent instance
         """
         return self._parent
 
     @property
-    def index(self):
+    def index(self) -> int:
         """
-        Returns index (internal position) of the sensor in the G90 alarm panel.
+        Index (internal position) of the sensor in the alarm panel.
 
         :return: Internal sensor position
-        :rtype: int
         """
         return self._protocol_data.index
 
     @property
-    def subindex(self):
+    def subindex(self) -> int:
         """
-        Returns index of the sensor within multi-node device.
+        Index of the sensor within multi-node device.
 
         :return: Index of sensor in multi-node device.
-        :rtype: int
         """
         return self._subindex
 
     @property
-    def supports_enable_disable(self):
+    def supports_enable_disable(self) -> bool:
         """
         Indicates if disabling/enabling the sensor is supported.
 
         :return: Support for enabling/disabling the sensor
-        :rtype: bool
         """
         return self._definition is not None
 
     @property
-    def enabled(self):
+    def is_wireless(self) -> bool:
+        """
+        Indicates if the sensor is wireless.
+        """
+        return self.protocol not in (G90SensorProtocols.CORD,)
+
+    @property
+    def is_low_battery(self) -> bool:
+        """
+        Indicates if the sensor is reporting low battery.
+        """
+        return self._low_battery
+
+    def _set_low_battery(self, value: bool) -> None:
+        """
+        Sets low battery state of the sensor.
+        Intentionally private, as low battery state is derived from
+        notifications/alerts.
+
+        :param value: Low battery state
+        """
+        _LOGGER.debug(
+            "Setting low battery for sensor index=%s '%s': %s"
+            " (previous value: %s)",
+            self.index, self.name, value, self._low_battery
+        )
+        self._low_battery = value
+
+    @property
+    def enabled(self) -> bool:
         """
         Indicates if the sensor is enabled.
 
         :return: If sensor is enabled
-        :rtype: bool
         """
-        return self.user_flag & G90SensorUserFlags.ENABLED
+        return self.user_flag & G90SensorUserFlags.ENABLED != 0
 
-    async def set_enabled(self, value):
+    async def set_enabled(self, value: bool) -> None:
         """
         Sets disabled/enabled state of the sensor.
 
-        :param bool value: Whether to enable or disable the sensor
+        :param value: Whether to enable or disable the sensor
         """
-        if not self.supports_enable_disable:
+        # Checking private attribute directly, since `mypy` doesn't recognize
+        # the check for sensor definition to be defined if done over
+        # `self.supports_enable_disable` property
+        if not self._definition:
             _LOGGER.warning(
                 'Manipulating with enable/disable for sensor index=%s'
                 ' is unsupported - no sensor definition for'
@@ -388,7 +425,7 @@ class G90Sensor:  # pylint:disable=too-many-instance-attributes
             G90Commands.GETSENSORLIST,
             start=self._proto_idx, end=self._proto_idx
         )
-        sensors = [x async for x in sensors_result]
+        sensors = [x.data async for x in sensors_result]
 
         # Abort if sensor is not found
         if not sensors:
@@ -401,7 +438,7 @@ class G90Sensor:  # pylint:disable=too-many-instance-attributes
 
         # Compare actual sensor data from what the sensor has been instantiated
         # from, and abort the operation if out-of-band changes are detected.
-        _sensor_pos, sensor_data = sensors[0]
+        sensor_data = sensors[0]
         if self._protocol_incoming_data_kls(
             *sensor_data
         ) != self._protocol_data:
@@ -422,7 +459,7 @@ class G90Sensor:  # pylint:disable=too-many-instance-attributes
             user_flag &= ~G90SensorUserFlags.ENABLED
 
         # Re-instantiate the protocol data with modified user flags
-        _data = self._protocol_data._asdict()
+        _data = asdict(self._protocol_data)
         _data['user_flag_data'] = user_flag
         self._protocol_data = self._protocol_incoming_data_kls(**_data)
 
@@ -454,32 +491,49 @@ class G90Sensor:  # pylint:disable=too-many-instance-attributes
         )
         # Modify the sensor
         await self._parent.command(
-            G90Commands.SETSINGLESENSOR, list(outgoing_data)
+            G90Commands.SETSINGLESENSOR, list(astuple(outgoing_data))
         )
 
     @property
-    def extra_data(self):
+    def extra_data(self) -> Any:
         """
-        Sets extra data for the sensor, that can be used to store
+        Extra data for the sensor, that can be used to store
         caller-specific information and will be carried by the sensor instance.
         """
         return self._extra_data
 
     @extra_data.setter
-    def extra_data(self, val):
+    def extra_data(self, val: Any) -> None:
         self._extra_data = val
 
-    def __repr__(self):
+    def _asdict(self) -> Dict[str, Any]:
+        """
+        Returns dictionary representation of the sensor.
+
+        :return: Dictionary representation
+        """
+        return {
+            'name': self.name,
+            'type': self.type,
+            'subtype': self.subtype,
+            'index': self.index,
+            'subindex': self.subindex,
+            'node_count': self.node_count,
+            'protocol': self.protocol,
+            'occupancy': self.occupancy,
+            'user_flag': self.user_flag,
+            'reserved': self.reserved,
+            'extra_data': self.extra_data,
+            'enabled': self.enabled,
+            'supports_enable_disable': self.supports_enable_disable,
+            'is_wireless': self.is_wireless,
+            'is_low_battery': self.is_low_battery,
+        }
+
+    def __repr__(self) -> str:
         """
         Returns string representation of the sensor.
 
         :return: String representation
-        :rtype: str
-        """
-        return super().__repr__() + f"(name='{str(self.name)}'" \
-            f' type={str(self.type)}' \
-            f' protocol={str(self.protocol)}' \
-            f' occupancy={self.occupancy}' \
-            f' user flag={str(self.user_flag)}' \
-            f' reserved={str(self.reserved)}' \
-            f" extra_data={str(self.extra_data)})"
+        """
+        return super().__repr__() + f'({repr(self._asdict())})'

pyg90alarm/history.py

@@ -21,9 +21,9 @@
 """
 History protocol entity.
 """
-
+from typing import Any, Optional, Dict
+from dataclasses import dataclass
 from datetime import datetime, timezone
-from collections import namedtuple
 from .const import (
     G90AlertTypes,
     G90AlertSources,
@@ -65,52 +65,50 @@ states_mapping = {
         G90HistoryStates.WIFI_DISCONNECTED,
 }
 
-INCOMING_FIELDS = [
-    'type',
-    'event_id',
-    'source',
-    'state',
-    'sensor_name',
-    'unix_time',
-    'other',
-]
-# Class representing the data incoming from the device
-ProtocolData = namedtuple('ProtocolData', INCOMING_FIELDS)
+
+@dataclass
+class ProtocolData:
+    """
+    Class representing the data incoming from the device
+
+    :meta private:
+    """
+    type: G90AlertTypes
+    event_id: G90AlertStateChangeTypes
+    source: G90AlertSources
+    state: int
+    sensor_name: str
+    unix_time: int
+    other: str
 
 
 class G90History:
     """
-    tbd
+    Represents a history entry from the alarm panel.
     """
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args: Any, **kwargs: Any):
         self._protocol_data = ProtocolData(*args, **kwargs)
 
     @property
-    def datetime(self):
+    def datetime(self) -> datetime:
         """
         Date/time of the history entry.
-
-        :rtype: :class:`datetime.datetime`
         """
         return datetime.fromtimestamp(
             self._protocol_data.unix_time, tz=timezone.utc
         )
 
     @property
-    def type(self):
+    def type(self) -> G90AlertTypes:
         """
         Type of the history entry.
-
-        :rtype: :class:`.G90AlertTypes`
         """
         return G90AlertTypes(self._protocol_data.type)
 
     @property
-    def state(self):
+    def state(self) -> G90HistoryStates:
         """
         State for the history entry.
-
-        :rtype: :class:`.G90HistoryStates`
         """
         # Door open/close type, mapped against `G90AlertStates` using `state`
         # incoming field
@@ -140,11 +138,9 @@ class G90History:
         )
 
     @property
-    def source(self):
+    def source(self) -> G90AlertSources:
         """
         Source of the history entry.
-
-        :rtype: :class:`.G90AlertSources`
         """
         # Device state changes or open/close events are mapped against
         # `G90AlertSources` using `source` incoming field
@@ -162,22 +158,18 @@ class G90History:
         return G90AlertSources.DEVICE
 
     @property
-    def sensor_name(self):
+    def sensor_name(self) -> Optional[str]:
         """
         Name of the sensor related to the history entry, might be empty if none
         associated.
-
-        :rtype: str|None
         """
         return self._protocol_data.sensor_name or None
 
     @property
-    def sensor_idx(self):
+    def sensor_idx(self) -> Optional[int]:
         """
         ID of the sensor related to the history entry, might be empty if none
         associated.
-
-        :rtype: str|None
         """
         # Sensor ID will only be available if entry source is a sensor
         if self.source == G90AlertSources.SENSOR:
@@ -185,12 +177,10 @@ class G90History:
 
         return None
 
-    def as_device_alert(self):
+    def as_device_alert(self) -> G90DeviceAlert:
         """
         Returns the history entry represented as device alert structure,
         suitable for :meth:`G90DeviceNotifications._handle_alert`.
-
-        :rtype: :class:`.G90DeviceAlert`
         """
         return G90DeviceAlert(
             type=self._protocol_data.type,
@@ -198,21 +188,27 @@ class G90History:
             source=self._protocol_data.source,
             state=self._protocol_data.state,
             zone_name=self._protocol_data.sensor_name,
-            device_id=None,
+            device_id='',
             unix_time=self._protocol_data.unix_time,
-            resv4=None,
+            resv4=0,
             other=self._protocol_data.other
         )
 
-    def __repr__(self):
+    def _asdict(self) -> Dict[str, Any]:
         """
-        Textural representation of the history entry.
+        Returns the history entry as dictionary.
+        """
+        return {
+            'type': self.type,
+            'source': self.source,
+            'state': self.state,
+            'sensor_name': self.sensor_name,
+            'sensor_idx': self.sensor_idx,
+            'datetime': self.datetime,
+        }
 
-        :rtype: str
+    def __repr__(self) -> str:
+        """
+        Textural representation of the history entry.
         """
-        return f'type={repr(self.type)}' \
-            + f' source={repr(self.source)}' \
-            + f' state={repr(self.state)}' \
-            + f' sensor_name={self.sensor_name}' \
-            + f' sensor_idx={self.sensor_idx}' \
-            + f' datetime={repr(self.datetime)}'
+        return super().__repr__() + f'({repr(self._asdict())})'