cgse 2024.7.0__py3-none-any.whl → 2025.0.2__py3-none-any.whl

egse/command.py

@@ -1,699 +0,0 @@
-"""
-This module defines a number of classes and helper functions to define and work
-with commands that operate hardware devices. The goal is to be able to define /
-create commands transparently from a YAML file without having to write (too much)
-code.
-
-A few definitions for the classes defined in this module:
-
-**command**
-
-a string that is sent to a device over an interface like TCP/IP or USB. This
-string is generated by the get_cmd_string() method of the Command class.
-
-The string contains format like syntax that looks like an f-string, but is
-interpreted differently. See further: How to format device command strings.
-
-**Command**
-
-the base class for commands. This class contains the definition of the command
-and provides methods to parse and check arguments. The Command can be 'called'
-or 'executed' in which case a number of actons are performed based on the
-provided arguments.
-
-**CommandExecution**
-
-this class contains all the information needed to execute a command, without
-actually executing it. A CommandExecution contains the command definition and
-the parameters for the execution. It is mainly served as a communication
-mechanism to the control servers, i.e. the client side (Proxy) defines a
-command execution and the server then executes the command.
-
-**CommandError**
-
-a catch-all exception for unrecoverable errors in this module
-
-**InvalidArgumentsError**
-
-a CommandError raised when the arguments provided are themselve invalid
-or if the number of arguments is not matching expectations
-
-The basic interface is:
-
-    cmd = Command(name     = <command name>,
-                  cmd      = <command string>,
-                  response = <callable to retreive a response>,
-                  wait     = <callable to wait a specific time/delay>)
-
-where:
-
-* name: a name for the command, this is just needed for reporting, not used in commanding
-* cmd: the command string to send or execute, see further for details
-* response: send a second command to read or get a response on the 'cmd' sent
-* wait: a function object that will wait for a specific duration,
-  e.g. ```partial(time.sleep, 10)```
-
-How to format device command strings
-
-The ``cmd`` argument is a string that contains placeholders (replacement fields)
-for future arguments that will be passed when calling the Command. The replacement
-fields are marked with curly braces and are mandatory. When a name is provided
-in the curly braces, the argument shall be provided as a keyword argument, otherwise
-a positional argument is expected. In the current implementation the ``cmd``
-can only contain either positional arguments or keyword argument, not a mix of both.
-
-The replacement fields may also have a format specifier to specify a precise format
-for that field.
-
-**Examples**
-
-    moveAbsolute = Command(
-        name = "moveAbsolute",
-        cmd  = "&2 Q70=0 Q71={tx:.6f} Q72={ty:.6f} Q73={tz:.6f} "
-               "Q74={rx:.6f} Q75={ry:.6f} Q76={rz:.6f} Q20=11"
-    )
-
-    response = moveAbsolute(1, 1, 1, 0, 0, 20)
-    response = moveAbsolute(tx=1, ty=1, tz=1, rx=0, ry=0, rz=20)
-
-
-Questions
-
-Do we need additional hooks into this commanding?
-
-* add a meaning to the check, what is it and what is it used for?
-* add a output processor possibility. A callback function that will process the
-  output value before returning it by the __call__.
-* provide an execute method for the CommandExecution that executes the command
-  with the saved parameters
-"""
-import functools
-import inspect
-import logging
-import re
-from collections import namedtuple
-from typing import Callable
-
-from egse.control import Success
-from egse.exceptions import Error
-
-logger = logging.getLogger(__name__)
-
-
-def stringify_function_call(function_info: dict) -> str:
-    def quote(value):
-        return f'"{value}"' if isinstance(value, str) else value
-
-    description = function_info.get("description")
-    if description:
-        return description
-
-    result = ""
-
-    name = function_info.get("func_name")
-    args = function_info.get("args")
-    kwargs = function_info.get("kwargs")
-
-    if name:
-        result += name
-    else:
-        result += "unknown_function"
-
-    result += "("
-
-    if args:
-        result += f"{args}"[1:-1]
-
-    if kwargs:
-        result += ", " if args else ""
-        result += ", ".join([f"{k}={quote(v)}" for k, v in kwargs.items()])
-
-    result += ")"
-
-    return result
-
-
-def dry_run(func: Callable) -> Callable:
-    """This decorator prepares the function to handle a dry run.
-
-    A dry run is used to check the logic of an instrument commanding script without
-    actually executing the instrument commands. The commands are instead added to the
-    command sequence in the global state.
-
-    Args:
-        func: the function that needs to be executed
-
-    Returns:
-        A wrapper around the given function.
-    """
-
-    @functools.wraps(func)
-    def func_wrapper(self, *args, **kwargs):
-
-        from egse.state import GlobalState  # prevent circular import
-
-        if GlobalState.dry_run:
-            if callable(func) and func.__name__ == "client_call":
-                # This client_call function takes an additional argument which is the Proxy.
-                # the Proxy is not part of the CommandExecution signature and shall be removed
-                # FIXME: do we introduce a memory leak here by adding 'self' to this GlobalState?
-                args = args[1:]
-                try:
-                    self.validate_arguments(*args, **kwargs)
-                except CommandError as e_ce:
-                    GlobalState.add_command(InvalidCommandExecution(e_ce, self, *args, **kwargs))
-                else:
-                    GlobalState.add_command(CommandExecution(self, *args, **kwargs))
-            else:
-                FunctionExecution = namedtuple("FunctionExecution", ["name", "args", "kwargs"])
-                GlobalState.add_command(FunctionExecution(func.__name__, args, kwargs))
-            return Success(
-                "Command execution appended to command sequence, function not executed in dry_run."
-            )
-        else:
-            return func(self, *args, **kwargs)
-
-    return func_wrapper
-
-
-def parse_format_string(fstring):
-    """
-    Parse and decode the format string.
-    """
-    # Remove occurrences of {{ }} from the fstring as they are not replacement fields
-    # and will occur after formatting as single braces.
-
-    fstring = re.sub(r"{{.*}}", lambda x: "_", fstring)
-
-    # logger.debug(f"fstring = '{fstring}', replaced {{{{.*}}}} with _")
-
-    parts = re.findall(r"\{(.*?)\}", fstring)
-
-    # logger.debug(f"Parts: {parts!r}, n={len(parts)}")
-
-    tot_n_args = len(parts)
-    n_args = 0
-    n_kwargs = 0
-    keys = []
-
-    for part in parts:
-        result = re.split(r"(:)", part)
-        if result[0] == "":
-            n_args += 1
-        else:
-            n_kwargs += 1
-            keys.append(result[0])
-
-    # If this assertion fails, there is a flaw in the algorithm above
-    assert tot_n_args == n_args + n_kwargs, (
-        f"Total number of arguments ({tot_n_args}) doesn't match # args ({n_args}) + "
-        f"# kwargs ({n_kwargs})."
-    )
-
-    if n_args > 0 and n_kwargs > 0:
-        raise InvalidArgumentsError("Mixing of positional and keyword arguments is not available.")
-
-    return tot_n_args, n_args, n_kwargs, keys
-
-
-class CommandError(Error):
-    """A Command Exception as a base class for this module."""
-
-
-class InvalidArgumentsError(CommandError):
-    """The arguments provided are invalid"""
-
-
-class CommandExecution:
-    """
-    This class contains all the information that is needed to execute a command
-    with a set of parameters/arguments. The command is however not executed
-    automatically. That is the responsibility of the caller to actually execute
-    the command with the given parameters.
-
-    Developer info
-
-    you can see this as a partial (functools) which defines the command and
-    its arguments, but doesn't execute until explicitly called. You can execute
-    the command by calling the `cmd` with the given arguments:
-
-       ```
-       ce = CommandExecution(cmd, 20.0)
-       ...
-       response = ce.run()
-       ```
-    """
-
-    def __init__(self, cmd, *args, **kwargs):
-        self._cmd = cmd
-        self._args = args
-        self._kwargs = kwargs
-
-    def get_name(self):
-        return self._cmd.get_name()
-
-    def get_cmd(self):
-        return self._cmd
-
-    def get_args(self):
-        return self._args
-
-    def get_kwargs(self):
-        return self._kwargs
-
-    def run(self):
-        return self._cmd(*self._args, **self._kwargs)
-
-    def __str__(self):
-        msg = f"[{self.get_cmd().__class__.__name__}] {self.get_name()}("
-        for arg in self.get_args():
-            msg += f"{arg}, "
-        for k, v in self.get_kwargs().items():
-            msg += f"{k}={v}, "
-        if msg.endswith(", "):
-            msg = msg[:-2]
-        msg += ")"
-        return msg
-
-
-class InvalidCommandExecution(CommandExecution):
-    """A invalid command execution."""
-
-    def __init__(self, exc, cmd, *args, **kwargs):
-        """
-        Args:
-            exc: the Exception that was raised and describes the problem
-            cmd: the Command object
-            *args: the positional arguments that were given
-            **kwargs: the keyword arguments that were given
-        """
-        super().__init__(cmd, *args, **kwargs)
-        self._exc = exc
-
-    def run(self):
-        raise InvalidArgumentsError(
-            f"The command {self.get_name()} can not be executed. Reason: {self._exc}"
-        )
-
-    def __str__(self):
-        msg = super().__str__()
-        msg += f" [ERROR: {self._exc}]"
-        return msg
-
-
-class WaitCommand:
-    def __init__(self, command, condition):
-        self._command = command
-        self._condition = condition
-
-    def __call__(self):
-
-        # .. todo:: do we need a timeout possibility here?
-
-        while True:
-            return_code = self._command()
-            if self._condition(return_code):
-                break
-
-        return 0
-
-
-class Command:
-    """
-    A Command is basically a string that is send to a device and for which the
-    device returns a response.
-
-    The command string can contain placeholders that will be filled when the
-    command is 'called'.
-
-    The arguments that are given will be filled into the formatted string.
-    Arguments can be positional or keyword arguments, not both.
-    """
-
-    def __init__(
-            self, name, cmd, response=None, wait=None, check=None, description=None,
-            device_method=None
-    ):
-        self._name = name
-        self._cmd = cmd
-        self._response = response
-        self._wait = wait
-        self._check = check
-        self._description = description
-        self._device_method = device_method
-
-        tot_n_args, n_args, n_kwargs, keys = parse_format_string(cmd)
-
-        self._tot_n_args = tot_n_args
-        self._n_args = n_args
-        self._n_kwargs = n_kwargs
-        self._keys = keys
-
-        self.__doc__ = self.doc_string()
-
-    def doc_string(self):
-        msg = f"usage: {self._name}(nargs={self._tot_n_args}, keys={self._keys})\n"
-        msg += "       args & kwargs can be mixed (limited)"
-
-        if self._description is not None:
-            msg += "\n"
-            msg += f"{self._description}\n"
-
-        return msg
-
-    def validate_arguments(self, *args, **kwargs):
-
-        # Special case for commands with *args or **kwargs, we don't validate
-
-        if self._cmd in ("*", "**"):
-            return
-
-        nargs = len(args)
-        nkwargs = len(kwargs)
-
-        if self._tot_n_args != nargs + nkwargs:
-            raise InvalidArgumentsError(
-                f"Expected {self._tot_n_args} arguments for command {self._name}, "
-                f"got {nargs + nkwargs} arguments."
-            )
-
-        if self._tot_n_args == 0:
-            pass
-        elif nargs and nargs == self._n_args:
-            pass
-        elif nkwargs and nkwargs == self._n_kwargs:
-            pass
-        elif nargs == self._n_kwargs and nkwargs == 0:
-            pass
-        else:
-            raise InvalidArgumentsError(
-                f"Expected {self._n_args} positional arguments and {self._n_kwargs} "
-                f"keyword arguments for command {self._name}, got {nargs} positional "
-                f"and {nkwargs} keyword arguments instead."
-            )
-
-    def execute(self, cmd):
-        return 0
-
-    def get_name(self):
-        return self._name
-
-    def needs_argument(self, name):
-        if name in self._keys:
-            return True
-        return False
-
-    def __repr__(self):
-        name = self._name if hasattr(self, "_name") else None
-        return f"<{self.__class__.__name__}({name})>"
-
-    def get_device_method(self):
-        return self._device_method
-
-    def get_device_method_name(self):
-        return self._device_method.__name__
-
-    def get_command_execution(self, *args, **kwargs):
-
-        return CommandExecution(self, *args, **kwargs)
-
-    def __call__(self, *args, **kwargs):
-        cmd_string = self.get_cmd_string(*args, **kwargs)
-
-        # Now execute the cmd_string
-
-        response = self.execute(cmd_string)
-
-        if self._wait is not None:
-            self._wait()
-
-        if self._response is not None:
-            response = self._response()
-
-        if self._check is not None:
-            response = self._check(response)
-
-        return response
-
-    def get_raw_cmd_string(self):
-        return self._cmd
-
-    def get_cmd_string(self, *args, **kwargs):
-        nargs = len(args)
-        nkwargs = len(kwargs)
-
-        if self._tot_n_args != nargs + nkwargs:
-            raise CommandError(
-                f"Expected {self._tot_n_args} arguments for command {self._name}, "
-                f"got {nargs + nkwargs} arguments."
-            )
-
-        if self._tot_n_args == 0:
-            cmd_string = self._cmd or self._name
-        elif nargs and nargs == self._n_args:
-            cmd_string = self._create_command_string_from_args(*args)
-        elif nkwargs and nkwargs == self._n_kwargs:
-            cmd_string = self._create_command_string_from_kwargs(**kwargs)
-        elif nargs == self._n_kwargs and nkwargs == 0:
-            cmd_string = self._create_command_string_from_args_with_kw(*args)
-        else:
-            raise CommandError(
-                f"Expected {self._n_args} positional arguments and {self._n_kwargs} "
-                f"keyword arguments for command {self._name}, got {nargs} positional "
-                f"and {nkwargs} keyword arguments instead."
-            )
-
-        return cmd_string
-
-    def _create_command_string_from_args(self, *args):
-        full_command = self._cmd.format(*args)
-        return full_command
-
-    def _create_command_string_from_args_with_kw(self, *args):
-        full_command = self._cmd.format(**{k: v for k, v in zip(self._keys, args)})
-        return full_command
-
-    def _create_command_string_from_kwargs(self, **kwargs):
-        full_command = self._cmd.format(**kwargs)
-        return full_command
-
-
-class ClientServerCommand(Command):
-    @dry_run
-    def client_call(self, other, *args, **kwargs):
-        """
-        This method is called at the client side. It is used by the Proxy
-        as a generic command to send a command execution to the server.
-
-        Args:
-            other: a sub-class of the Proxy class
-            args: arguments that will be passed on to this command when executed
-            kwargs: keyword arguments that will be passed on to this command when executed
-
-        Returns:
-            the response that is returned by calling the command (at the server side).
-        """
-
-        try:
-            self.validate_arguments(*args, **kwargs)
-        except CommandError as e_ce:
-            logger.error(str(e_ce))
-            return None
-
-        ce = CommandExecution(self, *args, **kwargs)
-        rc = other.send(ce)
-
-        # FIXME:
-        #   not sure if I should do this, the Success/Failure returns from the CS should be
-        #   re-designed. I have put this here for the following reason: when requesting an obsid
-        #   from the CM_CS we don't want a Success message back, but we need the number!
-
-        # if isinstance(rc, Success):
-        #     logger.info(rc)
-        #     rc = rc.return_code
-
-        return rc
-
-    def server_call(self, other, *args, **kwargs):
-        """
-        This method is called at the server side. It is used by the CommandProtocol class in the
-        ``execute`` method.
-
-        Args:
-            other: a sub-class of the CommandProtocol
-            args: arguments are passed on to the response method
-            kwargs: keyword arguments are passed on to the response method
-
-        Returns:
-            0 on success and -1 on failure.
-        """
-
-        if self._response is None:
-            logger.warning(f"No response defined for {other} command {self.get_name()}")
-            return -1
-
-        # Note that `_response` is of type 'function' because it was loaded from
-        # a class object and therefore not bound to a class instance. The reason
-        # that we could not use a bound method for `_response` is that we pass the
-        # command objects back and forth from the control server to the proxy and
-        # the class instances are not known at the other side.
-
-        if self._response.__name__ == "handle_device_method":
-
-            # call the handle_device_method of the Protocol sub-class
-
-            logger.log(0,
-                       f"Executing Command {self._response.__name__}({other!r}, "
-                       f"{self!r}, {args}, {kwargs})")
-
-            rc = self._response(other, self, *args, **kwargs)
-        else:
-            logger.log(0,
-                       f"Executing Command {self._response.__name__}({other!r}, {args}, {kwargs})")
-
-            rc = self._response(other, *args, **kwargs)
-
-        logger.log(0, f"Response is {rc}.")
-
-        return 0
-
-
-def get_method(parent_obj, method_name: str):
-    """
-    Returns a bound method from a given class instance.
-
-    Args:
-        parent_obj: the class instance that provides the method
-        method_name: name of the method that is requested
-
-    Returns:
-        the method [type: method].
-
-    .. note::
-        The method returned is an bound class instance method and therefore
-        this method *does not* expects as its first argument the class
-        instance, i.e. self, when you call this as a function.
-
-    """
-    if method_name is None or method_name == "None":
-        return None
-
-    if hasattr(parent_obj, method_name):
-        method = getattr(parent_obj, method_name)
-        if inspect.ismethod(method):
-            return method
-        logger.warning(f"{method_name} is not a method, type={type(method)}")
-    else:
-        logger.warning(f"{parent_obj!r} has no method called {method_name}")
-
-    return None
-
-
-def get_function(parent_class, method_name: str):
-    """
-    Returns a function (unbound method) from a given class.
-
-    Args:
-        parent_class: the class that provides the method
-        method_name: name of the method that is requested
-
-    Returns:
-        the method [type: function].
-
-    .. note::
-        The function returned is an unbound class instance method and
-        therefore this function expects as its first argument the class
-        instance, i.e. self, when you call it as a function.
-
-    """
-    if method_name is None or method_name == "None":
-        return None
-
-    if hasattr(parent_class, method_name):
-        func = getattr(parent_class, method_name)
-        if inspect.isfunction(func):
-            return func
-        logger.warning(f"{method_name} is not a function, type={type(func)}")
-    else:
-        logger.warning(
-            f"{parent_class.__module__}.{parent_class.__name__} has no method called {method_name}"
-        )
-
-    return None
-
-
-def load_commands(protocol_class, command_settings, command_class, device_class):
-    """
-    Loads the command definitions from the given ``command_settings`` and builds an internal
-    dictionary containing the command names as keys and the corresponding ``Command`` class objects
-    as values.
-
-    The ``command_settings`` is usually loaded from a YAML configuration file containing the
-    command definitions for the device.
-
-    Args:
-        protocol_class: the CommandProtocol or a sub-class
-        command_settings: a dictionary containing the command definitions for this device
-        command_class: the type of command to create, a subclass of Command
-        device_class: the type of the base device class from which the methods are loaded
-    """
-    commands = {}
-
-    for name in command_settings:
-        command_settings_name = command_settings[name]
-        if "cmd" in command_settings_name:
-            cmd = command_settings_name["cmd"]
-        else:
-            cmd = ""
-
-        if "description" in command_settings_name:
-            description = command_settings_name["description"]
-        else:
-            description = None
-
-        # The response field is the name of a function from the CommandProtocol class
-        # or a sub-class. This function shall send a response back to the client (Proxy). That's
-        # why this field is called response.
-        # By convention we like that this method name would start with `handle_` so that we can
-        # make a distinction between response commands and normal methods in Protocol. Remember
-        # that response methods should send a reply back to the client (which will be waiting for
-        # it..). If no response field is given, then the `handle_device_method` will be called.
-
-        if "response" in command_settings_name:
-            response_method = get_function(protocol_class, command_settings_name["response"])
-        else:
-            response_method = get_function(protocol_class, "handle_device_method")
-            response_method = None
-
-        # The device_method field is used in the `handle_device_method` to call the method on the
-        # device class. That is the class that implements the DeviceInterface and is usually called
-        # a Controller or a Simulator.
-        #
-        # If no device_name field is given, the name from the command_settings is used.
-
-        if "device_method" in command_settings_name:
-            device_method_name = command_settings_name["device_method"]
-        else:
-            device_method_name = name
-
-        # check if the device_method exists in the device base class
-
-        if device_method_name == "None":
-            device_method = None
-        else:
-            device_method = get_function(device_class, device_method_name)
-
-        logger.debug(
-            f"Creating {command_class.__module__}.{command_class.__name__}(name='{name}', "
-            f"cmd='{cmd}', response={response_method}, device_method={device_method})"
-        )
-
-        commands[name] = command_class(
-            name=name,
-            cmd=cmd,
-            response=response_method,
-            description=description,
-            device_method=device_method,
-        )
-
-    return commands