pyg90alarm 1.12.1__py3-none-any.whl → 1.14.0__py3-none-any.whl

pyg90alarm/base_cmd.py

@@ -21,43 +21,46 @@
 """
 Provides support for basic commands of G90 alarm panel.
 """
-
+from __future__ import annotations
 import logging
 import json
 import asyncio
-from typing import NamedTuple, Optional
+from asyncio import Future
+from asyncio.protocols import DatagramProtocol
+from asyncio.transports import DatagramTransport, BaseTransport
+from typing import Optional, Tuple, List, Any
+from dataclasses import dataclass
 from .exceptions import (G90Error, G90TimeoutError)
+from .const import G90Commands
 
 
 _LOGGER = logging.getLogger(__name__)
+G90BaseCommandData = List[Any]
 
 
-class G90Header(NamedTuple):
+@dataclass
+class G90Header:
     """
     Represents JSON structure of the header used in alarm panel commands.
-    Note that typing.NamedTuple is used (instead of collections.namedtuple) to
-    provide support for Python 3.6 and higher, while providing default values.
 
     :meta private:
     """
     code: Optional[int] = None
-    data: Optional[str] = None
+    data: Optional[G90BaseCommandData] = None
 
 
-class G90BaseCommand:
+class G90BaseCommand(DatagramProtocol):
     """
-    tbd
+    Implements basic command handling for alarm panel protocol.
     """
     # pylint: disable=too-many-instance-attributes
     # Lock need to be shared across all of the class instances
     _sk_lock = asyncio.Lock()
 
-    def __init__(self, host, port, code,
-                 data=None, local_port=None,
-                 timeout=3.0, retries=3):
-        """
-        tbd
-        """
+    def __init__(self, host: str, port: int, code: G90Commands,
+                 data: Optional[G90BaseCommandData] = None,
+                 local_port: Optional[int] = None,
+                 timeout: float = 3.0, retries: int = 3) -> None:
         # pylint: disable=too-many-arguments
         self._remote_host = host
         self._remote_port = port
@@ -66,8 +69,10 @@ class G90BaseCommand:
         self._timeout = timeout
         self._retries = retries
         self._data = '""'
-        self._result = None
-        self._connection_result = None
+        self._result: G90BaseCommandData = []
+        self._connection_result: Optional[
+            Future[Tuple[str, int, bytes]]
+        ] = None
         if data:
             self._data = json.dumps([code, data],
                                     # No newlines to be inserted
@@ -78,19 +83,19 @@ class G90BaseCommand:
 
     # Implementation of datagram protocol,
     # https://docs.python.org/3/library/asyncio-protocol.html#datagram-protocols
-    def connection_made(self, transport):
+    def connection_made(self, transport: BaseTransport) -> None:
         """
-        tbd
+        Invoked when connection is established.
         """
 
-    def connection_lost(self, exc):
+    def connection_lost(self, exc: Optional[Exception]) -> None:
         """
-        tbd
+        Invoked when connection is lost.
         """
 
-    def datagram_received(self, data, addr):
+    def datagram_received(self, data: bytes, addr: Tuple[str, int]) -> None:
         """
-        tbd
+        Invoked when datagram is received.
         """
         if asyncio.isfuture(self._connection_result):
             if self._connection_result.done():
@@ -100,9 +105,9 @@ class G90BaseCommand:
                 return
             self._connection_result.set_result((*addr, data))
 
-    def error_received(self, exc):
+    def error_received(self, exc: Exception) -> None:
         """
-        tbd
+        Invoked when error is received.
         """
         if (
             asyncio.isfuture(self._connection_result) and not
@@ -110,9 +115,11 @@ class G90BaseCommand:
         ):
             self._connection_result.set_exception(exc)
 
-    async def _create_connection(self):
+    async def _create_connection(self) -> (
+        Tuple[DatagramTransport, DatagramProtocol]
+    ):
         """
-        tbd
+        Creates UDP connection to the alarm panel.
         """
         try:
             loop = asyncio.get_running_loop()
@@ -121,38 +128,38 @@ class G90BaseCommand:
 
         _LOGGER.debug('Creating UDP endpoint for %s:%s',
                       self.host, self.port)
-        extra_kwargs = {}
+        local_addr = None
         if self._local_port:
-            extra_kwargs['local_addr'] = ('0.0.0.0', self._local_port)
+            local_addr = ('0.0.0.0', self._local_port)
 
         transport, protocol = await loop.create_datagram_endpoint(
             lambda: self,
             remote_addr=(self.host, self.port),
-            **extra_kwargs,
-            allow_broadcast=True)
+            allow_broadcast=True,
+            local_addr=local_addr)
 
-        return transport, protocol
+        return (transport, protocol)
 
-    def to_wire(self):
+    def to_wire(self) -> bytes:
         """
-        tbd
+        Returns the command in wire format.
         """
         wire = bytes(f'ISTART[{self._code},{self._code},{self._data}]IEND\0',
                      'utf-8')
         _LOGGER.debug('Encoded to wire format %s', wire)
         return wire
 
-    def from_wire(self, data):
+    def from_wire(self, data: bytes) -> G90BaseCommandData:
         """
-        tbd
+        Parses the response from the alarm panel.
         """
         _LOGGER.debug('To be decoded from wire format %s', data)
         self._parse(data.decode('utf-8', errors='ignore'))
-        return self._resp.data
+        return self._resp.data or []
 
-    def _parse(self, data):
+    def _parse(self, data: str) -> None:
         """
-        tbd
+        Processes the response from the alarm panel.
         """
         if not data.startswith('ISTART'):
             raise G90Error('Missing start marker in data')
@@ -189,39 +196,40 @@ class G90BaseCommand:
                     f"{self._resp.code}, expected code {self._code}")
 
     @property
-    def result(self):
+    def result(self) -> G90BaseCommandData:
         """
-        tbd
+        The result of the command.
         """
         return self._result
 
     @property
-    def host(self):
+    def host(self) -> str:
         """
-        tbd
+        The hostname/IP address of the alarm panel.
         """
         return self._remote_host
 
     @property
-    def port(self):
+    def port(self) -> int:
         """
-        tbd
+        The port of the alarm panel.
         """
         return self._remote_port
 
-    async def process(self):
+    async def process(self) -> G90BaseCommand:
         """
-        tbd
+        Processes the command.
         """
+        # Disallow using `NONE` command, which is intended to use by inheriting
+        # classes overriding `process()` method
+        if self._code == G90Commands.NONE:
+            raise G90Error("'NONE' command code is disallowed")
 
         transport, _ = await self._create_connection()
         attempts = self._retries
         while True:
             attempts = attempts - 1
-            try:
-                loop = asyncio.get_running_loop()
-            except AttributeError:
-                loop = asyncio.get_event_loop()
+            loop = asyncio.get_running_loop()
             self._connection_result = loop.create_future()
             async with self._sk_lock:
                 _LOGGER.debug('(code %s) Sending request to %s:%s',
@@ -253,9 +261,9 @@ class G90BaseCommand:
         self._result = ret
         return self
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         """
-        tbd
+        Returns string representation of the command.
         """
         return f'Command: {self._code}, request: {self._data},' \
             f' response: {self._resp.data}'

pyg90alarm/callback.py

@@ -21,22 +21,33 @@
 """
 Implements callbacks.
 """
-
+from __future__ import annotations
 import asyncio
 from functools import (partial, wraps)
+from asyncio import Task
+from typing import Any, Callable, Coroutine, cast, Optional, Union
 import logging
 
 _LOGGER = logging.getLogger(__name__)
 
+Callback = Optional[
+    Union[
+        Callable[..., None],
+        Callable[..., Coroutine[None, None, None]],
+    ]
+]
+
 
 class G90Callback:
     """
-    tbd
+    Implements callbacks.
     """
     @staticmethod
-    def invoke(callback, *args, **kwargs):
+    def invoke(
+        callback: Callback, *args: Any, **kwargs: Any
+    ) -> None:
         """
-        tbd
+        Invokes the callback.
         """
         if not callback:
             return
@@ -46,73 +57,52 @@ class G90Callback:
                       callback, args, kwargs)
 
         if not asyncio.iscoroutinefunction(callback):
-            def async_wrapper(func):
+            def async_wrapper(
+                func: Callable[..., None]
+            ) -> Callable[..., Coroutine[Any, Any, None]]:
                 """
                 Wraps the regular callback function into coroutine, so it could
                 later be created as async task.
                 """
                 @wraps(func)
-                async def wrapper(*args, **kwds):
+                async def wrapper(
+                    *args: Any, **kwds: Any
+                ) -> None:
                     return func(*args, **kwds)
-                return wrapper
 
-            callback = async_wrapper(callback)
+                return cast(Callable[..., Coroutine[Any, Any, None]], wrapper)
 
-        if hasattr(asyncio, 'create_task'):
-            task = asyncio.create_task(callback(*args, **kwargs))
+            task = asyncio.create_task(
+                async_wrapper(
+                    cast(Callable[..., None], callback)
+                )(*args, **kwargs)
+            )
         else:
-            # Python 3.6 has only `ensure_future` method
-            task = asyncio.ensure_future(callback(*args, **kwargs))
+            task = asyncio.create_task(callback(*args, **kwargs))
 
-        def reap_callback_exception(task):
+        def reap_callback_exception(task: Task[Any]) -> None:
             """
             Reaps an exception (if any) from the task logging it, to prevent
             `asyncio` reporting that task exception was never retrieved.
             """
             exc = task.exception()
             if exc:
-                _LOGGER.error('Got exception when invoking'
-                              " callback '%s(...)':",
-                              task.get_coro().__qualname__,
-                              exc_info=exc, stack_info=False)
+                _LOGGER.error(
+                    "Got exception when invoking callback '%s(...)':",
+                    cast(
+                        Coroutine[Any, Any, None], task.get_coro()
+                    ).__qualname__,
+                    exc_info=exc, stack_info=False
+                )
 
         task.add_done_callback(reap_callback_exception)
 
     @staticmethod
-    def invoke_delayed(delay, callback, *args, **kwargs):
+    def invoke_delayed(
+        delay: float, callback: Callable[..., None], *args: Any, **kwargs: Any
+    ) -> None:
         """
-        tbd
+        Invokes the callback after a delay.
         """
-        if hasattr(asyncio, 'get_running_loop'):
-            loop = asyncio.get_running_loop()
-        else:
-            # Python 3.6 has no `get_running_loop`, only `get_event_loop`
-            loop = asyncio.get_event_loop()
+        loop = asyncio.get_running_loop()
         loop.call_later(delay, partial(callback, *args, **kwargs))
-
-
-def async_as_sync(func):
-    """
-    Invokes an async function as regular one via :py:func:`G90Callback.invoke`.
-    One of possible use cases is implementing property setter for async code,
-    where the function could be used an decorator:
-
-    .. code-block:: python
-
-     @property
-     async def a_property(...):
-         ...
-
-     @a_property.setter
-     @async_as_sync
-     async def a_property(...):
-         ...
-
-    Since the function internally submits the wrapped async code as
-    :py:mod:`asyncio` task, it execution isn't guaranteed as the program could
-    be terminated earlier that it is processed in the loop.
-    """
-    @wraps(func)
-    def wrapper(*args, **kwargs):
-        return G90Callback.invoke(func, *args, **kwargs)
-    return wrapper

pyg90alarm/config.py

@@ -21,12 +21,15 @@
 """
 Represents various configuration aspects of the alarm panel.
 """
+from __future__ import annotations
 from enum import IntFlag
-from collections import namedtuple
+from dataclasses import dataclass
 
 
 class G90AlertConfigFlags(IntFlag):
-    """ Alert configuration flags, used bitwise """
+    """
+    Alert configuration flags, used bitwise
+    """
     AC_POWER_FAILURE = 1
     AC_POWER_RECOVER = 2
     ARM_DISARM = 4
@@ -41,15 +44,16 @@ class G90AlertConfigFlags(IntFlag):
     UNKNOWN2 = 8192
 
 
-class G90AlertConfig(namedtuple('G90AlertConfig', ['flags_data'])):
+@dataclass
+class G90AlertConfig:
     """
     Represents alert configuration as received from the alarm panel.
     """
+    flags_data: int
 
     @property
-    def flags(self):
+    def flags(self) -> G90AlertConfigFlags:
         """
-        :return: Instance of :class:`G90AlertConfigFlags` that provides
-         symbolic names to corresponding flag bits
+        :return: Symbolic names for corresponding flag bits
         """
         return G90AlertConfigFlags(self.flags_data)

pyg90alarm/const.py

@@ -21,8 +21,9 @@
 """
 Definies different constants for G90 alarm panel.
 """
-
+from __future__ import annotations
 from enum import IntEnum
+from typing import Optional
 
 REMOTE_PORT = 12368
 REMOTE_TARGETED_DISCOVERY_PORT = 12900
@@ -40,7 +41,7 @@ class G90Commands(IntEnum):
     comprehensive or complete.
     """
 
-    def __new__(cls, value, doc=None):
+    def __new__(cls, value: int, doc: Optional[str] = None) -> G90Commands:
         """
         Allows to set the docstring along with the value to enum entry.
         """
@@ -49,6 +50,12 @@ class G90Commands(IntEnum):
         obj.__doc__ = doc
         return obj
 
+    NONE = (0, """
+        Pseudo command, to be used for proper typing with subclasses of
+        `G90BaseCommand` invoking its constructor but implementing special
+        processing
+    """)
+
     # Host status
     GETHOSTSTATUS = (100, 'Get host status')
     SETHOSTSTATUS = (101, 'Set host status')

pyg90alarm/definitions/sensors.py

@@ -22,7 +22,7 @@
 Sensor definitions for G90 devices, required when modifying them since writing
 a sensor to the device requires values not present on read.
 """
-from collections import namedtuple
+from typing import NamedTuple
 from enum import IntEnum
 
 
@@ -44,21 +44,22 @@ class SensorRwMode(IntEnum):
     READ_WRITE = 2
 
 
-class SensorDefinition(
-    namedtuple(
-        'SensorDefinition', [
-            'type', 'subtype', 'rx', 'tx',
-            'private_data', 'rwMode', 'matchMode',
-        ]
-    )
-):
+class SensorDefinition(NamedTuple):
     """
     Holds sensor definition data.
     """
+    type: int
+    subtype: int
+    rx: int
+    tx: int
+    private_data: str
+    rwMode: SensorRwMode
+    matchMode: SensorMatchMode
+
     @property
-    def reserved_data(self):
+    def reserved_data(self) -> int:
         """
-        Returns sensor 'reserved_data' field to be written, combined of match
+        Sensor's 'reserved_data' field to be written, combined of match
         and RW mode values bitwise.
         """
         return self.matchMode.value << 4 | self.rwMode.value