fprime-gds 3.4.3__py3-none-any.whl → 3.4.4a2__py3-none-any.whl

fprime_gds/common/utils/string_util.py

@@ -9,12 +9,51 @@ Note: This function has an identical copy in fprime-gds
 
 import logging
 import re
+from typing import Any, Union
 
 LOGGER = logging.getLogger("string_util_logger")
 
 
-def format_string_template(format_str, given_values):
-    r"""
+def format_string_template(template: str, value: Union[tuple, list, Any]) -> str:
+    """
+    Function to format a string template with values. This function is a simple wrapper around the
+    format function. It accepts a tuple, list, or single value and passes it to the format function
+
+    Args:
+        template (str): String template to be formatted
+        value (Union[tuple, list, Any]): Value(s) to be inserted into the template
+
+    Returns:
+        str: Formatted string
+    """
+    if not isinstance(value, (tuple, list)):
+        value = (value,)
+    try:
+        return template.format(*value)
+    except (IndexError, ValueError) as e:
+        LOGGER.error(
+            f"Error formatting string template: {template} with value: {str(value)}"
+        )
+        raise e
+
+
+def preprocess_fpp_format_str(format_str: str) -> str:
+    """Preprocess a FPP-style format string and convert it to Python format string
+    FPP format strings are documented https://nasa.github.io/fpp/fpp-spec.html#Format-Strings
+    For example "{x}" -> "{:x}" or "{.2f}" -> "{:.2f}"
+
+    Args:
+        format_str (str): FPP-style format string
+
+    Returns:
+        str: Python-style format string
+    """
+    pattern = r"{(\d*\.?\d*[cdxoefgCDXOEFG])}"
+    return re.sub(pattern, r"{:\1}", format_str)
+
+
+def preprocess_c_style_format_str(format_str: str) -> str:
+    """
     Function to convert C-string style to python format
     without using python interpolation
     Considered the following format for C-string:
@@ -31,20 +70,26 @@ def format_string_template(format_str, given_values):
     This function will keep the flags, width, and .precision of C-string
     template.
 
-    It will keep f, d, x, o, and e flags and remove all other types.
-    Other types will be duck-typed by python
-    interpreter.
+    It will keep f, x, o, and e flags and remove all other types.
+    Other types will be duck-typed by python interpreter.
 
     lengths will also be removed since they are not meaningful to Python interpreter.
     `See: https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting`
-
     `Regex Source: https://www.regexlib.com/REDetails.aspx?regexp_id=3363`
+
+    For example "%x" -> "{:x}" or "%.2f" -> "{:.2f}"
+
+    Args:
+        format_str (str): C-style format string
+
+    Returns:
+        str: Python-style format string
     """
 
-    def convert(match_obj, ignore_int):
+    def convert(match_obj: re.Match):
         if match_obj.group() is None:
             return match_obj
-        flags, width, precision, length, conversion_type = match_obj.groups()
+        flags, width, precision, _, conversion_type = match_obj.groups()
         format_template = ""
         if flags:
             format_template += f"{flags}"
@@ -53,66 +98,13 @@ def format_string_template(format_str, given_values):
         if precision:
             format_template += f"{precision}"
 
-        if conversion_type:
-            if any(
-                [
-                    str(conversion_type).lower() == "f",
-                    str(conversion_type).lower() == "x",
-                    str(conversion_type).lower() == "o",
-                    str(conversion_type).lower() == "e",
-                ]
-            ):
-                format_template += f"{conversion_type}"
-            elif all([not ignore_int, str(conversion_type).lower() == "d"]):
-                format_template += f"{conversion_type}"
+        if conversion_type and str(conversion_type).lower() in {"f", "x", "o", "e"}:
+            format_template += f"{conversion_type}"
 
         return "{}" if format_template == "" else "{:" + format_template + "}"
 
-    def convert_include_all(match_obj):
-        return convert(match_obj, ignore_int=False)
-
-    def convert_ignore_int(match_obj):
-        return convert(match_obj, ignore_int=True)
-
-    # Allowing single, list and tuple inputs
-    if not isinstance(given_values, (list, tuple)):
-        values = (given_values,)
-    elif isinstance(given_values, list):
-        values = tuple(given_values)
-    else:
-        values = given_values
-
-    pattern = r"(?<!%)(?:%%)*%([\-\+0\ \#])?(\d+|\*)?(\.\*|\.\d+)?([hLIw]|l{1,2}|I32|I64)?([cCdiouxXeEfgGaAnpsSZ])"
+    pattern = r"(?<!%)(?:%%)*%([\-\+0\ \#])?(\d+|\*)?(\.\*|\.\d+)?([hLIw]|l{1,2}|I32|I64)?([cCdiouxXeEfgGaAnpsSZ])"  # NOSONAR
 
     match = re.compile(pattern)
 
-    # First try to include all types
-    try:
-        formatted_str = re.sub(match, convert_include_all, format_str)
-        result = formatted_str.format(*values)
-        result = result.replace("%%", "%")
-        return result
-    except Exception:
-        msg = "Value and format string do not match. "
-        msg += " Will ignore integer flags `d` in string template. "
-        msg += f"values: {values}. "
-        msg += f"format_str: {format_str}. "
-        msg += f"given_values: {given_values}"
-        LOGGER.warning(msg)
-
-    # Second try by not including %d.
-    # This will resolve failing ENUMs with %d
-    # but will fail on other types.
-    try:
-        formatted_str = re.sub(match, convert_ignore_int, format_str)
-        result = formatted_str.format(*values)
-        result = result.replace("%%", "%")
-        return result
-    except ValueError as e:
-        msg = "Value and format string do not match. "
-        msg += f"values: {values}. "
-        msg += f"format_str: {format_str}. "
-        msg += f"given_values: {given_values}"
-        msg += f"Err Msg: {str(e)}\n"
-        LOGGER.error(msg)
-        raise ValueError
+    return re.sub(match, convert, format_str).replace("%%", "%")

fprime_gds/common/zmq_transport.py

@@ -9,6 +9,7 @@ replace the ThreadedTcpServer for several reasons as described below.
 
 @author lestarch
 """
+
 import logging
 import struct
 from typing import Tuple
@@ -24,6 +25,7 @@ from fprime_gds.common.transport import (
 
 LOGGER = logging.getLogger("transport")
 
+
 class ZmqWrapper(object):
     """Handler for ZMQ functions for use in other objects"""
 
@@ -50,7 +52,9 @@ class ZmqWrapper(object):
             sub_topic: subscription topic used to filter incoming messages
             pub_topic: publication topic supplied for remote subscription filters
         """
-        assert len(transport_url) == 2, f"Must supply a pair of URLs for ZeroMQ not '{transport_url}'"
+        assert (
+            len(transport_url) == 2
+        ), f"Must supply a pair of URLs for ZeroMQ not '{transport_url}'"
         self.pub_topic = pub_topic
         self.sub_topic = sub_topic
         self.transport_url = transport_url
@@ -78,8 +82,12 @@ class ZmqWrapper(object):
         The connection is made using self.transport_url, and as such, this must be configured before running. This is
         intended to be called on the sending thread.
         """
-        assert self.transport_url is not None and len(self.transport_url) == 2, "Must configure before connecting"
-        assert self.zmq_socket_outgoing is None, "Cannot connect outgoing multiple times"
+        assert (
+            self.transport_url is not None and len(self.transport_url) == 2
+        ), "Must configure before connecting"
+        assert (
+            self.zmq_socket_outgoing is None
+        ), "Cannot connect outgoing multiple times"
         assert self.pub_topic is not None, "Must configure sockets before connecting"
         self.zmq_socket_outgoing = self.context.socket(zmq.PUB)
         self.zmq_socket_outgoing.setsockopt(zmq.SNDHWM, 0)
@@ -93,7 +101,7 @@ class ZmqWrapper(object):
             self.zmq_socket_outgoing.connect(self.transport_url[0])
 
     def connect_incoming(self):
-        """ Sets up a ZeroMQ connection for incoming data
+        """Sets up a ZeroMQ connection for incoming data
 
         ZeroMQ allows multiple connections to a single endpoint. This only affects incoming connections as sockets must
         be created on their owning threads. This will connect the ZeroMQ topology and if self.server is set, will bind
@@ -102,8 +110,12 @@ class ZmqWrapper(object):
         The connection is made using self.transport_url, and as such, this must be configured before running. This is
         intended to be called on the receiving thread.
         """
-        assert self.transport_url is not None and len(self.transport_url) == 2, "Must configure before connecting"
-        assert self.zmq_socket_incoming is None, "Cannot connect incoming multiple times"
+        assert (
+            self.transport_url is not None and len(self.transport_url) == 2
+        ), "Must configure before connecting"
+        assert (
+            self.zmq_socket_incoming is None
+        ), "Cannot connect incoming multiple times"
         assert self.sub_topic is not None, "Must configure sockets before connecting"
         self.zmq_socket_incoming = self.context.socket(zmq.SUB)
         self.zmq_socket_incoming.setsockopt(zmq.RCVHWM, 0)
@@ -118,14 +130,16 @@ class ZmqWrapper(object):
 
     def disconnect_outgoing(self):
         """Disconnect the ZeroMQ sockets"""
-        self.zmq_socket_outgoing.close()
+        if self.zmq_socket_outgoing is not None:
+            self.zmq_socket_outgoing.close()
 
     def disconnect_incoming(self):
         """Disconnect the ZeroMQ sockets"""
-        self.zmq_socket_incoming.close()
+        if self.zmq_socket_incoming is not None:
+            self.zmq_socket_incoming.close()
 
     def terminate(self):
-        """ Terminate the ZeroMQ context"""
+        """Terminate the ZeroMQ context"""
         self.context.term()
 
     def recv(self, timeout=None):
@@ -162,11 +176,14 @@ class ZmqClient(ThreadedTransportClient):
         self.zmq = ZmqWrapper()
 
     def connect(
-        self, transport_url: Tuple[str], sub_routing: RoutingTag, pub_routing: RoutingTag
+        self,
+        transport_url: Tuple[str],
+        sub_routing: RoutingTag,
+        pub_routing: RoutingTag,
     ):
         """Connects to the ZeroMQ network"""
         self.zmq.configure(transport_url, sub_routing.value, pub_routing.value)
-        self.zmq.connect_outgoing() # Outgoing socket, for clients, exists on the current thread
+        self.zmq.connect_outgoing()  # Outgoing socket, for clients, exists on the current thread
         super().connect(transport_url, sub_routing, pub_routing)
 
     def disconnect(self):
@@ -176,16 +193,18 @@ class ZmqClient(ThreadedTransportClient):
 
     def send(self, data):
         """Send data via ZeroMQ"""
-        if data[:4] == b'ZZZZ':
+        if data[:4] == b"ZZZZ":
             data = data[4:]
-        self.zmq.send(data)  # Must strip out ZZZZ as that is a ThreadedTcpServer only property
+        self.zmq.send(
+            data
+        )  # Must strip out ZZZZ as that is a ThreadedTcpServer only property
 
     def recv(self, timeout=None):
         """Receives data from ZeroMQ"""
         return self.zmq.recv(timeout)
 
     def recv_thread(self):
-        """ Overrides the recv_thread method
+        """Overrides the recv_thread method
 
         Overrides the recv_thread method of the superclass such that the ZeroMQ socket may be created/destroyed
         before/after the main recv loop.
@@ -203,11 +222,11 @@ class ZmqGround(GroundHandler):
     to the display and processing layer(s). This effectively acts as the "FSW" side of that interface as it
     frames/deframes packets heading to that layer.
 
-    Since there is likely only one communications client to the FSW users should call make_server() after construction
+    Since there is likely only one communications client to the FSW users should instantiate with server=True
     to ensure that it binds to resources for the network. This is not forced in case of multiple FSW connections.
     """
 
-    def __init__(self, transport_url):
+    def __init__(self, transport_url, server=True):
         """Initialize this interface with the transport_url needed to connect
 
         Args:
@@ -217,6 +236,8 @@ class ZmqGround(GroundHandler):
         self.zmq = ZmqWrapper()
         self.transport_url = transport_url
         self.timeout = 10
+        if server:
+            self.zmq.make_server()
 
     def open(self):
         """Open this ground interface. Delegates to the connect method
@@ -242,10 +263,6 @@ class ZmqGround(GroundHandler):
         self.zmq.disconnect_outgoing()
         self.zmq.terminate()
 
-    def make_server(self):
-        """Makes it into a server"""
-        self.zmq.make_server()
-
     def receive_all(self):
         """Receive all available packets
 

fprime_gds/executables/apps.py

@@ -0,0 +1,150 @@
+""" fprime_gds.executables.apps: an implementation of start-up apps in fprime
+
+There are twp ways to approach start=up applications in fprime. First, is to implement a run method via a subclass of
+`GdsFunction`. This gives the implementor the ability to run anything within the run function that python offers,
+however; this comes with complexity of setting up a new thread/process/isolation to ensure that the plugin does not
+threaten the fprime-gds core functionality and processes.
+
+The second method is to inherit from `GdsApp` implementing the `get_process_invocation` function to return the necessary
+command line that will be spun into its own process.
+
+@author lestarch
+"""
+import subprocess
+from abc import ABC, abstractmethod
+from typing import List, Type
+
+from fprime_gds.plugin.definitions import gds_plugin_specification
+
+
+class GdsBaseFunction(ABC):
+    """ Base functionality for pluggable GDS start-up functions
+
+    GDS start-up functionality is pluggable. This class acts as a base for pluggable functionality supplies helpers to
+    the various start-up plugins.
+
+    Developers who intend to run in an isolated subprocess are strongly encouraged to use `GdsApp` (see below).
+    Developers who need flexibility may use GdsFunction.
+    """
+
+    @abstractmethod
+    def run(self):
+        """ Run the start-up function
+
+        Run the start-up function unconstrained by the limitations of running in a dedicated subprocess.
+
+        """
+        raise NotImplementedError()
+
+
+class GdsFunction(GdsBaseFunction, ABC):
+    """ Functionality for pluggable GDS start-up functions
+
+    GDS start-up functionality is pluggable. This class acts as a wide-open implementation of functionality via a single
+    `run` callback. Developers have complete control of the start-up functionality. However, this comes at the cost of
+    instability in that case of poorly designed functions.
+
+    Developers who intend to run in an isolated subprocess are strongly encouraged to use `GdsApp` (see below).
+
+    Plugin developers are required to implement a single function `run`, which must take care of setting up and running
+    the start-up function. Developers **must** handle the isolation of this functionality including spinning off a new
+    thread, subprocess, etc. Additionally, the developer must define the `register_gds_function_plugin` class method
+    annotated with the @gds_plugin_implementation annotation.
+
+    Standard plug-in functions (get_name, get_arguments) are available should the implementer desire these features.
+    Arguments will be supplied to the class's `__init__` function.
+    """
+
+    @classmethod
+    @gds_plugin_specification
+    def register_gds_function_plugin(cls) -> Type["GdsFunction"]:
+        """Register gds start-up functionality
+
+        Plugin hook for registering a plugin that supplies start-up functionality. This functionality will run on start-up
+        of the GDS network.
+
+        Note: users should return the class, not an instance of the class. Needed arguments for instantiation are
+        determined from class methods, solicited via the command line, and provided at construction time to the chosen
+        instantiation.
+
+        Returns:
+            GDSFunction subclass
+        """
+        raise NotImplementedError()
+
+
+class GdsApp(GdsBaseFunction):
+    """ GDS start-up process functionality
+
+    A pluggable base class used to start a new process as part of the GDS command line invocation. This allows
+    developers to add process-isolated functionality to the GDS network.
+
+    Plugin developers are required to implement the `get_process_invocation` function that returns a list of arguments
+    needed to invoke the process via python's `subprocess`. Additionally, the developer must define the
+    `register_gds_function_plugin` class method annotated with the @gds_plugin_implementation annotation.
+
+    Standard plug-in functions (get_name, get_arguments) are available should the implementer desire these features.
+    Arguments will be supplied to the class's `__init__` function.
+    """
+    def __init__(self, **arguments):
+        """ Construct the communication applications around the arguments
+
+        Command line arguments are passed in to match those returned from the `get_arguments` functions.
+
+        Args:
+            arguments: arguments from the command line
+        """
+        self.process = None
+        self.arguments = arguments
+
+    def run(self):
+        """ Run the application as an isolated process
+
+        GdsFunction objects require an implementation of the `run` command. This implementation will take the arguments
+        provided from `get_process_invocation` function and supplies them as an invocation of the isolated subprocess.
+        """
+        invocation_arguments = self.get_process_invocation()
+        self.process = subprocess.Popen(invocation_arguments)
+
+    def wait(self, timeout=None):
+        """ Wait for the app to complete then return the return code
+
+        Waits (blocking) for the process to complete. Then returns the return code of the underlying process. If timeout
+        is non-None then the process will be killed after waiting for the timeout and another wait of timeout will be
+        allowed for the killed process to exit.
+
+        Return:
+            return code of the underlying process
+        """
+        try:
+            _, _ = self.process.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            self.process.kill()
+            _, _ = self.process.wait(timeout=timeout)
+        return self.process.returncode
+
+    @abstractmethod
+    def get_process_invocation(self) -> List[str]:
+        """ Run the start-up function
+
+        Run the start-up function unconstrained by the limitations of running in a dedicated subprocess.
+
+        """
+        raise NotImplementedError()
+
+    @classmethod
+    @gds_plugin_specification
+    def register_gds_app_plugin(cls) -> Type["GdsApp"]:
+        """Register a gds start-up application
+
+        Plugin hook for registering a plugin that supplies start-up functionality. This functionality will run on start-up
+        of the GDS network isolated into a dedicated process.
+
+        Note: users should return the class, not an instance of the class. Needed arguments for instantiation are
+        determined from class methods, solicited via the command line, and provided at construction time to the chosen
+        instantiation.
+
+        Returns:
+            GdsApp subclass
+        """
+        raise NotImplementedError()