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

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.4a1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fprime-gds
-Version: 3.4.3
+Version: 3.4.4a1
 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: 

{fprime_gds-3.4.3.dist-info → fprime_gds-3.4.4a1.dist-info}/RECORD

@@ -4,16 +4,16 @@ fprime_gds/version.py,sha256=dlUlfOKTsGaqz_L7TjhCVC-Vanx5cK67kdZlqcHCM8M,395
 fprime_gds/common/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 fprime_gds/common/handlers.py,sha256=t2-st-C3Z486kfcu2cpf-wHJQmpaaHQYj1dyXJEMmSU,2632
 fprime_gds/common/transport.py,sha256=y9HiupzsCRF5_JFMMtMWQxcEYPvPuxX1P_oBeqosKR0,10565
-fprime_gds/common/zmq_transport.py,sha256=TyYc--9rzjCSc8FxNran-i9CWK2pV-07T6NO7z2AzjY,12162
+fprime_gds/common/zmq_transport.py,sha256=Wb9IFFyp89S6y2okYavmVygOSqg7IJMbBoyBOR4iIrg,12291
 fprime_gds/common/communication/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-fprime_gds/common/communication/checksum.py,sha256=Oz2E1zM2xc-wIFp9ruYWmWrQmHhCQFmdGZhW2oBdSRU,789
-fprime_gds/common/communication/framing.py,sha256=oKZf4aptvgskh2R-GxzrzYRIXzLY9Zx6i8383cHyRcU,11081
+fprime_gds/common/communication/checksum.py,sha256=f6W0Tr68U-XGnFmysMqsFzoGYZVE8clKf-VIJja_1YM,741
+fprime_gds/common/communication/framing.py,sha256=TPpVn5JfGJxdc9BuKJzm5LXo6OQKtkSqX695UdN-Ezk,12915
 fprime_gds/common/communication/ground.py,sha256=9SD3AoyHA43yNE8UYkWnu5nEJt1PgyB3sU3QLDc4eDY,3619
 fprime_gds/common/communication/updown.py,sha256=UhfCIIA2eM5g2FsIhOGJJH6HzHurUPgcKIJ5fsLb2lE,9888
 fprime_gds/common/communication/adapters/__init__.py,sha256=ivGtzUTqhBYuve5mhN9VOHITwgZjNMVv7sxuac2Ll3c,470
-fprime_gds/common/communication/adapters/base.py,sha256=BqIjt6jzjn2ViqDHLKAV7Tez7OburnUahbu4I2CU3hI,4782
-fprime_gds/common/communication/adapters/ip.py,sha256=h1WJSq0GZ2pngn-Uzu3vixJzsPS-xai0ufSJSYoeKZU,16644
-fprime_gds/common/communication/adapters/uart.py,sha256=ArOGmo79JD2jWN8J7vb4pZcfUXxMJpa2urt1hY2Q8OQ,6373
+fprime_gds/common/communication/adapters/base.py,sha256=i3mf4HC-4tuf4mNkhdXCKlngRhODyTriia2pw6XBoSQ,3393
+fprime_gds/common/communication/adapters/ip.py,sha256=vCDclpsb3rVRXSxKqdt9UfkM2M6oCxnsKdzbzhMc0kM,17074
+fprime_gds/common/communication/adapters/uart.py,sha256=6SrN42ShVjwNubFg-1YrO09o1uJtu1rFqeMpLDNWlW4,6647
 fprime_gds/common/controllers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 fprime_gds/common/data_types/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 fprime_gds/common/data_types/ch_data.py,sha256=RP9zSyzNcH0nJ3MYyW_IATnmnHYZ6d0KmoJUJantdBI,6111
@@ -102,12 +102,13 @@ fprime_gds/common/utils/data_desc_type.py,sha256=9GV8hV5q1dDxdfF-1-Wty5MBrFd94Eb
 fprime_gds/common/utils/event_severity.py,sha256=7qPXHrDaM_REJ7sKBUEJTZIE0D4qVnVajsPDUuHg7sI,300
 fprime_gds/common/utils/string_util.py,sha256=jqut5Dd0EjvTHMci1mvs_8KQ1Nq-38xZofeaaSoiJEY,3985
 fprime_gds/executables/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-fprime_gds/executables/cli.py,sha256=F4qkckoYCoGlh5T_WByOj6CDI3wm_nBM1K57wzkXmtM,31127
-fprime_gds/executables/comm.py,sha256=86CO8eczu5y2lsdPnPPFtK1pEUVLrSyU9smC09bON-Q,5382
+fprime_gds/executables/apps.py,sha256=h2acqdOyMgv77IMEQUc41QcwAZ-_DToX6sZplCk17Zg,6543
+fprime_gds/executables/cli.py,sha256=bitIny2JYApMVuu3G4adnxB9iI-pieDaXAWJjNcHcLo,36942
+fprime_gds/executables/comm.py,sha256=KMoAtcUdE_KOFg4DynHCCCc3rfIiedjexx_FP6oN77s,5259
 fprime_gds/executables/fprime_cli.py,sha256=GvvuUQuoDGBrqQB867bDjUR3Kn5yPUckAY2rdfTa8jo,12432
-fprime_gds/executables/run_deployment.py,sha256=4M5646tH-LdjEgQGwAIJ3mf10pfivHlDBPrUwhLkJWI,6157
+fprime_gds/executables/run_deployment.py,sha256=01tI0JVONRkKaPPdfJS0Qt1mWm_7Wgf3N9iknozXmYc,7043
 fprime_gds/executables/tcpserver.py,sha256=KspVpu5YIuiWKOk5E6UDMKvqXYrRB1j9aX8CkMxysfw,17555
-fprime_gds/executables/utils.py,sha256=CTw2gMO3vguqra8V8AEJodY6zcX18zO4AyA-EKwThmM,7195
+fprime_gds/executables/utils.py,sha256=cBCFOpQthjxohWZmsdAQL1Y_lFYw73SQ-ANDjUoe33w,7221
 fprime_gds/flask/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 fprime_gds/flask/app.py,sha256=kJDCziri_BwZWKUszkR7u3RaNG_FWRzDkdCPsVDAtYM,6720
 fprime_gds/flask/channels.py,sha256=sOeL-UmWPh2hqYvqj81STpABLlPcjdPgkRwjd3Qx77k,735
@@ -218,10 +219,13 @@ fprime_gds/flask/static/third-party/webfonts/fa-solid-900.svg,sha256=lnTrG9VQRxe
 fprime_gds/flask/static/third-party/webfonts/fa-solid-900.ttf,sha256=r2OXUD_O-9YTl2whrVweNymMGLvgfQltsDzNOvbgW6g,202744
 fprime_gds/flask/static/third-party/webfonts/fa-solid-900.woff,sha256=P200iM9lN09vZ2wxU0CwrCvoMr1VJAyAlEjjbvm5YyY,101648
 fprime_gds/flask/static/third-party/webfonts/fa-solid-900.woff2,sha256=mDS4KtJuKjdYPSJnahLdLrD-fIA1aiEU0NsaqLOJlTc,78268
-fprime_gds-3.4.3.dist-info/LICENSE.txt,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-fprime_gds-3.4.3.dist-info/METADATA,sha256=SWlwzO_qggPMJK6biST8q8Ko4cOKm9MWLwUlKI0a_FA,24753
-fprime_gds-3.4.3.dist-info/NOTICE.txt,sha256=vXjA_xRcQhd83Vfk5D_vXg5kOjnnXvLuMi5vFKDEVmg,1612
-fprime_gds-3.4.3.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
-fprime_gds-3.4.3.dist-info/entry_points.txt,sha256=UisSXL905z4YEjwd7c-I2o6ZKmOw1xDDdO1mN0VPu6c,271
-fprime_gds-3.4.3.dist-info/top_level.txt,sha256=6vzFLIX6ANfavKaXFHDMSLFtS94a6FaAsIWhjgYuSNE,27
-fprime_gds-3.4.3.dist-info/RECORD,,
+fprime_gds/plugin/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fprime_gds/plugin/definitions.py,sha256=5rHGSOrr62qRNVfX9bZIo4HDAKG62lKteNum9G40y3g,2347
+fprime_gds/plugin/system.py,sha256=uWd6DVW90Re0FoNMPNCx0cXXTJUdpgAAO0mtakzRNgk,8564
+fprime_gds-3.4.4a1.dist-info/LICENSE.txt,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+fprime_gds-3.4.4a1.dist-info/METADATA,sha256=TiKl7YCs8sVBbCDBfQm6EK67tFvTtfH3f_hl3ewZ-tY,24755
+fprime_gds-3.4.4a1.dist-info/NOTICE.txt,sha256=vXjA_xRcQhd83Vfk5D_vXg5kOjnnXvLuMi5vFKDEVmg,1612
+fprime_gds-3.4.4a1.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
+fprime_gds-3.4.4a1.dist-info/entry_points.txt,sha256=UisSXL905z4YEjwd7c-I2o6ZKmOw1xDDdO1mN0VPu6c,271
+fprime_gds-3.4.4a1.dist-info/top_level.txt,sha256=6vzFLIX6ANfavKaXFHDMSLFtS94a6FaAsIWhjgYuSNE,27
+fprime_gds-3.4.4a1.dist-info/RECORD,,

{fprime_gds-3.4.3.dist-info → fprime_gds-3.4.4a1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.42.0)
+Generator: bdist_wheel (0.43.0)
 Root-Is-Purelib: true
 Tag: py3-none-any