xaal.lib 0.7.7__py3-none-any.whl → 0.7.8__py3-none-any.whl

xaal/lib/devices.py

@@ -18,127 +18,156 @@
 #  along with xAAL. If not, see <http://www.gnu.org/licenses/>.
 #
 
+import logging
+import time
+import typing
+from typing import Any, Optional, Union, Callable, Awaitable
+
+from tabulate import tabulate
 
-from . import config
-from . import tools
-from . import bindings
+from . import bindings, config, tools
 from .exceptions import DeviceError
 
-from tabulate import tabulate
-import logging
+if typing.TYPE_CHECKING:
+    from .aioengine import AsyncEngine
+    from .engine import Engine
+    from .core import EngineMixin
+
+# Funtion types with any arguments and return a dict or None (device methods)
+MethodT = Union[Callable[..., Union[dict, None]], Callable[..., Awaitable[Union[dict, None]]]]
+
 logger = logging.getLogger(__name__)
 
-import time
 
 class Attribute(object):
-
-    def __init__(self, name, dev=None, default=None):
+    def __init__(self, name, dev: Optional['Device'] = None, default: Any = None):
         self.name = name
         self.default = default
-        self.device = dev
+        self.device: Optional['Device'] = dev
         self.__value = default
 
     @property
-    def value(self):
+    def value(self) -> Any:
         return self.__value
 
     @value.setter
-    def value(self, value):
+    def value(self, value: Any):
         if value != self.__value and self.device:
             eng = self.device.engine
             if eng:
                 eng.add_attributes_change(self)
-                logger.debug("Attr change %s %s=%s" % (self.device.address,self.name,value))
+                logger.debug("Attr change %s %s=%s" % (self.device.address, self.name, value))
         self.__value = value
 
-    def __repr__(self): # pragma: no cover
+    def __repr__(self) -> str:  # pragma: no cover
         return f"<{self.__module__}.Attribute {self.name} at 0x{id(self):x}>"
 
 
 class Attributes(list):
     """Devices owns a attributes list. This list also have dict-like access"""
 
-    def __getitem__(self,value):
-        if isinstance(value,int):
-            return list.__getitem__(self,value)
+    def __getitem__(self, value):
+        if isinstance(value, int):
+            return list.__getitem__(self, value)
         for k in self:
-            if (value == k.name):
+            if value == k.name:
                 return k.value
         raise KeyError(value)
 
-    def __setitem__(self,name,value):
-        if isinstance(name,int):
-            return list.__setitem__(self,name,value)
+    def __setitem__(self, name, value):
+        if isinstance(name, int):
+            return list.__setitem__(self, name, value)
         for k in self:
-            if (name == k.name):
+            if name == k.name:
                 k.value = value
                 return
         raise KeyError(name)
 
-class Device(object):
-
-    __slots__ = ['__dev_type','__address','group_id',
-                'vendor_id','product_id','hw_id',
-                '__version','__url','schema','info',
-                'unsupported_attributes','unsupported_methods','unsupported_notifications',
-                'alive_period','next_alive',
-                '__attributes','methods','engine']
 
-    def __init__(self,dev_type,addr=None,engine=None):
+class Device(object):
+    __slots__ = [
+        '__dev_type',
+        '__address',
+        'group_id',
+        'vendor_id',
+        'product_id',
+        'hw_id',
+        '__version',
+        '__url',
+        'schema',
+        'info',
+        'unsupported_attributes',
+        'unsupported_methods',
+        'unsupported_notifications',
+        'alive_period',
+        'next_alive',
+        '__attributes',
+        'methods',
+        'engine',
+    ]
+
+    def __init__(
+        self,
+        dev_type: str,
+        addr: Optional[bindings.UUID] = None,
+        engine: Union['AsyncEngine', 'Engine', 'EngineMixin', None] = None,
+    ):
         # xAAL internal attributes for a device
-        self.dev_type = dev_type        # xaal dev_type
-        self.address = addr             # xaal addr
-        self.group_id = None            # group devices
-        self.vendor_id = None           # vendor ID ie : ACME
-        self.product_id = None          # product ID
-        self.hw_id = None               # hardware info
-        self.__version = None           # product release
-        self.__url = None               # product URL
-        self.schema = None              # schema URL
-        self.info = None                # additionnal info
+        self.dev_type = dev_type  # xaal dev_type
+        self.address = addr  # xaal addr
+        self.group_id: Optional[bindings.UUID] = None  # group devices
+        self.vendor_id: Optional[str] = None  # vendor ID ie : ACME
+        self.product_id: Optional[str] = None  # product ID
+        self.hw_id: Optional[str] = None  # hardware info
+        self.version = None  # product release
+        self.url = None  # product URL
+        self.schema: Optional[str] = None  # schema URL
+        self.info: Optional[str] = None  # additionnal info
 
         # Unsupported stuffs
         self.unsupported_attributes = []
         self.unsupported_methods = []
         self.unsupported_notifications = []
         # Alive management
-        self.alive_period = config.alive_timer # time in sec between two alive
+        self.alive_period = config.alive_timer  # time in sec between two alive
         self.next_alive = 0
         # Default attributes & methods
         self.__attributes = Attributes()
-        self.methods = {'get_attributes' : self._get_attributes,
-                        'get_description': self._get_description }
+        self.methods: dict[str, MethodT] = {
+            'get_attributes': self._get_attributes,
+            'get_description': self._get_description,
+        }
         self.engine = engine
 
     @property
-    def dev_type(self):
+    def dev_type(self) -> str:
         return self.__dev_type
 
     @dev_type.setter
-    def dev_type(self, value):
+    def dev_type(self, value: str):
         if not tools.is_valid_dev_type(value):
             raise DeviceError(f"The dev_type {value} is not valid")
         self.__dev_type = value
 
     @property
-    def version(self):
+    def version(self) -> Optional[str]:
         return self.__version
 
     @version.setter
-    def version(self, value):
-        # version must be a string
+    def version(self, value: Any):
+        # version must be a string
         if value:
             self.__version = "%s" % value
         else:
             self.__version = None
 
     @property
-    def address(self):
+    def address(self) -> Optional[bindings.UUID]:
         return self.__address
 
     @address.setter
-    def address(self, value):
-        if value == None:
+    def address(self, value: Optional[bindings.UUID]):
+        if value is None:
             self.__address = None
             return
         if not tools.is_valid_address(value):
@@ -146,61 +175,65 @@ class Device(object):
         self.__address = value
 
     @property
-    def url(self):
+    def url(self) -> Optional[bindings.URL]:
         return self.__url
 
     @url.setter
-    def url(self,value):
-        if value == None:
+    def url(self, value: Optional[str]):
+        if value is None:
             self.__url = None
         else:
             self.__url = bindings.URL(value)
 
     # attributes
-    def new_attribute(self,name,default=None):
-        attr = Attribute(name,self,default)
+    def new_attribute(self, name: str, default: Any = None):
+        attr = Attribute(name, self, default)
         self.add_attribute(attr)
         return attr
 
-    def add_attribute(self, attr):
+    def add_attribute(self, attr: Attribute):
         if attr:
             self.__attributes.append(attr)
             attr.device = self
 
-    def del_attribute(self,attr):
+    def del_attribute(self, attr: Attribute):
         if attr:
             attr.device = None
             self.__attributes.remove(attr)
 
-    def get_attribute(self,name):
+    def get_attribute(self, name: str) -> Optional[Attribute]:
         for attr in self.__attributes:
             if attr.name == name:
                 return attr
         return None
 
     @property
-    def attributes(self):
+    def attributes(self) -> Attributes:
         return self.__attributes
 
     @attributes.setter
-    def attributes(self,values):
-        if isinstance(values,Attributes):
+    def attributes(self, values: Attributes):
+        if isinstance(values, Attributes):
             self.__attributes = values
         else:
             raise DeviceError("Invalid attributes list, use class Attributes)")
 
-    def add_method(self,name,func):
-        self.methods.update({name:func})
+    def add_method(self, name: str, func: MethodT):
+        self.methods.update({name: func})
+
+    def del_method(self, name: str):
+        if name in self.methods:
+            del self.methods[name]
 
-    def get_methods(self):
+    def get_methods(self) -> dict[str, MethodT]:
         return self.methods
 
     def update_alive(self):
-        """ update the alive timimg"""
+        """update the alive timimg"""
         self.next_alive = time.time() + self.alive_period
 
-    def get_timeout(self):
-        """ return Alive timeout used for isAlive msg"""
+    def get_timeout(self) -> int:
+        """return Alive timeout used for isAlive msg"""
         return 2 * self.alive_period
 
     #####################################################
@@ -210,46 +243,56 @@ class Device(object):
         print("= Device: %s" % self)
         # info & description
         r = []
-        r.append(['dev_type',self.dev_type])
-        r.append(['address',self.address])
-        for k,v in self._get_description().items():
-            r.append([k,v])
-        print(tabulate(r,tablefmt="fancy_grid"))
+        r.append(['dev_type', self.dev_type])
+        r.append(['address', self.address])
+        for k, v in self._get_description().items():
+            r.append([k, v])
+        print(tabulate(r, tablefmt='fancy_grid'))
 
         # attributes
         if len(self._get_attributes()) > 0:
             r = []
-            for k,v in self._get_attributes().items():
-                r.append([k,str(v)])
-            print(tabulate(r,tablefmt="fancy_grid"))
+            for k, v in self._get_attributes().items():
+                r.append([k, str(v)])
+            print(tabulate(r, tablefmt='fancy_grid'))
 
         # methods
         if len(self.methods) > 0:
             r = []
-            for k,v in self.methods.items():
-                r.append([k,v.__name__])
-            print(tabulate(r,tablefmt="fancy_grid"))
-
+            for k, v in self.methods.items():
+                r.append([k, v.__name__])
+            print(tabulate(r, tablefmt='fancy_grid'))
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<xaal.Device {id(self):x} {self.address} {self.dev_type}>"
 
     #####################################################
     # default public methods
     #####################################################
-    def _get_description(self):
+    def _get_description(self) -> dict:
         result = {}
-        if self.vendor_id:  result['vendor_id']  = self.vendor_id
-        if self.product_id: result['product_id'] = self.product_id
-        if self.version:    result['version']    = self.version
-        if self.url:        result['url']        = self.url
-        if self.schema:     result['schema']     = self.schema
-        if self.info:       result['info']       = self.info
-        if self.hw_id:      result['hw_id']      = self.hw_id
-        if self.group_id:   result['group_id']   = self.group_id
-        if self.unsupported_methods:       result['unsupported_methods']       = self.unsupported_methods
-        if self.unsupported_notifications: result['unsupported_notifications'] = self.unsupported_notifications
-        if self.unsupported_attributes:    result['unsupported_attributes']    = self.unsupported_attributes
+        if self.vendor_id:
+            result['vendor_id'] = self.vendor_id
+        if self.product_id:
+            result['product_id'] = self.product_id
+        if self.version:
+            result['version'] = self.version
+        if self.url:
+            result['url'] = self.url
+        if self.schema:
+            result['schema'] = self.schema
+        if self.info:
+            result['info'] = self.info
+        if self.hw_id:
+            result['hw_id'] = self.hw_id
+        if self.group_id:
+            result['group_id'] = self.group_id
+        if self.unsupported_methods:
+            result['unsupported_methods'] = self.unsupported_methods
+        if self.unsupported_notifications:
+            result['unsupported_notifications'] = self.unsupported_notifications
+        if self.unsupported_attributes:
+            result['unsupported_attributes'] = self.unsupported_attributes
         return result
 
     def _get_attributes(self, _attributes=None):
@@ -279,7 +322,7 @@ class Device(object):
                 result.update({attr.name: attr.value})
         return result
 
-    def send_notification(self,notification,body={}):
-        """ queue an notification, this is just a method helper """
+    def send_notification(self, notification: str, body: dict = {}):
+        """queue an notification, this is just a method helper"""
         if self.engine:
-            self.engine.send_notification(self,notification,body)
+            self.engine.send_notification(self, notification, body)

xaal/lib/engine.py

@@ -18,33 +18,44 @@
 #  along with xAAL. If not, see <http://www.gnu.org/licenses/>.
 #
 
-from . import core
-from .network  import NetworkConnector
-from .exceptions  import *
-from . import config
-
-import time
 import collections
+import logging
+import time
+import typing
 from enum import Enum
+from typing import Optional
+
+
+
+from .config import config
+from . import core
+from .exceptions import CallbackError, MessageParserError, XAALError
+from .network import NetworkConnector
+
+if typing.TYPE_CHECKING:
+    from .devices import Device
+    from .messages import Message
+
 
-import logging
 logger = logging.getLogger(__name__)
 
-class EngineState(Enum):
-    started  = 1
-    running  = 2
-    halted   = 3
 
-class Engine(core.EngineMixin):
+class EngineState(Enum):
+    started = 1
+    running = 2
+    halted = 3
 
-    __slots__ = ['__last_timer','__txFifo','state','network']
 
-    def __init__(self,address=config.address,port=config.port,hops=config.hops,key=config.key):
-        core.EngineMixin.__init__(self,address,port,hops,key)
+class Engine(core.EngineMixin):
+    __slots__ = ['__last_timer', '__txFifo', 'state', 'network']
 
-        self.__last_timer = 0                    # last timer check
-        self.__txFifo = collections.deque()      # tx msg fifo
+    def __init__(
+        self, address: str = config.address, port: int = config.port, hops: int = config.hops, key: bytes = config.key
+    ):
+        core.EngineMixin.__init__(self, address, port, hops, key)
 
+        self.__last_timer = 0  # last timer check
+        self.__txFifo = collections.deque()  # tx msg fifo
         # message receive workflow
         self.subscribe(self.handle_request)
         # ready to go
@@ -56,16 +67,16 @@ class Engine(core.EngineMixin):
     # xAAL messages Tx handling
     #####################################################
     # Fifo for msg to send
-    def queue_msg(self, msg):
+    def queue_msg(self, msg: bytes):
         """queue an encoded / cyphered message"""
         self.__txFifo.append(msg)
 
-    def send_msg(self, msg):
+    def send_msg(self, msg: bytes):
         """Send an encoded message to the bus, use queue_msg instead"""
         self.network.send(msg)
 
     def process_tx_msg(self):
-        """ Process (send) message in tx queue called from the loop()"""
+        """Process (send) message in tx queue called from the loop()"""
         cnt = 0
         while self.__txFifo:
             temp = self.__txFifo.popleft()
@@ -79,13 +90,13 @@ class Engine(core.EngineMixin):
     #####################################################
     # xAAL messages subscribers
     #####################################################
-    def receive_msg(self):
+    def receive_msg(self) -> Optional['Message']:
         """return new received message or None"""
         result = None
         data = self.network.get_data()
         if data:
             try:
-                msg = self.msg_factory.decode_msg(data,self.msg_filter)
+                msg = self.msg_factory.decode_msg(data, self.msg_filter)
             except MessageParserError as e:
                 logger.warning(e)
                 msg = None
@@ -99,35 +110,37 @@ class Engine(core.EngineMixin):
             for func in self.subscribers:
                 func(msg)
             self.process_attributes_change()
-            
-    def handle_request(self, msg):
+
+    def handle_request(self, msg: 'Message'):
         """
         Filter msg for devices according default xAAL API then process the
         request for each targets identied in the engine
         """
         if not msg.is_request():
-            return 
-        
+            return
+
         targets = core.filter_msg_for_devices(msg, self.devices)
         for target in targets:
-            if msg.action == 'is_alive':
+            if msg.is_request_isalive():
                 self.send_alive(target)
             else:
                 self.handle_action_request(msg, target)
 
-    def handle_action_request(self, msg, target):
+    def handle_action_request(self, msg: 'Message', target: 'Device'):
         """
         Run method (xAAL exposed method) on device:
-            - None is returned if device method do not return anything
             - result is returned if device method gives a response
             - Errors are raised if an error occured:
                 * Internal error
                 * error returned on the xAAL bus
         """
+        if msg.action is None:
+            return # should not happen, but pyright need this check
+
         try:
             result = run_action(msg, target)
-            if result != None:
-                self.send_reply(dev=target,targets=[msg.source],action=msg.action,body=result)
+            if result:
+                self.send_reply(dev=target, targets=[msg.source], action=msg.action, body=result)
         except CallbackError as e:
             self.send_error(target, e.code, e.description)
         except XAALError as e:
@@ -139,12 +152,13 @@ class Engine(core.EngineMixin):
     def process_timers(self):
         """Process all timers to find out which ones should be run"""
         expire_list = []
-        
-        if len(self.timers)!=0 :
+
+        if len(self.timers) != 0:
             now = time.time()
             # little hack to avoid to check timer to often.
             # w/ this enable timer precision is bad, but far enougth
-            if (now - self.__last_timer) < 0.4: return
+            if (now - self.__last_timer) < 0.4:
+                return
 
             for t in self.timers:
                 if t.deadline < now:
@@ -153,14 +167,14 @@ class Engine(core.EngineMixin):
                     except CallbackError as e:
                         logger.error(e.description)
                     if t.counter != -1:
-                        t.counter-= 1
+                        t.counter -= 1
                         if t.counter == 0:
                             expire_list.append(t)
                     t.deadline = now + t.period
             # delete expired timers
             for t in expire_list:
                 self.remove_timer(t)
-                    
+
             self.__last_timer = now
 
     #####################################################
@@ -187,7 +201,7 @@ class Engine(core.EngineMixin):
 
     def start(self):
         """Start the core engine: send queue alive msg"""
-        if self.state in [EngineState.started,EngineState.running]:
+        if self.state in [EngineState.started, EngineState.running]:
             return
         self.network.connect()
         for dev in self.devices:
@@ -206,13 +220,14 @@ class Engine(core.EngineMixin):
         while self.state == EngineState.running:
             self.loop()
 
-    def is_running(self):
+    def is_running(self) -> bool:
         if self.state == EngineState.running:
             return True
         return False
 
-def run_action(msg,device):
-    """ 
+
+def run_action(msg: 'Message', device: 'Device') -> Optional[dict]:
+    """
     Extract an action & launch it
     Return:
         - action result
@@ -220,12 +235,15 @@ def run_action(msg,device):
 
     Note: If an exception raised, it's logged, and raise an XAALError.
     """
-    method,params = core.search_action(msg,device)
+    method, params = core.search_action(msg, device)
     result = None
     try:
         result = method(**params)
     except Exception as e:
         logger.error(e)
-        raise XAALError("Error in method:%s params:%s" % (msg.action,params))
+        raise XAALError("Error in method:%s params:%s" % (msg.action, params))
+    # Here result should be None or a dict, and we need to enforce that. This will cause issue
+    # in send_reply otherwise.
+    if result is not None and not isinstance(result, dict):
+        raise XAALError("Method %s should return a dict or None" % msg.action)
     return result
-

xaal/lib/exceptions.py

@@ -1,20 +1,36 @@
-
 # devices.py
-class DeviceError(Exception):pass
+class DeviceError(Exception):
+    pass
 
 # core.py
-class EngineError(Exception):pass
-class XAALError(Exception):pass
+class EngineError(Exception):
+    pass
+
+class XAALError(Exception):
+    pass
+
 class CallbackError(Exception):
     def __init__(self, code, desc):
         self.code = code
         self.description = desc
 
 # messages.py
-class MessageParserError(Exception):pass
-class MessageError(Exception):pass
+class MessageParserError(Exception):
+    pass
+
+class MessageError(Exception):
+    pass
 
 # binding.py
-class UUIDError(Exception):pass
+class UUIDError(Exception):
+    pass
 
-__all__ = ["DeviceError","EngineError","XAALError","CallbackError","MessageParserError","MessageError","UUIDError"]
+__all__ = [
+    'DeviceError',
+    'EngineError',
+    'XAALError',
+    'CallbackError',
+    'MessageParserError',
+    'MessageError',
+    'UUIDError',
+]