enapter 0.9.2__py3-none-any.whl → 0.10.0__py3-none-any.whl

enapter/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.9.2"
+__version__ = "0.10.0"
 
 from . import async_, log, mdns, mqtt, types, vucm
 

enapter/log/json_formatter.py

@@ -6,7 +6,7 @@ import json_log_formatter
 class JSONFormatter(json_log_formatter.JSONFormatter):
     def json_record(self, message, extra, record):
         json_record = {
-            "time": datetime.datetime.utcnow().isoformat(),
+            "time": datetime.datetime.now(datetime.UTC).isoformat(),
             "level": record.levelname[:4],
             "name": record.name,
             **extra,

enapter/types.py

@@ -1,3 +1,3 @@
-from typing import Any, Dict
+from typing import Dict, List, Union
 
-JSON = Dict[str, Any]
+JSON = Union[str, int, float, None, bool, List["JSON"], Dict[str, "JSON"]]

enapter/vucm/__init__.py

@@ -1,12 +1,14 @@
 from .app import App, run
 from .config import Config
-from .device import Device
+from .device import Device, device_command, device_task
 from .ucm import UCM
 
 __all__ = [
     "App",
     "Config",
     "Device",
+    "device_command",
+    "device_task",
     "UCM",
     "run",
 ]

enapter/vucm/app.py

@@ -6,10 +6,10 @@ from .config import Config
 from .ucm import UCM
 
 
-async def run(device_factory):
+async def run(device_factory, config_prefix=None):
     enapter.log.configure(level=enapter.log.LEVEL or "info")
 
-    config = Config.from_env()
+    config = Config.from_env(prefix=config_prefix)
 
     async with App(config=config, device_factory=device_factory) as app:
         await app.join()

enapter/vucm/config.py

@@ -7,7 +7,9 @@ import enapter
 
 class Config:
     @classmethod
-    def from_env(cls, prefix="ENAPTER_VUCM_", env=os.environ):
+    def from_env(cls, prefix=None, env=os.environ):
+        if prefix is None:
+            prefix = "ENAPTER_VUCM_"
         try:
             blob = os.environ[prefix + "BLOB"]
         except KeyError:

enapter/vucm/device.py

@@ -2,25 +2,57 @@ import asyncio
 import concurrent
 import functools
 import traceback
-from typing import Optional, Set
+from typing import Any, Callable, Coroutine, Optional, Set
 
 import enapter
 
 from .logger import Logger
 
+DEVICE_TASK_MARK = "_enapter_vucm_device_task"
+DEVICE_COMMAND_MARK = "_enapter_vucm_device_command"
+
+DeviceTaskFunc = Callable[[Any], Coroutine]
+DeviceCommandFunc = Callable[..., Coroutine]
+
+
+def device_task(func: DeviceTaskFunc) -> DeviceTaskFunc:
+    setattr(func, DEVICE_TASK_MARK, True)
+    return func
+
+
+def device_command(func: DeviceCommandFunc) -> DeviceTaskFunc:
+    setattr(func, DEVICE_COMMAND_MARK, True)
+    return func
+
+
+def is_device_task(func: DeviceTaskFunc) -> bool:
+    return getattr(func, DEVICE_TASK_MARK, False) is True
+
+
+def is_device_command(func: DeviceCommandFunc) -> bool:
+    return getattr(func, DEVICE_COMMAND_MARK, False) is True
+
 
 class Device(enapter.async_.Routine):
     def __init__(
         self,
         channel,
         cmd_prefix="cmd_",
-        task_prefix="task_",
         thread_pool_executor=None,
     ) -> None:
         self.__channel = channel
 
-        self.__cmd_prefix = cmd_prefix
-        self.__task_prefix = task_prefix
+        self.__tasks = {}
+        for name in dir(self):
+            obj = getattr(self, name)
+            if is_device_task(obj):
+                self.__tasks[name] = obj
+
+        self.__commands = {}
+        for name in dir(self):
+            obj = getattr(self, name)
+            if is_device_command(obj):
+                self.__commands[name] = obj
 
         if thread_pool_executor is None:
             thread_pool_executor = concurrent.futures.ThreadPoolExecutor(max_workers=1)
@@ -62,11 +94,8 @@ class Device(enapter.async_.Routine):
 
         tasks = set()
 
-        for name in dir(self):
-            if name.startswith(self.__task_prefix):
-                task_func = getattr(self, name)
-                name_without_prefix = name[len(self.__task_prefix) :]
-                tasks.add(asyncio.create_task(task_func(), name=name_without_prefix))
+        for name, func in self.__tasks.items():
+            tasks.add(asyncio.create_task(func(), name=name))
 
         tasks.add(
             asyncio.create_task(
@@ -107,8 +136,8 @@ class Device(enapter.async_.Routine):
 
     async def __execute_command(self, req):
         try:
-            cmd = getattr(self, self.__cmd_prefix + req.name)
-        except AttributeError:
+            cmd = self._commands[req.name]
+        except KeyError:
             return enapter.mqtt.api.CommandState.ERROR, {"reason": "unknown command"}
 
         try:

enapter/vucm/ucm.py

@@ -2,7 +2,7 @@ import asyncio
 
 import enapter
 
-from .device import Device
+from .device import Device, device_command, device_task
 
 
 class UCM(Device):
@@ -13,20 +13,24 @@ class UCM(Device):
             )
         )
 
-    async def cmd_reboot(self):
+    @device_command
+    async def reboot(self):
         await asyncio.sleep(0)
         raise NotImplementedError
 
-    async def cmd_upload_lua_script(self, url, sha1, payload=None):
+    @device_command
+    async def upload_lua_script(self, url, sha1, payload=None):
         await asyncio.sleep(0)
         raise NotImplementedError
 
-    async def task_telemetry_publisher(self):
+    @device_task
+    async def telemetry_publisher(self) -> None:
         while True:
             await self.send_telemetry()
             await asyncio.sleep(1)
 
-    async def task_properties_publisher(self):
+    @device_task
+    async def properties_publisher(self):
         while True:
             await self.send_properties({"virtual": True, "lua_api_ver": 1})
             await asyncio.sleep(10)

{enapter-0.9.2.dist-info → enapter-0.10.0.dist-info}/METADATA

@@ -1,14 +1,21 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: enapter
-Version: 0.9.2
+Version: 0.10.0
 Summary: Enapter Python SDK
 Home-page: https://github.com/Enapter/python-sdk
 Author: Roman Novatorov
 Author-email: rnovatorov@enapter.com
 Description-Content-Type: text/markdown
-Requires-Dist: aiomqtt ==1.0.*
-Requires-Dist: dnspython ==2.6.*
-Requires-Dist: json-log-formatter ==0.5.*
+Requires-Dist: aiomqtt==1.0.*
+Requires-Dist: dnspython==2.6.*
+Requires-Dist: json-log-formatter==0.5.*
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: summary
 
 # Enapter Python SDK
 
@@ -42,12 +49,13 @@ Checkout [examples](examples).
 
 ### Device Telemetry and Properties
 
-Every method of `enapter.vucm.Device` subclass with a name that starts with
-`task_` prefix is considered a _device task_. When such a device is started,
-all of its tasks are started as well. Device tasks are started in random order
-and are being executed concurrently in the background. If a device task returns
-or raises an exception, device routine is terminated. A typical use of the task
-is to run a periodic job to send device telemetry and properties.
+Every method of `enapter.vucm.Device` subclass decorated with
+`enapter.vucm.device_task` decorator is considered a _device task_. When such a
+device is started, all of its tasks are started as well. Device tasks are
+started in random order and are being executed concurrently in the background.
+If a device task returns or raises an exception, device routine is terminated.
+A typical use of the task is to run a periodic job to send device telemetry and
+properties.
 
 In order to send telemetry and properties define two corresponding device
 tasks. It is advised (but is not obligatory) to send telemetry every **1
@@ -57,12 +65,12 @@ Examples:
 
 - [wttr-in](examples/vucm/wttr-in)
 
-### Device Commands
+### Device Command Handlers
 
-Every method of `enapter.vucm.Device` subclass with a name that starts with
-`cmd_` prefix is considered a _device command handler_. Device command handlers
-receive the same arguments as described in device Blueprint manifest and can
-optionally return a payload as `dict`.
+Every method of `enapter.vucm.Device` subclass decorated with
+`enapter.vucm.device_command` is considered a _device command handler_. Device
+command handlers receive the same arguments as described in device Blueprint
+manifest and can optionally return a payload as `enapter.types.JSON`.
 
 In order to handle device commands define corresponding device command
 handlers.

{enapter-0.9.2.dist-info → enapter-0.10.0.dist-info}/RECORD

@@ -1,10 +1,10 @@
-enapter/__init__.py,sha256=h2hySSbGrLvW5vO6yVmf7t8DPWVpflma66GhlNmUPdw,182
-enapter/types.py,sha256=2366bx_VI7bIBNnIaG5sol7G4k0PqaQ6oS74dzM4l1M,52
+enapter/__init__.py,sha256=No4wlAO2UL9UZK-GmXjX2uitUxjgply-xv38DCZb4_w,183
+enapter/types.py,sha256=J_rFCW79cloh2FF_49Oab5kaEGdZohymkCJU7vfko-8,113
 enapter/async_/__init__.py,sha256=JuiRI2bN2AgB-HLfAUoSsZpEziwFRftNNEp59Evnd0M,109
 enapter/async_/generator.py,sha256=qBhnt36Gl2166sJFnZHsREbZu8l43M4DfxybUMIv6W4,300
 enapter/async_/routine.py,sha256=A5fG4XnCEQT0Qa_JNh1N43Fv5lnLaCoGF4xt6pOAdNs,1770
 enapter/log/__init__.py,sha256=n1sWMDKJSs_ebZzjbTrVdfg-oi0V1tvliTxgIV-msJ0,600
-enapter/log/json_formatter.py,sha256=P46zEdU5-dr3mDMkUjBy7z_FSMPi61RUgEYyBEfqVNQ,705
+enapter/log/json_formatter.py,sha256=mkcWW2VmksCmRVPU7ayxbNp5-eRetznSjZlA-DUloOY,714
 enapter/mdns/__init__.py,sha256=uwsg8wJ0Lcsr9oOEW1PkEV3jVgWzgA7RG2ur_MRLtM0,55
 enapter/mdns/resolver.py,sha256=FFQuZiaKOaNtfSgI2YOaSdG-BuZwOKmYVy06Sc735Zo,1297
 enapter/mqtt/__init__.py,sha256=aKJklTmR8OEnwnQXN1MtrvJimC9EfxcTOqhhBsPcb84,126
@@ -14,12 +14,12 @@ enapter/mqtt/api/__init__.py,sha256=M1g2891bSLCnDbZOuLElEPPlN6pJk0J1w_1Fi8x5xJU,
 enapter/mqtt/api/command.py,sha256=ozhDTjRrdCWv_bzPTjVFpL8tx7nhirm3JtQaD45wTdo,1092
 enapter/mqtt/api/device_channel.py,sha256=fma_R59kxMoH6S4DwDBcSqgTsr8KNJkEov-c3poNsD0,2371
 enapter/mqtt/api/log_severity.py,sha256=ZmHXMc8d1e2ZnsXDWwl3S3noAEJjILYab_qjqk374Qw,126
-enapter/vucm/__init__.py,sha256=OhUYlVNO1RereHiZEyeJPdpEcy2QEqDBg4xBk_-A7-c,177
-enapter/vucm/app.py,sha256=NLA4z32rykoxa9I3YDYh0TbT-25fx0gBpR6oKgaJzSs,1384
-enapter/vucm/config.py,sha256=fYvHk7vDWYf0w5OGQX7f_-Y4RmrrK2U1WY3DiOBEKcg,1660
-enapter/vucm/device.py,sha256=nRV83ZYmaWwwma8mPTlxym57LYB5vZYUr4yB0tb6YzQ,3620
+enapter/vucm/__init__.py,sha256=40GAkJvpCl7oMuWDU09zpjP5rM4V-oKRbh_R1uhx4aE,247
+enapter/vucm/app.py,sha256=zHdEEUnKrVHNvVGmw7Jrv5MFkVnbg5yiiped86jxbSU,1424
+enapter/vucm/config.py,sha256=Lj-YLQvoZ9ivXVBF0oKRvdupLRJ2l55EEzoxZ4HWWRE,1713
+enapter/vucm/device.py,sha256=FiJSJNgZkWGL-866IGY8bbqS75ZZigJZYyoH7kMW7Is,4352
 enapter/vucm/logger.py,sha256=a_ZtuIinATbEtiP5avV8JGAKFKG0-RZhF6SozaF-_PU,1445
-enapter/vucm/ucm.py,sha256=zRU4hCuF04LgV65zxJqiy5EYHU_gHRmLyZFmmD26Uhw,864
+enapter/vucm/ucm.py,sha256=r1q1rSYlT7GWZ24JLmTbzkpMDUUHcvCNp9t5xHTEyzY,957
 tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/conftest.py,sha256=qEZwCEK8F6hJZ5sSHK6hUmUYKaWfY77UuNOHntfNS3c,397
 tests/fake_data_generator.py,sha256=lpVgazRRXAP07SeiTeY3Fe1LzDdM44lS50QTlwBdMYg,587
@@ -28,11 +28,11 @@ tests/integration/conftest.py,sha256=TpbUrExImSsLp77FIp1O-6wJrxgTmyxCgmmATIDEmL4
 tests/integration/test_mqtt.py,sha256=Hm165Sxysrc5ZatJjiMKITv0-78N0NbGiTI5QrJ_aSU,3891
 tests/unit/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/unit/test_async.py,sha256=KwhwKBSeSb7Qyaf50Ca2LGB7gm3m5j5wgGgWnvYY98k,4208
-tests/unit/test_log.py,sha256=DQD1OCVkYYzy-Kq-jH_xsaRDtiwIqULuTgMitjSeiuo,1876
-tests/unit/test_vucm.py,sha256=h3sY9GXxNizHyjx0lxM5yErHUI4VzzJj_O1MbIu6OGM,685
+tests/unit/test_log.py,sha256=Q-ZelqGfladBCaw-BQrwRrxbxMK1VZxgY7HBsBb1GHw,1875
+tests/unit/test_vucm.py,sha256=a3euiqV9etsfrWFDUtHCNqKU3irx-GEZMczBcmddhek,3626
 tests/unit/test_mqtt/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/unit/test_mqtt/test_api.py,sha256=ObKCHB-KDOYQLFrdzjTmLfjdWXXX0oanGKpX49P0qMI,2670
-enapter-0.9.2.dist-info/METADATA,sha256=h4HfaVY9ko8wFfK-R-ICaq98OHErV0X63bH46XZqjMU,3153
-enapter-0.9.2.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
-enapter-0.9.2.dist-info/top_level.txt,sha256=DsMzVradd7z3A0fm7zmn9oh08ijO41RtzglrnPlx54w,14
-enapter-0.9.2.dist-info/RECORD,,
+enapter-0.10.0.dist-info/METADATA,sha256=354uZuKv0_6QgPow7MPuP6VT6GNMNKYLfhSnSXNo0Fw,3335
+enapter-0.10.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+enapter-0.10.0.dist-info/top_level.txt,sha256=DsMzVradd7z3A0fm7zmn9oh08ijO41RtzglrnPlx54w,14
+enapter-0.10.0.dist-info/RECORD,,

{enapter-0.9.2.dist-info → enapter-0.10.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.42.0)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

tests/unit/test_log.py

@@ -26,11 +26,9 @@ class TestJSONFormat:
         time = record.pop("time")
         assert re.match(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+", time) is not None
 
-        assert record == {
-            "level": "INFO",
-            "name": "enapter",
-            "message": "hello",
-        }
+        assert record["level"] == "INFO"
+        assert record["name"] == "enapter"
+        assert record["message"] == "hello"
 
     def test_exc_info(self):
         buf = io.StringIO()

tests/unit/test_vucm.py

@@ -11,6 +11,101 @@ class TestDevice:
             assert await device.run_in_thread(lambda: 42) == 42
         assert device._Device__thread_pool_executor._shutdown
 
+    async def test_task_marks(self, fake):
+        class MyDevice(enapter.vucm.Device):
+            async def task_foo(self):
+                pass
+
+            @enapter.vucm.device_task
+            async def task_bar(self):
+                pass
+
+            @enapter.vucm.device_task
+            async def baz(self):
+                pass
+
+            @enapter.vucm.device_task
+            async def goo(self):
+                pass
+
+        async with MyDevice(channel=MockChannel(fake)) as device:
+            tasks = device._Device__tasks
+            assert len(tasks) == 3
+            assert "task_foo" not in tasks
+            assert "task_bar" in tasks
+            assert "baz" in tasks
+            assert "goo" in tasks
+
+    async def test_command_marks(self, fake):
+        class MyDevice(enapter.vucm.Device):
+            async def cmd_foo(self):
+                pass
+
+            async def cmd_foo2(self, a, b, c):
+                pass
+
+            @enapter.vucm.device_command
+            async def cmd_bar(self):
+                pass
+
+            @enapter.vucm.device_command
+            async def cmd_bar2(self, a, b, c):
+                pass
+
+            @enapter.vucm.device_command
+            async def baz(self):
+                pass
+
+            @enapter.vucm.device_command
+            async def baz2(self, a, b, c):
+                pass
+
+            @enapter.vucm.device_command
+            async def goo(self):
+                pass
+
+        async with MyDevice(channel=MockChannel(fake)) as device:
+            commands = device._Device__commands
+            assert len(commands) == 5
+            assert "cmd_foo" not in commands
+            assert "cmd_foo2" not in commands
+            assert "cmd_bar" in commands
+            assert "cmd_bar2" in commands
+            assert "baz" in commands
+            assert "baz2" in commands
+            assert "goo" in commands
+
+    async def test_task_and_commands_marks(self, fake):
+        class MyDevice(enapter.vucm.Device):
+            @enapter.vucm.device_task
+            async def foo_task(self):
+                pass
+
+            @enapter.vucm.device_task
+            async def bar_task(self):
+                pass
+
+            @enapter.vucm.device_command
+            async def foo_command(self):
+                pass
+
+            @enapter.vucm.device_command
+            async def bar_command(self):
+                pass
+
+        async with MyDevice(channel=MockChannel(fake)) as device:
+            tasks = device._Device__tasks
+            assert len(tasks) == 2
+            assert "foo_task" in tasks
+            assert "bar_task" in tasks
+            assert "foo_command" not in tasks
+            assert "bar_command" not in tasks
+            commands = device._Device__commands
+            assert "foo_task" not in commands
+            assert "bar_task" not in commands
+            assert "foo_command" in commands
+            assert "bar_command" in commands
+
 
 class MockChannel:
     def __init__(self, fake):