Implement a basic plugin system

Author: cburgdorf

trinity/extensibility/__init__.py

@@ -0,0 +1,11 @@
+from trinity.extensibility.events import (  # noqa: F401
+    BaseEvent
+)
+from trinity.extensibility.plugin import (  # noqa: F401
+    BasePlugin,
+    DebugPlugin,
+    PluginContext,
+)
+from trinity.extensibility.plugin_manager import (  # noqa: F401
+    PluginManager,
+)

trinity/extensibility/events.py

@@ -0,0 +1,55 @@
+from typing import (
+    Any,
+    Type,
+    TYPE_CHECKING,
+)
+from argparse import (
+    Namespace,
+)
+
+from trinity.config import (
+    ChainConfig,
+)
+
+
+if TYPE_CHECKING:
+    from trinity.extensibility import (  # noqa: F401
+        BasePlugin,
+    )
+
+
+class BaseEvent:
+    """
+    The base class for all plugin events. Plugin events can be broadcasted for all different
+    kind of reasons. Plugins can act based on these events and consume the events even before
+    the plugin is started, giving plugins the chance to start based on an event or a series of
+    events. The startup of Trinity itself can be an event as well as the start of a plugin itself
+    which, for instance, gives other plugins the chance to start based on these previous events.
+    """
+    pass
+
+
+class TrinityStartupEvent(BaseEvent):
+    """
+    Broadcasted when Trinity is starting.
+    """
+    def __init__(self, args: Namespace, chain_config: ChainConfig) -> None:
+        self.args = args
+        self.chain_config = chain_config
+
+
+class PluginStartedEvent(BaseEvent):
+    """
+    Broadcasted when a plugin was started
+    """
+    def __init__(self, plugin: 'BasePlugin') -> None:
+        self.plugin = plugin
+
+
+class ResourceAvailableEvent(BaseEvent):
+    """
+    Broadcasted when a resource becomes available
+    """
+    def __init__(self, resource: Any, resource_type: Type[Any]) -> None:
+        self.resource = resource
+        self.resource_type = resource_type

trinity/extensibility/plugin.py

@@ -0,0 +1,104 @@
+from abc import (
+    ABC,
+    abstractmethod
+)
+from argparse import (
+    ArgumentParser
+)
+import logging
+from typing import (
+    Any
+)
+
+from trinity.extensibility.events import (
+    BaseEvent
+)
+
+# TODO: we spec this out later
+PluginContext = Any
+
+
+class BasePlugin(ABC):
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """
+        Describe the name of the plugin
+        """
+        raise NotImplementedError(
+            "Must be implemented by subclasses"
+        )
+
+    @property
+    def logger(self) -> logging.Logger:
+        return logging.getLogger('trinity.extensibility.plugin.BasePlugin#{0}'.format(self.name))
+
+    @abstractmethod
+    def configure_parser(self, arg_parser: ArgumentParser) -> None:
+        """
+        Called at startup, giving the plugin a chance to amend the Trinity CLI argument parser
+        """
+        raise NotImplementedError(
+            "Must be implemented by subclasses"
+        )
+
+    @abstractmethod
+    def handle_event(self, activation_event: BaseEvent) -> None:
+        """
+        Notify the plugin about an event, giving it the chance to do internal accounting right
+        before :meth:`~trinity.extensibility.plugin.BasePlugin.should_start` is called
+        """
+
+        raise NotImplementedError(
+            "Must be implemented by subclasses"
+        )
+
+    @abstractmethod
+    def should_start(self) -> bool:
+        """
+        Return ``True`` if the plugin should start, otherwise return ``False``
+        """
+
+        raise NotImplementedError(
+            "Must be implemented by subclasses"
+        )
+
+    @abstractmethod
+    def start(self, context: PluginContext) -> None:
+        """
+        The ``start`` method is called only once when the plugin is started
+        """
+        raise NotImplementedError(
+            "Must be implemented by subclasses"
+        )
+
+    def stop(self) -> None:
+        """
+        Called when the plugin gets stopped. Should be overwritten to perform cleanup
+        work in case the plugin set up external resources.
+        """
+        pass
+
+
+class DebugPlugin(BasePlugin):
+    """
+    This is a dummy plugin useful for demonstration and debugging purposes
+    """
+
+    @property
+    def name(self) -> str:
+        return "Debug Plugin"
+
+    def configure_parser(self, arg_parser: ArgumentParser) -> None:
+        arg_parser.add_argument("--debug-plugin", type=bool, required=False)
+
+    def handle_event(self, activation_event: BaseEvent) -> None:
+        self.logger.info("Debug plugin: handle_event called: ", activation_event)
+
+    def should_start(self) -> bool:
+        self.logger.info("Debug plugin: should_start called")
+        return True
+
+    def start(self, context: PluginContext) -> None:
+        self.logger.info("Debug plugin: start called")

trinity/extensibility/plugin_manager.py

@@ -0,0 +1,77 @@
+from argparse import (
+    ArgumentParser
+)
+import logging
+from typing import (
+    Iterable,
+    List,
+    Union,
+)
+
+from trinity.extensibility.events import (
+    BaseEvent,
+    PluginStartedEvent,
+)
+from trinity.extensibility.plugin import (
+    BasePlugin,
+)
+
+
+class PluginManager:
+    """
+    The plugin manager is responsible to register, keep and manage the life cycle of any available
+    plugins.
+
+      .. note::
+
+        This API is very much in flux and is expected to change heavily.
+    """
+
+    def __init__(self) -> None:
+        self._plugin_store: List[BasePlugin] = []
+        self._started_plugins: List[BasePlugin] = []
+        self._logger = logging.getLogger("trinity.extensibility.plugin_manager.PluginManager")
+
+    def register(self, plugins: Union[BasePlugin, Iterable[BasePlugin]]) -> None:
+        """
+        Register one or multiple instances of :class:`~trinity.extensibility.plugin.BasePlugin`
+        with the plugin manager.
+        """
+
+        new_plugins = [plugins] if isinstance(plugins, BasePlugin) else plugins
+        self._plugin_store.extend(new_plugins)
+
+    def amend_argparser_config(self, arg_parser: ArgumentParser) -> None:
+        """
+        Call :meth:`~trinity.extensibility.plugin.BasePlugin.configure_parser` for every registered
+        plugin, giving them the option to amend the global parser setup.
+        """
+        for plugin in self._plugin_store:
+            plugin.configure_parser(arg_parser)
+
+    def broadcast(self, event: BaseEvent, exclude: BasePlugin = None) -> None:
+        """
+        Notify every registered :class:`~trinity.extensibility.plugin.BasePlugin` about an
+        event and check whether the plugin wants to start based on that event.
+
+        If a plugin gets started it will cause a
+        :class:`~trinity.extensibility.events.PluginStartedEvent` to get
+        broadcasted to all other plugins, giving them the chance to start based on that.
+        """
+        for plugin in self._plugin_store:
+
+            if plugin is exclude:
+                continue
+
+            plugin.handle_event(event)
+
+            if plugin in self._started_plugins:
+                continue
+
+            if not plugin.should_start():
+                continue
+
+            plugin.start(None)
+            self._started_plugins.append(plugin)
+            self._logger.info("Plugin started: {}".format(plugin.name))
+            self.broadcast(PluginStartedEvent(plugin), plugin)