xaal.lib 0.7.2__tar.gz

xaal_lib-0.7.2/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.1
+Name: xaal.lib
+Version: 0.7.2
+Summary: xaal.lib is the official Python stack of xAAL protocol dedicated to home automation systems
+Author-email: Jerome Kerdreux <Jerome.Kerdreux@imt-atlantique.fr>
+License: GPL License
+Keywords: xaal,home-automation
+Classifier: Programming Language :: Python
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Description-Content-Type: text/x-rst
+Requires-Dist: cbor2==5.4.2
+Requires-Dist: pysodium
+Requires-Dist: configobj
+Requires-Dist: coloredlogs
+Requires-Dist: decorator
+Requires-Dist: tabulate
+Requires-Dist: aioconsole
+
+
+xaal.lib
+========
+**xaal.lib** is the official Python stack to develop home-automation devices and gateways
+with the xAAL protocol. For a full description of the protocol check out 
+http://recherche.imt-atlantique.fr/xaal/
+
+
+Dependencies
+~~~~~~~~~~~~
+xaal.lib depends on :
+ * cbor2
+ * pysodium
+ * configobj
+ * coloredlogs
+ * decorator
+ * tabulate
+ * aioconsole
+
+
+Install
+~~~~~~~
+Please refer to the official `full documentation to install the lib in a virtualenv 
+<https://redmine.telecom-bretagne.eu/svn/xaal/code/Python/branches/0.7/README.html>`_
+
+
+Usage
+~~~~~
+The main goal of xaal.lib is to provide an API to easily develop devices & gateways.
+**xaal.lib.Engine send / receive / parse to|from xAAL Bus**.
+
+
+To receive / parse / display incoming xAAL messages, you can simply try something like
+this:
+
+.. code-block:: python
+   
+   from xaal.lib import Engine
+
+   def display(msg):
+       print(msg)
+
+   eng = Engine()
+   eng.subscribe(display)
+   eng.run()
+   
+The Engine will call the display function every time it receive a xAAL message.
+
+Let's take a look at a simple lamp device : 
+
+.. code-block:: python
+   
+   from xaal.lib import Device,Engine,tools
+   
+   # create and configure the lamp device, with a random address
+   dev = Device("lamp.basic", tools.get_random_uuid()) 
+   dev.product_id = 'Dummy Lamp'
+   dev.url  = 'http://www.acme.org'
+   dev.info = 'My fake lamp'
+
+   # add an xAAL attribute 'light'
+   light = dev.new_attribute('light')
+   
+   # declare two device methods ON & OFF
+   def on():
+       light.value = True
+
+   def off():
+       light.value = False
+       
+   dev.add_method('turn_on',on)
+   dev.add_method('turn_off',off)
+
+   # last step, create an engine and register the lamp
+   eng = Engine()
+   eng.add_device(dev)
+   eng.run()
+   
+   
+FAQ
+~~~
+The core engine run forever so how can I use it in webserver, GUI or to develop device
+with IO. The whole API is absolutely not thread safe, so **don't use threads** unless you
+exactly know what's going on. Anyways, you have several options to fix this issue:
+
+* You can use you own loop and periodically call *eng.loop()*
+  for example, you can do something like this:
+  
+  .. code:: python
+     
+     while 1:
+         do_some_stuff()
+         eng.loop()
+
+* You can use a engine timer, to perform some stuff.
+  
+  .. code:: python
+     
+     def read_io():
+         pass
+
+     # call the read_io function every 10 sec
+     eng.add_timer(read_io,10)
+     eng.run()
+
+* Use the **AsyncEngine**. Python version > 3.8 provides async programming with **asyncio** package.
+  *AsyncEngine* use the same API as *Engine*, but it is a **asynchronous** engine. You can use
+  *coroutines* in device methods, timers functions and callbacks. It provides additionals features
+  like the *on_start* and *on_stop* callbacks.
+
+* Use an alternate coroutine lib, you can use **gevent** or **greenlet** for example. Look at 
+  apps/rest for a simple greenlet example. 
+  

xaal_lib-0.7.2/README.rst

@@ -0,0 +1,113 @@
+
+xaal.lib
+========
+**xaal.lib** is the official Python stack to develop home-automation devices and gateways
+with the xAAL protocol. For a full description of the protocol check out 
+http://recherche.imt-atlantique.fr/xaal/
+
+
+Dependencies
+~~~~~~~~~~~~
+xaal.lib depends on :
+ * cbor2
+ * pysodium
+ * configobj
+ * coloredlogs
+ * decorator
+ * tabulate
+ * aioconsole
+
+
+Install
+~~~~~~~
+Please refer to the official `full documentation to install the lib in a virtualenv 
+<https://redmine.telecom-bretagne.eu/svn/xaal/code/Python/branches/0.7/README.html>`_
+
+
+Usage
+~~~~~
+The main goal of xaal.lib is to provide an API to easily develop devices & gateways.
+**xaal.lib.Engine send / receive / parse to|from xAAL Bus**.
+
+
+To receive / parse / display incoming xAAL messages, you can simply try something like
+this:
+
+.. code-block:: python
+   
+   from xaal.lib import Engine
+
+   def display(msg):
+       print(msg)
+
+   eng = Engine()
+   eng.subscribe(display)
+   eng.run()
+   
+The Engine will call the display function every time it receive a xAAL message.
+
+Let's take a look at a simple lamp device : 
+
+.. code-block:: python
+   
+   from xaal.lib import Device,Engine,tools
+   
+   # create and configure the lamp device, with a random address
+   dev = Device("lamp.basic", tools.get_random_uuid()) 
+   dev.product_id = 'Dummy Lamp'
+   dev.url  = 'http://www.acme.org'
+   dev.info = 'My fake lamp'
+
+   # add an xAAL attribute 'light'
+   light = dev.new_attribute('light')
+   
+   # declare two device methods ON & OFF
+   def on():
+       light.value = True
+
+   def off():
+       light.value = False
+       
+   dev.add_method('turn_on',on)
+   dev.add_method('turn_off',off)
+
+   # last step, create an engine and register the lamp
+   eng = Engine()
+   eng.add_device(dev)
+   eng.run()
+   
+   
+FAQ
+~~~
+The core engine run forever so how can I use it in webserver, GUI or to develop device
+with IO. The whole API is absolutely not thread safe, so **don't use threads** unless you
+exactly know what's going on. Anyways, you have several options to fix this issue:
+
+* You can use you own loop and periodically call *eng.loop()*
+  for example, you can do something like this:
+  
+  .. code:: python
+     
+     while 1:
+         do_some_stuff()
+         eng.loop()
+
+* You can use a engine timer, to perform some stuff.
+  
+  .. code:: python
+     
+     def read_io():
+         pass
+
+     # call the read_io function every 10 sec
+     eng.add_timer(read_io,10)
+     eng.run()
+
+* Use the **AsyncEngine**. Python version > 3.8 provides async programming with **asyncio** package.
+  *AsyncEngine* use the same API as *Engine*, but it is a **asynchronous** engine. You can use
+  *coroutines* in device methods, timers functions and callbacks. It provides additionals features
+  like the *on_start* and *on_stop* callbacks.
+
+* Use an alternate coroutine lib, you can use **gevent** or **greenlet** for example. Look at 
+  apps/rest for a simple greenlet example. 
+  

xaal_lib-0.7.2/pyproject.toml

@@ -0,0 +1,11 @@
+[project]
+name = "xaal.lib"
+version = "0.7.2"
+description = "xaal.lib is the official Python stack of xAAL protocol dedicated to home automation systems"
+readme = "README.rst"
+authors = [ { name = "Jerome Kerdreux", email = "Jerome.Kerdreux@imt-atlantique.fr" } ]
+license = { text = "GPL License"}
+classifiers = ['Programming Language :: Python', 'Topic :: Software Development :: Libraries :: Python Modules']
+keywords = ['xaal', 'home-automation']
+dependencies = ['cbor2==5.4.2', 'pysodium', 'configobj', 'coloredlogs', 'decorator', 'tabulate', 'aioconsole']
+

xaal_lib-0.7.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xaal_lib-0.7.2/tests/test_bindings.py

@@ -0,0 +1,56 @@
+import unittest
+from xaal.lib import bindings
+
+
+class TestUUID(unittest.TestCase):
+
+
+    def test_add_sub(self):
+        uuid = bindings.UUID("12345678-1234-1234-1234-123456789012")
+        uuid += 1
+        self.assertEqual(uuid,bindings.UUID("12345678-1234-1234-1234-123456789013"))
+        uuid -= 1
+        self.assertEqual(uuid,bindings.UUID("12345678-1234-1234-1234-123456789012"))
+
+    def test_random(self):
+        uuid = bindings.UUID.random()
+        self.assertIsInstance(uuid,bindings.UUID)
+
+        uuid = bindings.UUID.random_base()
+        self.assertIsInstance(uuid,bindings.UUID)
+
+        with self.assertRaises(bindings.UUIDError):
+            uuid = bindings.UUID.random_base(0)
+
+    def test_get_set(self):
+        uuid1 = bindings.UUID("12345678-1234-1234-1234-123456789012")
+        data = uuid1.get()
+        uuid2 = bindings.UUID.random()
+        uuid2.set(data)
+        self.assertEqual(uuid1,uuid2)
+
+    def test_str(self):
+        uuid = bindings.UUID("12345678-1234-1234-1234-123456789012")
+        self.assertEqual(str(uuid),"12345678-1234-1234-1234-123456789012")
+        self.assertEqual(uuid.str,"12345678-1234-1234-1234-123456789012")
+
+    def test_bytes(self):
+        uuid = bindings.UUID("12345678-1234-1234-1234-123456789012")
+        self.assertEqual(uuid.bytes,b'\x124Vx\x124\x124\x124\x124Vx\x90\x12')
+
+
+class TestURL(unittest.TestCase):
+
+    def test_url(self):
+        url = bindings.URL("http://bar.com")
+        self.assertEqual(str(url), "http://bar.com")
+        url.set("http://foo.com")
+        print(url)
+        self.assertEqual(str(url), "http://foo.com")
+        self.assertEqual(url.str, "http://foo.com")
+        self.assertEqual(url.get(), "http://foo.com")
+        self.assertEqual(url.bytes, "http://foo.com")
+
+
+if __name__ == '__main__':
+    unittest.main()

xaal_lib-0.7.2/tests/test_cbor.py

@@ -0,0 +1,62 @@
+import unittest
+from xaal.lib import cbor
+from xaal.lib import bindings
+import binascii
+
+
+class TestCbor(unittest.TestCase):
+    def test_encode(self):
+        value = cbor.dumps(42)
+        self.assertEqual(value, b"\x18*")  # 0x18 0x2a
+
+    def test_decode(self):
+        value = cbor.loads(b"\x18*")
+        self.assertEqual(value, 42)
+
+    def test_list(self):
+        value = []
+        value.append(7)
+        value.append(1234567890)
+        data = cbor.dumps(value)
+        print(data)
+        self.assertEqual(data, binascii.unhexlify(b"82071a499602d2"))
+
+    def test_uuid(self):
+        uuid = bindings.UUID.random()
+        cbor_value = cbor.dumps(uuid)
+        value = cbor.loads(cbor_value)
+        self.assertEqual(value, uuid)
+        self.assertEqual(type(value), bindings.UUID)
+
+    def test_url(self):
+        url = bindings.URL("http://www.example.com")
+        cbor_value = cbor.dumps(url)
+        value = cbor.loads(cbor_value)
+        self.assertEqual(value, url)
+        self.assertEqual(type(value), bindings.URL)
+
+    def test_cleanup(self):
+        data = [
+            7,
+            "hello",
+            bindings.UUID("12345678-1234-1234-1234-123456789012"),
+            bindings.URL("http://www.example.com"),
+            {"hello": "world"},
+        ]
+        cbor_value = cbor.dumps(data)
+        value = cbor.loads(cbor_value)
+        cbor.cleanup(value)
+        self.assertEqual(
+            value,
+            [
+                7,
+                "hello",
+                "12345678-1234-1234-1234-123456789012",
+                "http://www.example.com",
+                {"hello": "world"},
+            ],
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

xaal_lib-0.7.2/tests/test_device.py

@@ -0,0 +1,195 @@
+import unittest
+from xaal.lib import tools
+from xaal.lib import Device,DeviceError,Attribute,Engine
+from xaal.lib.devices import Attributes
+
+
+def new_dev() -> Device:
+    addr = tools.get_random_uuid()
+    dev = Device("light.basic",addr=addr)
+    return dev
+
+class TestAttribute(unittest.TestCase):
+
+    def test_default(self):
+        attr = Attribute("foo",dev=new_dev(),default=1)
+        self.assertEqual(attr.value,1)
+        attr.value = 12
+        self.assertEqual(attr.value,12)
+
+    def test_with_engine(self):
+        dev = new_dev()
+        dev.engine = Engine()
+        attr = Attribute("foo",dev=dev,default=1,)
+        attr.value = 12
+        self.assertEqual(attr.value,12)
+
+class TestAttributes(unittest.TestCase):
+
+    def test_default(self):
+        dev = new_dev()
+        attr = Attribute("foo",dev=dev,default=1)
+        attrs = Attributes()
+        attrs.append(attr)
+        self.assertEqual(attrs[0].value,1)
+        self.assertEqual(attrs["foo"],1)
+
+        with self.assertRaises(KeyError):
+            attrs["bar"]
+
+        attrs[0] = Attribute("bar",dev=dev,default=2)
+        self.assertEqual(attrs[0].value,2)
+
+        attrs["bar"] = 12
+        self.assertEqual(attrs["bar"],12)
+
+        with self.assertRaises(KeyError):
+            attrs["nop"]=12
+
+
+class TestDevice(unittest.TestCase):
+
+    def test_init(self):
+        dev_type="light.basic"
+        addr = tools.get_random_uuid()
+        dev = Device(dev_type=dev_type,addr=addr)
+        self.assertEqual(dev.dev_type, dev_type)
+        self.assertEqual(dev.address, addr)
+
+    def test_address(self):
+        dev = new_dev()
+        # address
+        addr = tools.get_random_uuid()
+        dev.address = addr
+        self.assertEqual(dev.address, addr)
+        # none address
+        dev.address = None
+        self.assertEqual(dev.address, None)
+        # invalid address
+        with self.assertRaises(DeviceError):
+            dev.address = "foo"
+
+    def test_dev_type(self):
+        dev = new_dev()
+        dev.dev_type = "foo.basic"
+        self.assertEqual(dev.dev_type, "foo.basic")
+        with self.assertRaises(DeviceError):
+            dev.dev_type = "foo"
+
+    def test_version(self):
+        dev = new_dev()
+        # version 
+        dev.version = 12
+        self.assertEqual(dev.version, '12')
+        dev.version = None
+        self.assertEqual(dev.version, None)
+
+    def test_url(self):
+        dev = new_dev()
+        dev.url = "http://foo.bar"
+        self.assertEqual(dev.url, "http://foo.bar")
+        dev.url = None
+        self.assertEqual(dev.url, None)
+
+    def test_attributes(self):
+        dev = new_dev()
+        attr = Attribute("foo",dev=dev,default=1)
+        # add
+        dev.add_attribute(attr)
+        self.assertEqual(len(dev.attributes),1)
+        self.assertEqual(dev.attributes[0],attr)
+        # del
+        dev.del_attribute(attr)
+        self.assertEqual(len(dev.attributes),0)
+        # new
+        dev.new_attribute("foo",default=2)
+        self.assertEqual(len(dev.attributes),1)
+        self.assertEqual(dev.attributes[0].value,2)
+        # get
+        self.assertEqual(dev.get_attribute("foo").value,2)
+        self.assertEqual(dev.get_attribute("bar"),None)
+        
+        # set
+        attr = Attribute("bar",dev=dev,default=3)
+        dev.attributes =Attributes([attr,])
+        self.assertEqual(len(dev.attributes),1)
+        self.assertEqual(dev.attributes[0].value,3)
+        # only accepts Attributes not list 
+        with self.assertRaises(DeviceError):
+            dev.attributes = [attr,]
+
+    def test_get_attributes(self):
+        dev = new_dev()
+        dev.new_attribute("foo",default=1)
+        # _get_attributes
+        self.assertEqual(dev._get_attributes()["foo"],1)
+        data = dev._get_attributes(["foo","bar"])
+        self.assertEqual(len(data),1)
+        self.assertEqual(data["foo"],1)
+
+    def test_get_description(self):
+        dev = new_dev()
+
+        dev.vendor_id = 0x1234
+        dev.product_id = 0x1234
+        dev.version = '2f'
+        dev.url = "http://foo.bar"
+        dev.schema = "http://schemas.foo.bar/schema.json"
+        dev.info = "FooBar"
+        dev.hw_id = 0xf12
+        group = tools.get_random_uuid()
+        dev.group_id = group
+
+        dev.unsupported_methods = ["foo_func"]
+        dev.unsupported_attributes = ["foo_attr"]
+        dev.unsupported_notifications = ["foo_notif"]
+
+        data = dev._get_description()
+        self.assertEqual(data["vendor_id"], 0x1234)
+        self.assertEqual(data["product_id"], 0x1234)
+        self.assertEqual(data["version"], '2f')
+        self.assertEqual(data["url"], "http://foo.bar")
+        self.assertEqual(data["schema"], "http://schemas.foo.bar/schema.json")
+        self.assertEqual(data["info"], "FooBar")
+        self.assertEqual(data["hw_id"],0xf12)
+        self.assertEqual(data["group_id"],group)
+
+        self.assertEqual(data["unsupported_methods"],["foo_func"])
+        self.assertEqual(data["unsupported_notifications"],["foo_notif"])
+        self.assertEqual(data["unsupported_attributes"],["foo_attr"])
+
+    def test_methods(self):
+        dev = new_dev()
+        # device has two methods by default
+        self.assertEqual(len(dev.methods),2)
+        self.assertEqual(len(dev.get_methods()),2)
+        def func():pass
+        dev.add_method("foo",func)
+        self.assertEqual(dev.methods["foo"],func)
+
+    def test_dump(self):
+        dev = new_dev()
+        dev.info = 'FooBar'
+        dev.new_attribute("foo",default=1)
+        dev.dump()
+
+    def test_alive(self):
+        import time
+        now = time.time()
+        dev = new_dev()
+        dev.alive_period = 2 
+        dev.update_alive()
+        self.assertTrue(dev.next_alive > now)
+        self.assertTrue(dev.next_alive < now+3)
+        self.assertEqual(dev.get_timeout(),4)
+
+    def test_send_notification(self):
+        # not really a test here, just to check if the method is called
+        # check engine unittest for futher tests
+        dev = new_dev()
+        dev.engine = Engine()
+        dev.send_notification("foo")
+        
+
+if __name__ == '__main__':
+    unittest.main()

xaal_lib-0.7.2/tests/test_engine.py

@@ -0,0 +1,97 @@
+import time
+import unittest
+from xaal.lib import Engine, Device, MessageType, CallbackError
+from xaal.lib import engine, tools
+from xaal.lib.messages import Message
+
+TEST_PORT = 6666
+
+
+def new_engine():
+    engine = Engine(port=TEST_PORT)
+    return engine
+
+class TestEngine(unittest.TestCase):
+
+    def test_devices(self):
+        dev = Device("test.basic", tools.get_random_uuid())
+        eng = Engine(port=TEST_PORT)
+        eng.add_device(dev)
+        self.assertEqual(eng.devices,[dev,])
+        eng.remove_device(dev)
+        self.assertEqual(eng.devices,[])
+        eng.add_devices([dev,])
+        self.assertEqual(eng.devices,[dev,])
+
+    def test_start_stop(self):
+        eng = Engine(port=TEST_PORT)
+        dev = Device("test.basic", tools.get_random_uuid())
+        eng.add_device(dev)
+        eng.start()
+        eng.start()  # second start
+        self.assertEqual(engine.EngineState.started, eng.state)
+        eng.loop()
+        eng.stop()
+        self.assertEqual(engine.EngineState.halted, eng.state)
+
+    def test_timer(self):
+        eng = Engine(port=TEST_PORT)
+        t0 = time.time()
+        def _exit():
+            eng.shutdown()
+        eng.add_timer(_exit, 1, 1)
+        eng.run()
+        t = time.time() - t0
+        self.assertTrue(t > 1)
+        self.assertTrue(t < 2)
+
+    def test_timer_error(self):
+        eng = Engine(port=TEST_PORT)
+        eng.start()
+        def _error():
+            raise CallbackError(500,"test error")
+        eng.add_timer(_error,0,1)
+        eng.loop()  
+        eng.stop()
+        self.assertEqual(engine.EngineState.halted, eng.state)
+
+    def test_run_action(self):
+        target = Device("test.basic", tools.get_random_uuid())
+
+        def action_1():
+            return "action_1"
+
+        def action_2(_value=None):
+            return "action_%s" % _value
+
+        def action_3():
+            raise Exception
+
+        target.add_method("action_1", action_1)
+        target.add_method("action_2", action_2)
+        target.add_method("action_3", action_3)
+
+        msg = Message()
+        msg.msg_type = MessageType.REQUEST
+        msg.targets = [target.address]
+        # simple test method
+        msg.action = "action_1"
+        result = engine.run_action(msg, target)
+        self.assertEqual(result, "action_1")
+        # test with value
+        msg.action = "action_2"
+        msg.body = {"value": "2"}
+        result = engine.run_action(msg, target)
+        self.assertEqual(result, "action_2")
+        # Exception in method
+        msg.action = "action_3"
+        with self.assertRaises(engine.XAALError):
+            result = engine.run_action(msg, target)
+        # unknown method
+        msg.action = "missing"
+        with self.assertRaises(engine.XAALError):
+            result = engine.run_action(msg, target)
+
+
+if __name__ == "__main__":
+    unittest.main()