MTPPy2.0 0.1.5__py3-none-any.whl

mtppy/pea/user_logic/user_logic_registry.py

@@ -0,0 +1,106 @@
+"""UserLogicRegistry is a decorator for registering user logic."""
+
+__copyright__ = (
+    "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+)
+__license__ = "MIT"
+
+from collections.abc import Callable, Iterator
+
+from mtppy.part4.automation_services.service import Service
+from mtppy.utils.logging import logger
+
+UserFunc = Callable[..., bool]
+
+
+class UserLogicRegistry:
+    """Stores and dispatches user-defined logic functions by name.
+
+    A registry maps string names to callables that accept a
+    [Service][mtppy.part4.service.service.Service] instance and return a
+    boolean. If a name is dispatched that has not been registered, the
+    configured default answer is returned instead.
+
+    Attributes:
+        _registry (dict[str, UserFunc]): Dictionary to store registered functions.
+        _default_answer (bool): Default return value when no function is registered.
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty registry and set default answer to True."""
+        # Dictionary to store registered functions.
+        self._registry: dict[str, UserFunc] = {}
+        self._default_answer = True
+
+    def register(self, *names: str) -> Callable[[UserFunc], UserFunc]:
+        """Register a function under several ``names``.
+
+        Args:
+            *names: The keys used to store and later dispatch the function.
+
+        Returns:
+            A decorator that records the decorated function and returns it
+            unchanged.
+
+        Raises:
+            KeyError if one of the names was already used or is not of str type
+        """
+
+        def decorator(func: UserFunc) -> UserFunc:
+            for name in names:
+                if type(name) is not str or not name:
+                    message = "name must be a non-empty string"
+                    raise KeyError(message)
+                if name in self._registry:
+                    registered_name = self._registry[name].__name__
+                    message = f"name {name} already used for {registered_name}"
+                    raise KeyError(message)
+                self._registry[name] = func
+            return func
+
+        return decorator
+
+    def dispatch(
+        self,
+        them: Service,
+        name: str,
+        *args: object,
+        **kwargs: object,
+    ) -> bool:
+        """Call the function registered under ``name`` if it exists.
+
+        Args:
+            them: The service instance passed as the first argument to the
+                registered function.
+            name: The registered name of the function to call.
+            *args: Positional arguments forwarded to the registered function.
+            **kwargs: Keyword arguments forwarded to the registered function.
+
+        Returns:
+            The result of the registered function, or ``_default_answer`` if no
+            function is registered under ``name``.
+        """
+        logger.debug(f"name={name}, args={args}, kwargs={kwargs}")
+        if name in self._registry:
+            try:
+                return self._registry[name](them, *args, **kwargs)
+            except Exception as ex:  # noqa: BLE001
+                msg = f"Exception in user function {name}:{ex}"
+                logger.critical(msg)
+        else:
+            msg = f"no user function registered, returning {self._default_answer}"
+            logger.info(msg)
+
+        return self._default_answer
+
+    def registered_names(self) -> tuple[str, ...]:
+        """Return registered callback names in registration order."""
+        return tuple(self._registry)
+
+    def items(self) -> Iterator[tuple[str, UserFunc]]:
+        """Iterate over registered callback names and functions."""
+        return iter(self._registry.items())
+
+
+global_registry = UserLogicRegistry()
+register = global_registry.register

mtppy/pea/user_logic/user_logic_registry_test.py

@@ -0,0 +1,167 @@
+"""Unit tests for the UserLogicRegistry class."""
+
+__copyright__ = (
+    "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+)
+__license__ = "MIT"
+
+import unittest
+from unittest.mock import Mock
+from mtppy.pea.user_logic.user_logic_registry import UserLogicRegistry, global_registry
+from mtppy.pea.user_logic.user_logic_registry import register
+
+
+class TestUserLogicRegistry(unittest.TestCase):
+    """Test cases for the UserLogicRegistry class."""
+
+    def setUp(self):
+        """Set up test fixtures before each test method."""
+        self.registry = UserLogicRegistry()
+
+    def test_init_empty_registry(self):
+        """Test that the registry initializes with an empty registry and default answer."""
+        self.assertEqual(self.registry._registry, {})
+        self.assertEqual(self.registry._default_answer, True)
+
+    def test_register_function(self):
+        """Test that functions can be registered with names."""
+
+        def mock_func(service):
+            return True
+
+        # Register the function
+        decorated_func = self.registry.register("test_func")(mock_func)
+
+        # Check that function is registered
+        self.assertIn("test_func", self.registry._registry)
+        self.assertEqual(self.registry._registry["test_func"], mock_func)
+
+        # Check that decorator returns the original function
+        self.assertEqual(decorated_func, mock_func)
+
+    def test_register_multiple_names(self):
+        """Test that functions can be registered under multiple names."""
+
+        def mock_func(service):
+            return True
+
+        # Register the function under multiple names
+        self.registry.register("func1", "func2", "func3")(mock_func)
+
+        # Check that all names are registered
+        self.assertIn("func1", self.registry._registry)
+        self.assertIn("func2", self.registry._registry)
+        self.assertIn("func3", self.registry._registry)
+        self.assertEqual(self.registry._registry["func1"], mock_func)
+        self.assertEqual(self.registry._registry["func2"], mock_func)
+        self.assertEqual(self.registry._registry["func3"], mock_func)
+
+    def test_dispatch_existing_function(self):
+        """Test that dispatch calls registered functions."""
+        service_mock = Mock()
+
+        def mock_func(service):
+            return False
+
+        # Register the function
+        self.registry.register("test_func")(mock_func)
+
+        # Dispatch the function
+        result = self.registry.dispatch(service_mock, "test_func")
+
+        # Check that function was called and returned expected value
+        self.assertFalse(result)
+
+    def test_dispatch_non_existing_function(self):
+        """Test that dispatch returns default answer for non-existing functions."""
+        service_mock = Mock()
+
+        # Dispatch a non-existing function
+        result = self.registry.dispatch(service_mock, "non_existing_func")
+
+        # Should return the default answer (True)
+        self.assertTrue(result)
+
+    def test_dispatch_with_args_and_kwargs(self):
+        """Test that dispatch forwards arguments to registered functions."""
+        service_mock = Mock()
+
+        def mock_func(service, arg1, arg2, kwarg1=None):
+            self.assertEqual(arg1, "test_arg1")
+            self.assertEqual(arg2, "test_arg2")
+            self.assertEqual(kwarg1, "test_kwarg1")
+            return True
+
+        # Register the function
+        self.registry.register("test_func")(mock_func)
+
+        # Dispatch with arguments
+        result = self.registry.dispatch(
+            service_mock, "test_func", "test_arg1", "test_arg2", kwarg1="test_kwarg1"
+        )
+
+        # Check that function returned expected value
+        self.assertTrue(result)
+
+    def test_global_registry(self):
+        """Test that the global registry works as expected."""
+        # Test that global registry exists
+        self.assertIsInstance(global_registry, UserLogicRegistry)
+
+        # Test registering via global registry
+        def global_func(service):
+            return "global_result"
+
+        global_registry.register("global_test")(global_func)
+        self.assertIn("global_test", global_registry._registry)
+
+    def test_register_decorator(self):
+        """Test that the register decorator works."""
+
+        def decorated_func(service):
+            return "decorator_result"
+
+        # Apply the decorator
+        registered_func = register("decorated_test")(decorated_func)
+
+        # Should be registered in global registry
+        self.assertIn("decorated_test", global_registry._registry)
+        self.assertEqual(global_registry._registry["decorated_test"], decorated_func)
+
+    def test_register_same_name_raises_exception(self):
+        """Test that registering two different functions under the same name raises an exception."""
+
+        def func1(service):
+            return "result1"
+
+        def func2(service):
+            return "result2"
+
+        # Register first function
+        self.registry.register("same_name")(func1)
+
+        # Register second function with same name - should raise exception
+        with self.assertRaises(KeyError):
+            self.registry.register("same_name")(func2)
+
+    def test_register_invalid_key_name_raises_exception(self):
+        """Test that registering a function with an invalid key name raises an exception."""
+
+        def mock_func(service):
+            return True
+
+        # Test with None as key name (invalid for dict)
+        with self.assertRaises(KeyError):
+            self.registry.register(None)(mock_func)
+
+        # Test with list as key name (invalid for dict)
+        with self.assertRaises(KeyError):
+            self.registry.register([])(mock_func)
+
+        # Test with dict as key name (invalid for dict)
+        with self.assertRaises(KeyError):
+            self.registry.register({})(mock_func)
+
+
+if __name__ == "__main__":
+    unittest.main()

mtppy/pea/user_logic/user_logic_service.py

@@ -0,0 +1,228 @@
+"""UserLogicService implements Service and executes registered user logic."""
+
+__copyright__ = (
+    "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+)
+__license__ = "MIT"
+
+import time
+from collections.abc import Callable
+
+from mtppy.part3.data_assembly_set.data_assembly import DataAssembly
+from mtppy.part4.definitions.state_codes import StateCodes
+from mtppy.part4.automation_services.service import Service
+from mtppy.part4.automation_services.procedure import Procedure
+from mtppy.utils.logging import logger
+from mtppy.pea.user_logic.user_logic_registry import UserLogicRegistry
+
+UserFunc = Callable[[Service], bool]
+
+
+class UserLogicService(Service):
+    """Implementation of Service that calls user logic, registered by the
+    UserLogicRegistry.
+
+    This service acts as a bridge between the service execution framework and
+    user-defined logic functions that are registered in a UserLogicRegistry.
+
+    The state model follows the UML-State-Chart notation with entry, do, and exit
+    actions. Each state in the service lifecycle has three phases:
+    - entry: Executed once when entering the state
+    - do: Executed repeatedly while in the state (for cyclic states) until user
+    function returns `False`
+    - exit: Executed once when leaving the state
+
+    Attributes:
+        _registry: The UserLogicRegistry containing user-defined functions.
+        _cycle_time: Time interval (in seconds) for cyclic state execution.
+    """
+
+    ENTRY = "entry"
+    DO = "do"
+    EXIT = "exit"
+
+    def __init__(
+        self,
+        tag_name: str,
+        tag_description: str,
+        registry: UserLogicRegistry | None = None,
+        procedures: list[Procedure] | None = None,
+        cycle_time: float = 0.5,
+    ) -> None:
+        """Initialize the UserLogicService.
+
+        Args:
+            tag_name: The name of the service instance.
+            tag_description: A description of the service.
+            registry: Optional UserLogicRegistry containing user functions.
+            procedures: Optional list of procedures for the service.
+            cycle_time: Time interval (in seconds) for cyclic state execution.
+        """
+        super().__init__(tag_name, tag_description)
+
+        self.add_procedure(procedures)
+
+        self._registry = registry
+        self._cycle_time = cycle_time
+
+    def set_cycle_time(self, cycle_time: float) -> None:
+        """Set the cycle time for this service.
+
+        Args:
+            cycle_time: Time interval (in seconds) for cyclic state execution.
+        """
+        self._cycle_time = cycle_time
+
+    def set_registry(self, registry: UserLogicRegistry) -> None:
+        """Set the user logic registry for this service.
+
+        Args:
+            registry: The UserLogicRegistry containing user functions to be used.
+        """
+        self._registry = registry
+
+    def dispatch(self, name: str, *args, **kwargs) -> bool:
+        """Dispatch call to the registered function.
+
+        Args:
+            name: Name of the function to be called.
+            *args: Positional arguments to forward to the registered function.
+            **kwargs: Keyword arguments to forward to the registered function.
+
+        Returns:
+            The result of the registered function, or the default answer if no
+            function is registered under the given name.
+
+        Raises:
+            RuntimeError: If no registry is attached to the service.
+        """
+        if self._registry is not None:
+            return self._registry.dispatch(self, name, *args, **kwargs)
+        else:
+            raise RuntimeError("no registry registered")
+
+    def _user_code_callback_name(
+        self,
+        proc_name: str,
+        state_name: str,
+        action: str,
+    ) -> str:
+        """Build the lookup name for the dispatch table.
+
+        Args:
+            proc_name: Name of the procedure.
+            state_name: Name of the state.
+            action: Action type (entry, do, exit).
+
+        Returns:
+            The formatted callback name for dispatching.
+        """
+        return f"{self.name}.{proc_name}.{state_name}.{action}"
+
+    def _transient_state(self, state_name: str) -> None:
+        """Call the user function bound to the specific transient state.
+
+        This method handles transient states that have entry, do, and exit phases.
+        It calls the user functions for each phase and manages state transitions.
+
+        Args:
+            state_name: Name of the transient state to execute.
+        """
+        logger.app(f"self={self.name}, state_name={state_name}")
+        proc_name = self._lookup_procedure_cur_name()
+        if proc_name != "undefined":
+            self.dispatch(
+                self._user_code_callback_name(proc_name, state_name, self.ENTRY)
+            )
+            self.dispatch(self._user_code_callback_name(proc_name, state_name, self.DO))
+            self.dispatch(
+                self._user_code_callback_name(proc_name, state_name, self.EXIT)
+            )
+            self.state_change()
+        else:
+            # this should not happen!
+            logger.warning("proc undefined called!")
+            time.sleep(self._cycle_time)
+
+    def _cyclic_state(self, state_name: str) -> None:
+        """Call the user function bound to the specific cyclic state.
+
+        This method handles cyclic states that execute repeatedly until the
+        state changes or the service is stopped.
+
+        Args:
+            state_name: Name of the cyclic state to execute.
+        """
+        logger.app(f"self={self.name}, state_name={state_name}")
+        proc_name = self._lookup_procedure_cur_name()
+        cycle = 0
+        self.dispatch(self._user_code_callback_name(proc_name, state_name, self.ENTRY))
+        while self.is_state(state_name) and not (self.thread_ctrl.is_stopped()):
+            self.dispatch(self._user_code_callback_name(proc_name, state_name, self.DO))
+            time.sleep(self._cycle_time)
+            cycle += 1
+        self.dispatch(self._user_code_callback_name(proc_name, state_name, self.EXIT))
+
+    def idle(self) -> None:
+        """Execute the entry, do, and exit functions bound to idle."""
+        self._cyclic_state(StateCodes.IDLE.string)
+
+    def starting(self) -> None:
+        """Execute the entry, do, and exit functions bound to starting."""
+        self._transient_state(StateCodes.STARTING.string)
+
+    def execute(self) -> None:
+        """Execute the entry, do, and exit functions bound to execute."""
+        self._cyclic_state(StateCodes.EXECUTE.string)
+
+    def completing(self) -> None:
+        """Execute the entry, do, and exit functions bound to completing."""
+        self._transient_state(StateCodes.COMPLETING.string)
+
+    def completed(self) -> None:
+        """Execute the entry, do, and exit functions bound to completed."""
+        self._cyclic_state(StateCodes.COMPLETING.string)
+
+    def pausing(self) -> None:
+        """Execute the entry, do, and exit functions bound to pausing."""
+        self._transient_state(StateCodes.PAUSING.string)
+
+    def paused(self) -> None:
+        """Execute the entry, do, and exit functions bound to paused."""
+        self._cyclic_state(StateCodes.PAUSED.string)
+
+    def resuming(self) -> None:
+        """Execute the entry, do, and exit functions bound to resuming."""
+        self._transient_state(StateCodes.RESUMING.string)
+
+    def holding(self) -> None:
+        """Execute the entry, do, and exit functions bound to holding."""
+        self._transient_state(StateCodes.HOLDING.string)
+
+    def held(self) -> None:
+        """Execute the entry, do, and exit functions bound to held."""
+        self._cyclic_state(StateCodes.HELD.string)
+
+    def unholding(self) -> None:
+        """Execute the entry, do, and exit functions bound to unholding."""
+        self._transient_state(StateCodes.UNHOLDING.string)
+
+    def stopping(self) -> None:
+        """Execute the entry, do, and exit functions bound to stopping."""
+        self._transient_state(StateCodes.STOPPING.string)
+
+    def stopped(self) -> None:
+        """Execute the entry, do, and exit functions bound to stopped."""
+        self._cyclic_state(StateCodes.STOPPED.string)
+
+    def aborting(self) -> None:
+        """Execute the entry, do, and exit functions bound to aborting."""
+        self._transient_state(StateCodes.ABORTING.string)
+
+    def aborted(self) -> None:
+        """Execute the entry, do, and exit functions bound to aborted."""
+        self._cyclic_state(StateCodes.ABORTED.string)
+
+    def resetting(self) -> None:
+        """Execute the entry, do, and exit functions bound to resetting."""
+        self._transient_state(StateCodes.RESETTING.string)