fprime-gds 3.6.2a1__py3-none-any.whl → 4.0.0a1__py3-none-any.whl

fprime_gds/plugin/definitions.py

@@ -1,4 +1,4 @@
-""" fprime_gds.plugin.definitions: definitions of plugin specifications and decorators
+"""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.
@@ -7,6 +7,8 @@ This file also defines helper classes to support the plugin system.
 
 @author lestarch
 """
+
+import inspect
 import pluggy
 from enum import Enum, auto
 from typing import Any, Dict, Tuple, Type
@@ -17,8 +19,67 @@ gds_plugin_specification = pluggy.HookspecMarker(PROJECT_NAME)
 gds_plugin_implementation = pluggy.HookimplMarker(PROJECT_NAME)
 
 
+def gds_plugin(plugin_class):
+    """Decorator: make decorated class a plugin of the plugin_class
+
+    This allows users to quickly define plugin implementations by decorating their class with the definition of the
+    plugin they are implementing. This works by searching the plugin_class for a function with the attribute
+    { PROJECT_NAME }_spec. This will be the specification function. It will then add an implementation of the
+    implementation spec to the supplied class.
+
+    It will check the following assertions:
+      1. plugin_class has a valid gds_plugin_specification
+      2. plugin_class specification is well-formed (no arguments, class method)
+      2. The decorated class is a valid subclass of plugin_class
+      3. The decorated class is non-abstract
+    """
+    assert isinstance(
+        plugin_class, type
+    ), "Must supply @gds_plugin valid plugin classes"
+    plugin_name = plugin_class.__name__
+    spec_attr = f"{ PROJECT_NAME }_spec"
+    spec_methods = inspect.getmembers(
+        plugin_class, predicate=lambda item: hasattr(item, spec_attr)
+    )
+    assert len(spec_methods) == 1, f"'{plugin_name}' is not a valid F Prime GDS plugin."
+    spec_method = spec_methods[0]
+    spec_method_name, spec_method_function = spec_method
+    assert (
+        getattr(spec_method_function, "__self__", None) == plugin_class
+    ), f"'{plugin_name}' specification invalid."
+    assert inspect.isabstract(
+        plugin_class
+    ), f"{plugin_class} is not a plugin superclass."
+
+    def decorator(decorated_class):
+        """Implementation of the decorator: check valid subclass, and add plugin method"""
+        assert isinstance(decorated_class, type), "Must use @gds_plugin on classes"
+        class_name = decorated_class.__name__
+        assert issubclass(
+            decorated_class, plugin_class
+        ), f"{class_name} is not a subclass of {plugin_name}"
+        assert not inspect.isabstract(
+            decorated_class
+        ), f"{class_name} is abstract. Plugins may not be abstract."
+
+        def return_decorated_class(cls):
+            """Function to become the plugin implementation method"""
+            assert cls == decorated_class, "Plugin system failure"
+            return decorated_class
+
+        setattr(
+            decorated_class,
+            spec_method_name,
+            classmethod(gds_plugin_implementation(return_decorated_class)),
+        )
+        return decorated_class
+
+    return decorator
+
+
 class PluginType(Enum):
-    """ Enumeration of plugin types"""
+    """Enumeration of plugin types"""
+
     ALL = auto()
     """ Plugin selection including all types of plugins """
 
@@ -30,10 +91,10 @@ class PluginType(Enum):
 
 
 class Plugin(object):
-    """ Plugin wrapper object """
+    """Plugin wrapper object"""
 
     def __init__(self, category: str, plugin_type: PluginType, plugin_class: Type[Any]):
-        """ Initialize the plugin
+        """Initialize the plugin
 
         Args:
             category: category of the plugin (i.e. register_<category>_function)
@@ -44,8 +105,12 @@ class Plugin(object):
         self.type = plugin_type
         self.plugin_class = plugin_class
 
+    def get_implementor(self):
+        """Get the implementor of this plugin"""
+        return self.plugin_class
+
     def get_name(self):
-        """ Get the name of the plugin
+        """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.
@@ -54,12 +119,13 @@ class Plugin(object):
             name of plugin
         """
         return (
-            self.plugin_class.get_name() if hasattr(self.plugin_class, "get_name")
+            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
+        """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.
@@ -67,5 +133,17 @@ class Plugin(object):
         Returns:
             argument specification for plugin
         """
-        return self.plugin_class.get_arguments() if hasattr(self.plugin_class, "get_arguments") else {}
+        return (
+            self.plugin_class.get_arguments()
+            if hasattr(self.plugin_class, "get_arguments")
+            else {}
+        )
 
+    def check_arguments(self, **kwargs):
+        """Check a plugin's arguments
+
+        Check a plugin's arguments if it defines a check method. Arguments are passed as kwargs just like the arguments are
+        passed to the constructor.
+        """
+        if hasattr(self.plugin_class, "check_arguments"):
+            self.plugin_class.check_arguments(**kwargs)

fprime_gds/plugin/system.py

@@ -1,4 +1,4 @@
-""" fprime_gds.plugin.system: implementation of plugins
+"""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()`.
@@ -8,6 +8,7 @@ using entrypoints.
 
 @author lestarch
 """
+import copy
 import os
 import importlib
 import inspect
@@ -18,46 +19,11 @@ 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
 
@@ -66,17 +32,23 @@ class InvalidCategoryException(PluginException):
     pass
 
 
+class PluginsNotLoadedException(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"
+    PLUGIN_METADATA = None
     _singleton = None
 
     def __init__(self, categories: Union[None, List] = None):
-        """ Initialize the plugin system with specific categories
+        """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.
@@ -84,30 +56,41 @@ class Plugins(object):
         Args:
             categories: None for all categories otherwise a list of categories
         """
+        self.metadata = copy.deepcopy(self.get_plugin_metadata())
         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"])
+            self.manager.add_hookspecs(self.metadata[category]["class"])
 
         # Load plugins from setuptools entrypoints and the built-in plugins (limited to category)
-        self.manager.load_setuptools_entrypoints(PROJECT_NAME)
-
+        try:
+            self.manager.load_setuptools_entrypoints(PROJECT_NAME)
+        except Exception as e:
+            LOGGER.warning("Failed to load entrypoint plugins: %s", e)
         # Load plugins from environment variable specified modules
-        for token in [token for token in os.environ.get(self.PLUGIN_ENVIRONMENT_VARIABLE, "").split(";") if token]:
+        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)
+                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"]:
+            for built_in in self.metadata[category]["built-in"]:
                 self.register_plugin(built_in)
 
     def get_plugins(self, category) -> Iterable:
@@ -133,6 +116,64 @@ class Plugins(object):
             if self.validate_selection(category, plugin_class)
         ]
 
+    def start_loading(self, category: str):
+        """Start a category loading
+
+        When loading plugins via the CLI, it is imperative to distinguish between the no loaded implementors case, and
+        the case where loading was never attempted. This sets the variable in metadata to [] to indicate the loading
+        was attempted.
+        """
+        metadata = self.metadata[category]
+        metadata["bound_classes"] = (
+            metadata["bound_classes"] if "bound_classes" in metadata else []
+        )
+
+    def add_bound_class(self, category: str, bound_class: List[object]):
+        """Add class for plugin category with constructor arguments bound
+
+        Called from the plugin cli parser, this will add a class ready for zero-argument construction to the categories'
+        list of classes. This is the plugin class with constructor arguments bound to the cli arguments that fill those
+        values. For SELECTION plugins, only a single instance is allowed. For FEATURE plugins, multiple bound classes
+        are  allowed.
+
+        Args:
+            category: category to set
+            bound_class: constructor argument bound class
+        """
+        self.start_loading(category)
+        metadata = self.metadata[category]
+        metadata["bound_classes"].append(bound_class)
+        assert (
+            metadata["type"] == PluginType.FEATURE
+            or len(metadata["bound_classes"]) == 1
+        ), f"Multiple selections for: {category}"
+
+    def get_selected_class(self, category: str) -> object:
+        """Get the selected constructor-bound class for the category"""
+        metadata = self.metadata[category]
+        assert (
+            metadata["type"] == PluginType.SELECTION
+        ), "Features allow multiple plugins"
+        try:
+            return metadata["bound_classes"][0]
+        except (KeyError, IndexError):
+            raise PluginsNotLoadedException(
+                f"Plugins not loaded for category: {category}"
+            )
+
+    def get_feature_classes(self, category: str) -> object:
+        """Get the selected instance for the category"""
+        metadata = self.metadata[category]
+        assert (
+            metadata["type"] == PluginType.FEATURE
+        ), "Selections have single instances"
+        try:
+            return metadata["bound_classes"]
+        except KeyError:
+            raise PluginsNotLoadedException(
+                f"Plugins not loaded for category: {category}"
+            )
+
     def register_plugin(self, module_or_class):
         """Register a plugin directly
 
@@ -144,27 +185,96 @@ class Plugins(object):
         self.manager.register(module_or_class)
 
     def get_categories(self):
-        """ Get plugin categories """
+        """Get plugin categories"""
         return self.categories
 
-    @staticmethod
-    def get_all_categories():
-        """ Get all plugin categories """
-        return _PLUGIN_METADATA.keys()
+    @classmethod
+    def get_all_categories(cls):
+        """Get all plugin categories"""
+        return cls.get_plugin_metadata().keys()
+
+    @classmethod
+    def get_plugin_metadata(cls, category: str = None):
+        """Get the metadata describing a given category
+
+        F Prime supports certain plugin types that break down into categories. Each category has a set of built-in
+        plugins class type, and plugin type. This function will load that metadata for the supplied category. If no
+        category is supplied then the complete metadata block is returned.
+
+        On first invocation, the method will load plugin types and construct the metadata object.
 
-    @staticmethod
-    def get_plugin_metadata(category):
-        """ Get the plugin metadata for a given plugin category """
-        return _PLUGIN_METADATA[category]
+        Warning:
+            Since the loaded plugins may use features of the plugin system, these plugins must be imported at call time
+            instead of imported at the top of the module to prevent circular imports.
+
+        Return:
+            plugin metadata definitions
+        """
+        # Load on the first time only
+        if cls.PLUGIN_METADATA is None:
+            from fprime_gds.executables.apps import GdsFunction, GdsApp
+            from fprime_gds.common.handlers import DataHandlerPlugin
+            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
+            from fprime_gds.executables.apps import CustomDataHandlers
+
+            try:
+                from fprime_gds.common.communication.adapters.uart import SerialAdapter
+            except ImportError:
+                SerialAdapter = None
+            cls.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": [CustomDataHandlers],
+                },
+                "data_handler": {
+                    "class": DataHandlerPlugin,
+                    "type": PluginType.FEATURE,
+                    "built-in": [],
+                },
+            }
+            assert cls.PLUGIN_METADATA is not None, "Failed to set plugin metadata"
+        return (
+            cls.PLUGIN_METADATA[category]
+            if category is not None
+            else cls.PLUGIN_METADATA
+        )
 
     @classmethod
     def get_category_plugin_type(cls, category):
-        """ Get the plugin type given the 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 """
+        """Get the plugin class given the category"""
         return cls.get_plugin_metadata(category)["class"]
 
     @classmethod
@@ -204,7 +314,7 @@ class Plugins(object):
 
     @classmethod
     def system(cls, categories: Union[None, List] = None) -> "Plugins":
-        """ Get plugin system singleton
+        """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
@@ -218,8 +328,11 @@ class Plugins(object):
         """
         # Singleton undefined, construct it
         if cls._singleton is None:
-            cls._singleton = cls(cls.get_all_categories() if categories is None else categories)
+            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"
+        assert (
+            categories is None or cls._singleton.categories == categories
+        ), f"Inconsistent plugin categories: {categories} vs {cls._singleton.categories}"
         return cls._singleton
-

{fprime_gds-3.6.2a1.dist-info → fprime_gds-4.0.0a1.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: fprime-gds
-Version: 3.6.2a1
+Version: 4.0.0a1
 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: 
@@ -240,10 +240,11 @@ Requires-Dist: Jinja2>=2.11.3
 Requires-Dist: openpyxl>=3.0.10
 Requires-Dist: pyserial>=3.5
 Requires-Dist: pydantic>=2.6
+Dynamic: license-file
 
 # F´ GDS
 
-**Note:** This README describes GDS internals. Refer to the [user's guide](https://nasa.github.io/fprime/UsersGuide/gds/gds-introduction.html) for instructions on how to use the GDS.
+**Note:** This README describes GDS internals. Refer to the [F´ Documentation](https://fprime.jpl.nasa.gov/latest/docs/user-manual/overview/gds-introduction/) for instructions on how to use the GDS.
 
 Issues should be reported here: [File an issue](https://github.com/nasa/fprime/issues/new/choose)
 
@@ -268,7 +269,8 @@ 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/devel/docs/UsersGuide/media/gds_layout.jpg)
+the F´ deployment.  
+![The layout of the GDS](https://raw.githubusercontent.com/nasa/fprime/refs/heads/devel/docs/img/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,
@@ -285,15 +287,11 @@ commands and registering consumers to the GDS decoders. The Standard Pipeline ca
 [here](src/fprime_gds/common/pipeline/standard.py).
 
 ### GDS Integration Test API
-The Integration Test API is a tool that provides the ability to write integration-level tests for an
-F´ deployment using the GDS. The tool provides history searches/asserts, command sending, a
-detailed test log, sub-histories and convenient access to GDS data objects. The test API comes with
-separate [documentation](https://github.com/nasa/fprime/blob/master/docs/UsersGuide/dev/testAPI/markdown/contents.md) and its own [user
-guide](https://github.com/nasa/fprime/blob/master/docs/UsersGuide/dev/testAPI/user_guide.md) and is built on top of the Standard Pipeline.
+The Integration Test API is a tool that provides the ability to write integration-level tests for an F´ deployment using the GDS. The tool provides history searches/asserts, command sending, a detailed test log, sub-histories and convenient access to GDS data objects. The test API comes with its own [user guide](https://fprime.jpl.nasa.gov/latest/docs/user-manual/gds/gds-test-api-guide/) and is built on top of the Standard Pipeline.
 
 ## GDS GUI Usage
 
-A guide for how to use the GDS is available in the [fprime documentation](https://nasa.github.io/fprime/UsersGuide/gds/gds-introduction.html)
+A guide for how to use the GDS is available in the [F Prime documentation](https://fprime.jpl.nasa.gov/latest/docs/user-manual/overview/gds-introduction)
 
 ## Classes
 The GDS back end is composed of several different data processing units. For 
@@ -316,8 +314,15 @@ that descriptor. Descriptor types include events, channels, packets, etc (a full
 enumeration can be found in (src/utils/data_desc_type.py). The binary data that 
 the descriptor receives should be of the form:
 
-| Length (4 bytes) | Type Descriptor (4 bytes) | Message Data |
-| ---------------- | ------------------------- | ------------ |
+```mermaid
+---
+title: "Binary format received by Distributors"
+---
+packet-beta
+  0-31: "Length [4 bytes]"
+  32-63: "Type Descriptor [4 bytes]"
+  64-95: "Message Data [variable length]"
+```
 
 The distributor should then pass only the message data along to the decoders. 
 
@@ -433,10 +438,3 @@ pip install doxypypy
 
 Next, make `docs/py_filter` available in your system path however you see fit.
 Now you can run `doxygen Doxyfile` in the root directory to generate documentation in `docs/doxy/index.html`
-
-## Notes
- - Currently, the models/common directory has command.py, event.py, and
-   channel.py. These files must be present in order for the python dictionaries
-   to be properly imported. However, they are empty and not used in the GDS. 
-   When we switch fully to XML dictionaries, these can go away. 
-