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

fprime_gds/executables/run_deployment.py

@@ -13,6 +13,7 @@ from fprime_gds.executables.cli import (
     GdsParser,
     ParserBase,
     StandardPipelineParser,
+    PluginArgumentParser,
 )
 from fprime_gds.executables.utils import AppWrapperException, run_wrapped_application
 
@@ -20,14 +21,20 @@ BASE_MODULE_ARGUMENTS = [sys.executable, "-u", "-m"]
 
 
 def parse_args():
-    """ Parse command line arguments
+    """Parse command line arguments
     Gets an argument parsers to read the command line and process the arguments. Return
     the arguments in their namespace.
 
     :return: parsed argument namespace
     """
     # Get custom handlers for all executables we are running
-    arg_handlers = [StandardPipelineParser, GdsParser, BinaryDeployment, CommParser]
+    arg_handlers = [
+        StandardPipelineParser,
+        GdsParser,
+        BinaryDeployment,
+        CommParser,
+        PluginArgumentParser,
+    ]
     # Parse the arguments, and refine through all handlers
     args, parser = ParserBase.parse_args(arg_handlers, "Run F prime deployment and GDS")
     return args
@@ -63,7 +70,7 @@ def launch_process(cmd, logfile=None, name=None, env=None, launch_time=5):
 
 
 def launch_tts(parsed_args):
-    """ Launch the ThreadedTcpServer middleware application
+    """Launch the ThreadedTcpServer middleware application
 
 
     Args:
@@ -85,7 +92,7 @@ def launch_tts(parsed_args):
 
 
 def launch_html(parsed_args):
-    """ Launch the Flask application
+    """Launch the Flask application
 
     Args:
         parsed_args: parsed argument namespace
@@ -112,14 +119,18 @@ def launch_html(parsed_args):
         str(parsed_args.gui_port),
     ]
     ret = launch_process(gse_args, name="HTML GUI", env=flask_env, launch_time=2)
+    ui_url = f"http://{str(parsed_args.gui_addr)}:{str(parsed_args.gui_port)}/"
+    print(f"[INFO] Launched UI at: {ui_url}")
     webbrowser.open(
-        f"http://{str(parsed_args.gui_addr)}:{str(parsed_args.gui_port)}/", new=0, autoraise=True
+        ui_url,
+        new=0,
+        autoraise=True,
     )
     return ret
 
 
 def launch_app(parsed_args):
-    """ Launch the raw application
+    """Launch the raw application
 
     Args:
         parsed_args: parsed argument namespace
@@ -128,14 +139,20 @@ def launch_app(parsed_args):
     """
     app_path = parsed_args.app
     logfile = os.path.join(parsed_args.logs, f"{app_path.name}.log")
-    app_cmd = [app_path.absolute(), "-p", str(parsed_args.port), "-a", parsed_args.address]
+    app_cmd = [
+        app_path.absolute(),
+        "-p",
+        str(parsed_args.port),
+        "-a",
+        parsed_args.address,
+    ]
     return launch_process(
         app_cmd, name=f"{app_path.name} Application", logfile=logfile, launch_time=1
     )
 
 
 def launch_comm(parsed_args):
-    """ Launch the communication adapter process
+    """Launch the communication adapter process
 
     Args:
         parsed_args: parsed argument namespace
@@ -143,9 +160,27 @@ def launch_comm(parsed_args):
         launched process
     """
     arguments = CommParser().reproduce_cli_args(parsed_args)
-    arguments = arguments + ["--log-directly"] if "--log-directly" not in arguments else arguments
+    arguments = (
+        arguments + ["--log-directly"]
+        if "--log-directly" not in arguments
+        else arguments
+    )
     app_cmd = BASE_MODULE_ARGUMENTS + ["fprime_gds.executables.comm"] + arguments
-    return launch_process(app_cmd, name=f'comm[{parsed_args.adapter}] Application', launch_time=1)
+    return launch_process(
+        app_cmd,
+        name=f"comm[{parsed_args.communication_selection}] Application",
+        launch_time=1,
+    )
+
+
+def launch_plugin(plugin_class_instance):
+    """ Launch a plugin instance """
+    plugin_name = getattr(plugin_class_instance, "get_name", lambda: cls.__name__)()
+    return launch_process(
+        plugin_class_instance.get_process_invocation(),
+        name=f"{ plugin_name } Plugin App",
+        launch_time=1,
+    )
 
 
 def main():
@@ -155,20 +190,23 @@ def main():
     parsed_args = parse_args()
     launchers = []
 
-    # Launch a gui, if specified
+    # Launch middleware layer if not using ZMQ
     if not parsed_args.zmq:
         launchers.append(launch_tts)
 
     # Check if we are running with communications
-    if parsed_args.adapter != "none":
+    if parsed_args.communication_selection != "none":
         launchers.append(launch_comm)
 
     # Add app, if possible
     if parsed_args.app:
-        if parsed_args.adapter == "ip":
+        if parsed_args.communication_selection == "ip":
             launchers.append(launch_app)
         else:
-            print("[WARNING] App cannot be auto-launched without IP adapter", file=sys.stderr)
+            print(
+                "[WARNING] App cannot be auto-launched without IP adapter",
+                file=sys.stderr,
+            )
 
     # Launch the desired GUI package
     if parsed_args.gui == "html":
@@ -177,6 +215,9 @@ def main():
     # Launch launchers and wait for the last app to finish
     try:
         procs = [launcher(parsed_args) for launcher in launchers]
+        _ = [launch_plugin(cls) for cls in  parsed_args.gds_app_enabled_instances]
+        _ = [instance.run() for instance in parsed_args.gds_function_enabled_instances]
+
         print("[INFO] F prime is now running. CTRL-C to shutdown all components.")
         procs[-1].wait()
     except KeyboardInterrupt:

fprime_gds/executables/utils.py

@@ -3,6 +3,7 @@ fprime_gds.executables.utils:
 
 Utility functions to enable the executables package to function seamlessly.
 """
+
 import atexit
 import signal
 import subprocess
@@ -118,14 +119,15 @@ def run_wrapped_application(arguments, logfile=None, env=None, launch_time=None)
         if launch_time is not None:
             time.sleep(launch_time)
             child.poll()
-            if child.returncode is not None:
+            if child.returncode is not None and child.returncode != 0:
                 raise ProcessNotStableException(
                     arguments[0], child.returncode, launch_time
                 )
         return child
     except Exception as exc:
-        msg = f"Failed to run application: {' '.join(arguments)}. Error: {exc}"
-        raise AppWrapperException(msg)
+        argument_strings = [str(argument) for argument in arguments]
+        message = f"Failed to run application: {' '.join(argument_strings)}. Error: {exc}"
+        raise AppWrapperException(message)
 
 
 def find_settings(path: Path) -> Path:
@@ -147,7 +149,7 @@ def get_artifacts_root() -> Path:
     except FprimeLocationUnknownException:
         print(
             "[ERROR] Not in fprime project and no deployment path provided, unable to find dictionary and/or app",
-            file=sys.stderr
+            file=sys.stderr,
         )
         sys.exit(-1)
     except FprimeSettingsException as e:
@@ -177,7 +179,7 @@ def find_app(root: Path) -> Path:
     if len(files) > 1:
         print(
             f"[ERROR] Multiple app candidates in binary location {bin_dir}. Specify app manually with --app.",
-            file=sys.stderr
+            file=sys.stderr,
         )
         sys.exit(-1)
 
@@ -191,21 +193,31 @@ def find_dict(root: Path) -> Path:
         print(f"[ERROR] dictionary location {dict_dir} does not exist", file=sys.stderr)
         sys.exit(-1)
 
-    files = [
+    xml_dicts = [
         child
         for child in dict_dir.iterdir()
         if child.is_file() and child.name.endswith("Dictionary.xml")
     ]
+    json_dicts = [
+        child
+        for child in dict_dir.iterdir()
+        if child.is_file() and child.name.endswith("Dictionary.json")
+    ]
+    # Select json dictionary if available, otherwise use xml dictionary
+    dicts = json_dicts if json_dicts else xml_dicts
 
-    if not files:
-        print(f"[ERROR] No xml dictionary found in dictionary location {dict_dir}", file=sys.stderr)
+    if not dicts:
+        print(
+            f"[ERROR] No dictionary found in dictionary location {dict_dir}",
+            file=sys.stderr,
+        )
         sys.exit(-1)
 
-    if len(files) > 1:
+    if len(dicts) > 1:
         print(
-            f"[ERROR] Multiple xml dictionaries found in dictionary location {dict_dir}. Specify dictionary manually with --dictionary.",
-            file=sys.stderr
+            f"[ERROR] Multiple dictionaries of same type found in dictionary location {dict_dir}. Specify dictionary manually with --dictionary.",
+            file=sys.stderr,
         )
         sys.exit(-1)
 
-    return files[0]
+    return dicts[0]

fprime_gds/flask/sequence.py

@@ -73,7 +73,7 @@ class SequenceCompiler(flask_restful.Resource):
                 403,
                 message=f"{key} is invalid command key. Supply 0xfeedcafe to run command.",
             )
-        elif not re.match(".*\.seq", name) or Path(name).name != name:
+        elif not re.match(".*\\.seq", name) or Path(name).name != name:
             flask_restful.abort(
                 403,
                 message={"error": "Supply filename with .seq suffix", "type": "error"},

fprime_gds/flask/static/addons/commanding/command-input.js

@@ -83,7 +83,8 @@ Vue.component("command-input", {
         this.$root.$refs.command_input = this;
     },
     data: function() {
-        let selected = command_assignment_helper(null, [], "CMD_NO_OP");
+        // Select CMD_NO_OP by default if it exists, otherwise select the first command
+        let selected = command_assignment_helper("cmdDisp.CMD_NO_OP", [], "CMD_NO_OP");
         selected = (selected != null)? selected : Object.values(_datastore.commands)[0];
         return {
             "commands": _datastore.commands,
@@ -216,7 +217,7 @@ Vue.component("command-input", {
                  * @return {number} -1 or 1
                  */
                 function(obj1, obj2) {
-                    if (obj1.full_name <= obj2.full_name) {
+                    if (obj1.full_name.toLowerCase() <= obj2.full_name.toLowerCase()) {
                         return -1;
                     }
                     return 1;

fprime_gds/plugin/definitions.py

@@ -0,0 +1,71 @@
+""" fprime_gds.plugin.definitions: definitions of plugin specifications and decorators
+
+In order to define a plugin, an implementation decorator is used. Users can import `gds_plugin_implementation` from this
+file to decorate functions that implement plugins.
+
+This file also defines helper classes to support the plugin system.
+
+@author lestarch
+"""
+import pluggy
+from enum import Enum, auto
+from typing import Any, Dict, Tuple, Type
+
+PROJECT_NAME = "fprime_gds"
+
+gds_plugin_specification = pluggy.HookspecMarker(PROJECT_NAME)
+gds_plugin_implementation = pluggy.HookimplMarker(PROJECT_NAME)
+
+
+class PluginType(Enum):
+    """ Enumeration of plugin types"""
+    ALL = auto()
+    """ Plugin selection including all types of plugins """
+
+    SELECTION = auto()
+    """ Plugin that provides a selection between implementations """
+
+    FEATURE = auto()
+    """ Plugin that provides a feature """
+
+
+class Plugin(object):
+    """ Plugin wrapper object """
+
+    def __init__(self, category: str, plugin_type: PluginType, plugin_class: Type[Any]):
+        """ Initialize the plugin
+
+        Args:
+            category: category of the plugin (i.e. register_<category>_function)
+            plugin_type: type of plugin
+            plugin_class: implementation class of the plugin
+        """
+        self.category = category
+        self.type = plugin_type
+        self.plugin_class = plugin_class
+
+    def get_name(self):
+        """ Get the name of the plugin
+
+        Plugin names are derived from the `get_name` class method of the plugin's implementation class. When not defined
+        that name is derived from the plugin's implementation class __name__ property instead.
+
+        Returns:
+            name of plugin
+        """
+        return (
+            self.plugin_class.get_name() if hasattr(self.plugin_class, "get_name")
+            else self.plugin_class.__name__
+        )
+
+    def get_arguments(self) -> Dict[Tuple[str, ...], Dict[str, Any]]:
+        """ Get arguments needed by plugin
+
+        Plugin argument are derived from the `get_arguments` class method of the plugin's implementation class. When not
+        defined an empty dictionary is returned.
+
+        Returns:
+            argument specification for plugin
+        """
+        return self.plugin_class.get_arguments() if hasattr(self.plugin_class, "get_arguments") else {}
+

fprime_gds/plugin/system.py

@@ -0,0 +1,225 @@
+""" fprime_gds.plugin.system: implementation of plugins
+
+This file contains the implementation and registration of plugins for fprime_gds. Primarily, it defines the Plugins
+class that handles plugins. Users can acquire the Plugin singleton with `Plugin.system()`.
+
+This file also imports and registers plugin implementations built-into fprime-gds. These plugins are not registered
+using entrypoints.
+
+@author lestarch
+"""
+import os
+import importlib
+import inspect
+import logging
+from typing import Iterable, List, Union
+
+import pluggy
+
+from fprime_gds.plugin.definitions import Plugin, PluginType, PROJECT_NAME
+
+# For automatic validation of plugins, each plugin class type must be imported here
+from fprime_gds.executables.apps import GdsFunction, GdsApp
+from fprime_gds.common.communication.framing import FramerDeframer, FpFramerDeframer
+from fprime_gds.common.communication.adapters.base import BaseAdapter, NoneAdapter
+from fprime_gds.common.communication.adapters.ip import IpAdapter
+
+try:
+    from fprime_gds.common.communication.adapters.uart import SerialAdapter
+except ImportError:
+    SerialAdapter = None
+
+# Handy constants
+LOGGER = logging.getLogger(__name__)
+
+
+# Metadata regarding each plugin:
+_PLUGIN_METADATA = {
+    "framing": {
+        "class": FramerDeframer,
+        "type": PluginType.SELECTION,
+        "built-in": [FpFramerDeframer]
+    },
+    "communication": {
+        "class": BaseAdapter,
+        "type": PluginType.SELECTION,
+        "built-in": [adapter for adapter in [NoneAdapter, IpAdapter, SerialAdapter] if adapter is not None]
+    },
+    "gds_function": {
+        "class": GdsFunction,
+        "type": PluginType.FEATURE,
+        "built-in": []
+    },
+    "gds_app": {
+        "class": GdsApp,
+        "type": PluginType.FEATURE,
+        "built-in": []
+    }
+}
+
+
+class PluginException(Exception):
+    pass
+
+
+class InvalidCategoryException(PluginException):
+    pass
+
+
+class Plugins(object):
+    """GDS plugin system providing a plugin Singleton for use across the GDS
+
+    GDS plugins are broken into categories (e.g. framing) that represent the key features users can adjust. Each GDS
+    application will support and load the plugins for a given category.
+    """
+    PLUGIN_ENVIRONMENT_VARIABLE = "FPRIME_GDS_EXTRA_PLUGINS"
+    _singleton = None
+
+    def __init__(self, categories: Union[None, List] = None):
+        """ Initialize the plugin system with specific categories
+
+        Initialize the plugin system with support for the supplied categories. Only plugins for the specified categories
+        will be loaded for use. Other plugins will not be available for use.
+
+        Args:
+            categories: None for all categories otherwise a list of categories
+        """
+        categories = self.get_all_categories() if categories is None else categories
+        self.categories = categories
+        self.manager = pluggy.PluginManager(PROJECT_NAME)
+
+        # Load hook specifications from only the configured categories
+        for category in categories:
+            self.manager.add_hookspecs(_PLUGIN_METADATA[category]["class"])
+
+        # Load plugins from setuptools entrypoints and the built-in plugins (limited to category)
+        self.manager.load_setuptools_entrypoints(PROJECT_NAME)
+
+        # Load plugins from environment variable specified modules
+        for token in [token for token in os.environ.get(self.PLUGIN_ENVIRONMENT_VARIABLE, "").split(";") if token]:
+            module, class_token = token.split(":")
+            try:
+                imported_module = importlib.import_module(module)
+                module_class = module if class_token == "" else getattr(imported_module, class_token, imported_module)
+                self.register_plugin(module_class)
+            except ImportError as imp:
+                LOGGER.debug("Failed to load %s.%s as plugin", module, class_token)
+
+        # Load built-in plugins
+        for category in categories:
+            for built_in in _PLUGIN_METADATA[category]["built-in"]:
+                self.register_plugin(built_in)
+
+    def get_plugins(self, category) -> Iterable:
+        """Get available plugins for the given category
+
+        Gets all plugin implementors of "category" by looking for register_<category>_plugin implementors. If such a
+        function does not exist then this results in an exception.
+
+        Args:
+            category: category of the plugin requested
+
+        Return:
+            validated list of plugin implementor classes
+        """
+        try:
+            plugin_classes = getattr(self.manager.hook, f"register_{category}_plugin")()
+        except KeyError as error:
+            raise InvalidCategoryException(f"Invalid plugin category: {error}")
+
+        return [
+            Plugin(category, self.get_category_plugin_type(category), plugin_class)
+            for plugin_class in plugin_classes
+            if self.validate_selection(category, plugin_class)
+        ]
+
+    def register_plugin(self, module_or_class):
+        """Register a plugin directly
+
+        Allows local registration of plugin implementations that are shipped as part of the GDS package.
+
+        Args:
+            module_or_class: module or class that has plugin implementations
+        """
+        self.manager.register(module_or_class)
+
+    def get_categories(self):
+        """ Get plugin categories """
+        return self.categories
+
+    @staticmethod
+    def get_all_categories():
+        """ Get all plugin categories """
+        return _PLUGIN_METADATA.keys()
+
+    @staticmethod
+    def get_plugin_metadata(category):
+        """ Get the plugin metadata for a given plugin category """
+        return _PLUGIN_METADATA[category]
+
+    @classmethod
+    def get_category_plugin_type(cls, category):
+        """ Get the plugin type given the category """
+        return cls.get_plugin_metadata(category)["type"]
+
+    @classmethod
+    def get_category_specification_class(cls, category):
+        """ Get the plugin class given the category """
+        return cls.get_plugin_metadata(category)["class"]
+
+    @classmethod
+    def validate_selection(cls, category, result):
+        """Validate the result of plugin hook
+
+        Validates the result of a plugin hook call to ensure the result meets the expected properties for plugins of the
+        given category. Primarily this ensures that this plugin returns a concrete subclass of the expected type.
+
+        Args:
+            category: category of plugin used
+            result: result from the plugin hook call
+        Return:
+            True when the plugin passes validation, False otherwise
+        """
+        # Typing library not intended for introspection at runtime, thus we maintain a map of plugin specification
+        # functions to the types expected as a return value. When this is not found, plugins may continue without
+        # automatic validation.
+        try:
+            expected_class = cls.get_category_specification_class(category)
+            # Validate the result
+            if not issubclass(result, expected_class):
+                LOGGER.warning(
+                    f"{result.__name__} is not a subclass of {expected_class.__name__}. Not registering."
+                )
+                return False
+            elif inspect.isabstract(result):
+                LOGGER.warning(
+                    f"{result.__name__} is an abstract class. Not registering."
+                )
+                return False
+        except KeyError:
+            LOGGER.warning(
+                f"Plugin not registered for validation. Continuing without validation."
+            )
+        return True
+
+    @classmethod
+    def system(cls, categories: Union[None, List] = None) -> "Plugins":
+        """ Get plugin system singleton
+
+        Constructs the plugin system singleton (when it has yet to be constructed) then returns the singleton. The
+        singleton will support specific categories and further requests for a singleton will cause an assertion error
+        unless the categories match or is None.
+
+        Args:
+            categories: a list of categories to support or None to use the existing categories
+
+        Returns:
+            plugin system
+        """
+        # Singleton undefined, construct it
+        if cls._singleton is None:
+            cls._singleton = cls(cls.get_all_categories() if categories is None else categories)
+        # Ensure categories was unspecified or matches the singleton
+        assert categories is None or cls._singleton.categories == categories, "Inconsistent plugin categories"
+        return cls._singleton
+

{fprime_gds-3.4.3.dist-info → fprime_gds-3.4.4a2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fprime-gds
-Version: 3.4.3
+Version: 3.4.4a2
 Summary: F Prime Flight Software Ground Data System layer
 Author-email: Michael Starch <Michael.D.Starch@jpl.nasa.gov>, Thomas Boyer-Chammard <Thomas.Boyer.Chammard@jpl.nasa.gov>
 License: 
@@ -239,6 +239,7 @@ Requires-Dist: argcomplete >=1.12.3
 Requires-Dist: Jinja2 >=2.11.3
 Requires-Dist: openpyxl >=3.0.10
 Requires-Dist: pyserial >=3.5
+Requires-Dist: pydantic >=2.6
 
 # F´ GDS
 
@@ -267,7 +268,7 @@ output data type included. Command data objects are created in the command panel
 the command encoder registered to that panel. Encoders take a data object and turn it into binary
 data that can be sent to the F´ deployment. The binary data is then passed to the TCP client
 which is registered to the encoder. Finally, the TCP client send the data back to the TCP server and
-the F´ deployment. ![The layout of the GDS](https://github.com/nasa/fprime/blob/master/docs/UsersGuide/media/gds_layout.jpg)
+the F´ deployment. ![The layout of the GDS](https://github.com/nasa/fprime/blob/devel/docs/UsersGuide/media/gds_layout.jpg)
 
 All of these objects are created and registered to other objects when the GDS
 is initialized. Thus, all of the structure of the GDS is created in one place,