base: Improve @shc.handler() to allow defining handler functions with less parameters

This commit includes tests and documentation for this new feature. We also needed
to fix our AsyncMock implementation to work well with inspect.signature() in the
tests.

Fixes mhthies#63

Author: mhthies

docs/base.rst

@@ -181,7 +181,7 @@ Putting it all together, a logic handler may look as follows::
     @timer.trigger
     @some_variable.trigger
     @shc.handler()
-    async def my_logics(_value, origin):
+    async def my_logics(_value, _origin):
         """ Write value of `some_variable` to KNX bus every 5 minutes & when it changes, but only for values > 42 """
         # We cannot use the value provided, since it is not defined when triggered by the timer
         value = await some_variable.read()
@@ -231,6 +231,27 @@ Putting it all together, a logic handler may look as follows::
             # Unfortunately, no .write() or .read() possible here.
 
 
+.. tip::
+
+    The :func:`shc.handler` and :func:`shc.blocking_handler` decorators take care of calling the logic handler function with the correct number of arguments:
+    If you don't need the ``origin`` list, you can simply omit the second parameter of your wrapped logic handler function::
+
+        @shc.handler()
+        async def my_value_only_handler(value):
+            await some_variable.write(value + 3)
+
+    If you don't need the ``value`` either, you can also omit this parameter.
+    Hence, the logic handler from the first example above can be rewritten as::
+
+        @timer.trigger
+        @some_variable.trigger
+        @shc.handler()
+        async def my_logics():
+            value = await some_variable.read()
+            if value > 42:
+                await some_knx_object.write(value)
+
+
 ``shc.base`` Module Reference
 -----------------------------
 

shc/base.py

@@ -13,6 +13,7 @@
 import asyncio
 import contextvars
 import functools
+import inspect
 import logging
 import random
 from typing import Generic, List, Any, Tuple, Callable, Optional, Type, TypeVar, Awaitable, Union, Dict, Set
@@ -433,7 +434,12 @@ async def _from_provider(self) -> Optional[T_con]:
         return convert(val) if convert else val
 
 
-def handler(reset_origin=False, allow_recursion=False) -> Callable[[LogicHandler], LogicHandler]:
+LogicHandlerOptionalParams = Union[LogicHandler,
+                                   Callable[[T], Awaitable[None]],
+                                   Callable[[], Awaitable[None]]]
+
+
+def handler(reset_origin=False, allow_recursion=False) -> Callable[[LogicHandlerOptionalParams], LogicHandler]:
     """
     Decorator for custom logic handler functions.
 
@@ -445,6 +451,10 @@ def handler(reset_origin=False, allow_recursion=False) -> Callable[[LogicHandler
     * the `origin` can magically be passed when called directly by other logic handlers
     * the execution is skipped when called recursively (i.e. the logic handler is already contained in the `origin` list
 
+    It also allows to define the logic handler function with different numbers of parameters: If the function takes two
+    parameters, the trigger *value* and the *origin* are passed. If the function takes one parameter, only the *value*
+    is passed. If the function takes no parameters, it is called without arguments.
+
     :param reset_origin: If True, the origin which is magically passed to all `write` calls, only contains the logic
         handler itself, not the previous `origin` list, which led to the handler's execution. This can be used to
         change an object's value, which triggered this logic handler. This may cause infinite recursive feedback loops,
@@ -453,7 +463,9 @@ def handler(reset_origin=False, allow_recursion=False) -> Callable[[LogicHandler
         passed values and/or the `origin` list itself to prevent infinite feedback loops via `write` calls or calls to
         other logic handlers – especiaally when used together with `reset_origin`.
     """
-    def decorator(f: LogicHandler) -> LogicHandler:
+    def decorator(f: LogicHandlerOptionalParams) -> LogicHandler:
+        num_args = _count_function_args(f)
+
         @functools.wraps(f)
         async def wrapper(value, origin: Optional[List[Any]] = None) -> None:
             if origin is None:
@@ -467,7 +479,12 @@ async def wrapper(value, origin: Optional[List[Any]] = None) -> None:
             logger.info("Triggering logic handler %s() from %s", f.__name__, origin)
             try:
                 token = magicOriginVar.set([wrapper] if reset_origin else (origin + [wrapper]))
-                await f(value, origin)
+                if num_args == 0:
+                    await f()  # type: ignore
+                elif num_args == 1:
+                    await f(value)  # type: ignore
+                else:
+                    await f(value, origin)  # type: ignore
                 magicOriginVar.reset(token)
             except Exception as e:
                 logger.error("Error while executing handler %s():", f.__name__, exc_info=e)
@@ -486,9 +503,12 @@ def blocking_handler() -> Callable[[Callable[[T, List[Any]], None]], LogicHandle
     Like :func:`handler`, this decorator catches and logs errors and ensures that the `origin` can magically be passed
     when called directly by other logic handlers. However, since the wrapped function is not an asynchronous coroutine,
     it is not able to call :meth:`Writable.write` or another logic handler directly. Thus, this decorator does not
-    include special measures for preparing and passing the `origin` list or avoiding recursive execution.
+    include special measures for preparing and passing the `origin` list or avoiding recursive execution. Still, it
+    takes care of the correct number of arguments (zero to two) for calling the function.
     """
     def decorator(f: Callable[[T, List[Any]], None]) -> LogicHandler:
+        num_args = _count_function_args(f)
+
         @functools.wraps(f)
         async def wrapper(value, origin: Optional[List[Any]] = None) -> None:
             if origin is None:
@@ -499,8 +519,19 @@ async def wrapper(value, origin: Optional[List[Any]] = None) -> None:
             logger.info("Triggering blocking logic handler %s() from %s", f.__name__, origin)
             try:
                 loop = asyncio.get_event_loop()
-                await loop.run_in_executor(None, f, value, origin)
+                args = (value, origin)[:num_args]
+                await loop.run_in_executor(None, f, *args)
             except Exception as e:
                 logger.error("Error while executing handler %s():", f.__name__, exc_info=e)
         return wrapper
     return decorator
+
+
+def _count_function_args(f: Callable) -> int:
+    num_args = 0
+    for param in inspect.signature(f).parameters.values():
+        if param.kind in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD):
+            num_args += 1
+        elif param.kind is inspect.Parameter.VAR_POSITIONAL:
+            num_args += 2**30
+    return num_args

test/_helper.py

@@ -12,6 +12,7 @@
 import concurrent.futures
 import functools
 import heapq
+import inspect
 import threading
 import time
 import unittest.mock
@@ -49,6 +50,11 @@ class does not have the assert_awaited features of the official AsyncMock.
     The async calls are passed to the normal call/enter/exit methods of the super class to use its usual builtin
     evaluation/assertion functionality (e.g. :meth:`unittest.mock.NonCallableMock.assert_called_with`).
     """
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        if not hasattr(self, "__signature__"):
+            self.__signature__ = inspect.signature(self.__call__)
+
     async def __call__(self, *args, **kwargs):
         return super().__call__(*args, **kwargs)
 

test/test_base.py

@@ -160,6 +160,30 @@ async def test_handler(value, _origin) -> None:
             await asyncio.sleep(0.01)
         self.assertIn("unexpected error in _write", "\n".join(ctx.output))
 
+    @async_test
+    async def test_missing_parameters(self) -> None:
+        mock = AsyncMock()
+
+        @base.handler()
+        async def full_handler(value, origin) -> None:
+            await mock(value, origin)
+
+        @base.handler()
+        async def part_handler(value) -> None:
+            await mock(value)
+
+        @base.handler()
+        async def empty_handler() -> None:
+            await mock()
+
+        await full_handler(1, [self])
+        await part_handler(2, [self, object])
+        await empty_handler(3, [self, unittest.mock.sentinel])
+        await asyncio.sleep(0.01)
+        mock.assert_has_calls([unittest.mock.call(1, [self]),
+                               unittest.mock.call(2),
+                               unittest.mock.call()])
+
 
 class TestBlockingHandler(unittest.TestCase):
     @async_test
@@ -198,6 +222,30 @@ def blocking_test_handler(value, _origin):
         await asyncio.sleep(0.01)
         mock.assert_called_once_with(TOTALLY_RANDOM_NUMBER, [self, a, test_handler])
 
+    @async_test
+    async def test_missing_parameters(self) -> None:
+        mock = unittest.mock.MagicMock()
+
+        @base.blocking_handler()
+        def full_handler(value, origin) -> None:
+            mock(value, origin)
+
+        @base.blocking_handler()
+        def part_handler(value) -> None:
+            mock(value)
+
+        @base.blocking_handler()
+        def empty_handler() -> None:
+            mock()
+
+        await full_handler(1, [self])
+        await part_handler(2, [self, object])
+        await empty_handler(3, [self, unittest.mock.sentinel])
+        await asyncio.sleep(0.01)
+        mock.assert_has_calls([unittest.mock.call(1, [self]),
+                               unittest.mock.call(2),
+                               unittest.mock.call()])
+
 
 class TestReading(unittest.TestCase):
     @async_test