Add basic plugin discovery

.github/workflows/python-test-matrix.yml

@@ -33,6 +33,7 @@ jobs:
         python -m pip install --upgrade pip
         if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
         if [ -f requirements-dev.txt ]; then pip install -r requirements-dev.txt; fi
+        python -m pip install --editable .
     - name: Lint with flake8
       run: |
         flake8 --version

mcomix/plugins/__init__.py

@@ -0,0 +1,96 @@
+# -*- coding: utf-8 -*-
+import pkgutil
+import importlib
+import inspect
+
+import pkg_resources
+
+from mcomix.log import __logger, DEBUG
+import mcomix.plugins.base
+
+__logger.setLevel(DEBUG)
+log = __logger.getChild(__package__)
+
+
+def _get_entrypoints():
+    for plugin in pkg_resources.iter_entry_points('mcomix.plugins'):
+        yield plugin
+
+
+def _entrypoint_load_plugin(plugin, error=False):
+    try:
+        obj = plugin.load()
+    except ImportError:
+        log.error("Unable to load plugin from entrypoint `{}`".format(plugin))
+        if error:
+            raise
+        return None
+
+    # Make sure this is a plugin
+    if not issubclass(obj, mcomix.plugins.base.BasePlugin):
+        log.error("{}.{} is not a subclass of BasePlugin (found via entrypoint)".format(obj.__module__, obj.__name__))
+        if error:
+            raise TypeError("Class {} is not a plugin.".format(obj))
+        return None
+
+    return obj
+
+
+def get_entrypoint_plugins():
+    "Returns an iterable containing all plugins found via the `mcomix.plugins` entrypoint."
+    plugins = set()
+
+    # Iterate over plugin entrypoints
+    for plugin in _get_entrypoints():
+        obj = _entrypoint_load_plugin(plugin)
+
+        if obj is not None:
+            plugins.add(obj)
+            log.info("Found plugin {} at {}.{} via entrypoint ({})".format(obj.name, obj.__module__, obj.__name__, plugin.name))
+
+    return plugins
+
+
+def get_module_plugins():
+    "Returns an iterable containing all plugin classes found in the `mcomix.plugins` module."
+    plugins = set()
+
+    # Iterate over submodules of mcomix.plugins
+    for finder, name, ispkg in pkgutil.iter_modules(__path__, __package__ + "."):
+        plugin_module = importlib.import_module(name)
+
+        # Skip classes from mcomix.plugins.base
+        if plugin_module is mcomix.plugins.base:
+            continue
+
+        # Iterate over classes in module
+        for obj_name, obj in inspect.getmembers(plugin_module, inspect.isclass):
+            # Make sure this is a plugin
+            if not issubclass(obj, mcomix.plugins.base.BasePlugin):
+                log.debug("{}.{} is not a subclass of BasePlugin".format(name, obj.__name__))
+                continue
+
+            # Make sure class is defined in this module or a submodule
+            if inspect.getmodule(obj) is plugin_module or obj.__module__.startswith(name + '.'):
+
+                plugins.add(obj)
+                log.info("Found plugin {} at {}.{} via pkgutil".format(obj.name, name, obj_name))
+
+    return plugins
+
+
+def get_plugins():
+    "Returns an iterable containing all known plugin classes."
+    plugins = set()
+
+    plugins.update(get_entrypoint_plugins())
+    plugins.update(get_module_plugins())
+
+    return plugins
+
+
+__all__ = [
+    "get_plugins",
+    "get_entrypoint_plugins",
+    "get_module_plugins",
+]

mcomix/plugins/base/__init__.py

@@ -0,0 +1,22 @@
+
+
+class classproperty(object):
+    def __init__(self, fget):
+        self.fget = fget
+
+    def __get__(self, owner_self, owner_cls):
+        return self.fget(owner_cls)
+
+
+class BasePlugin(object):
+    @classproperty
+    def name(self):
+        return self.__name__
+
+
+class TestingDummyPlugin(BasePlugin):
+    """
+    This is a dummy class for testing plugin loading.
+    DO NOT USE!
+    """
+    pass

mcomix/plugins/dummy_1/__init__.py

@@ -0,0 +1,9 @@
+from mcomix.plugins.base import TestingDummyPlugin
+
+
+class DummyPlugin1(TestingDummyPlugin):
+    pass
+
+
+class NotAPlugin():
+    pass

mcomix/plugins/dummy_2.py

@@ -0,0 +1,5 @@
+from mcomix.plugins.base import TestingDummyPlugin
+
+
+class DummyPlugin2(TestingDummyPlugin):
+    name = "FooBarBaz"

setup.py

@@ -52,7 +52,14 @@
             'mcomix = mcomix.__main__:run',
             'comicthumb = mcomix.comicthumb:main'
         ],
-        'setuptools.installation': ['eggsecutable=mcomix.__main__:run'],
+        'setuptools.installation': [
+            'eggsecutable = mcomix.__main__:run'
+        ],
+        'mcomix.plugins': [
+            'DummyPlugin 1 = mcomix.plugins.dummy_1:DummyPlugin1',
+            'Fail 1 = mcomix.plugins.dummy_1:NotAPlugin',
+            'Fail 2 = mcomix.plugins.dummy_1:DoesNotExist',
+        ],
     },
     test_suite="test",
     install_requires=requirements,

test/test_plugins.py

@@ -0,0 +1,44 @@
+# coding: utf-8
+from __future__ import absolute_import
+
+import pytest
+
+import mcomix.plugins
+from mcomix.plugins.base import TestingDummyPlugin
+from mcomix.plugins.dummy_1 import DummyPlugin1
+from mcomix.plugins.dummy_2 import DummyPlugin2
+
+
+def test_dummy_plugin_count():
+    dummies = [plugin for plugin in mcomix.plugins.get_plugins() if issubclass(plugin, TestingDummyPlugin)]
+
+    assert len(dummies) == 2
+
+
+@pytest.mark.parametrize("plugin,expected_name", [
+    (DummyPlugin1, "DummyPlugin1"),
+    (DummyPlugin2, "FooBarBaz"),
+])
+def test_get_plugin_names(plugin, expected_name):
+    assert plugin.name == expected_name
+
+
+entrypoints = dict([("{}:{}".format(ep.module_name, '.'.join(ep.attrs)), ep) for ep in mcomix.plugins._get_entrypoints()])
+
+
+@pytest.mark.parametrize("plugin,exception", [
+    (entrypoints['mcomix.plugins.dummy_1:DummyPlugin1'], None),
+    (entrypoints['mcomix.plugins.dummy_1:NotAPlugin'], TypeError),
+    (entrypoints['mcomix.plugins.dummy_1:DoesNotExist'], ImportError),
+])
+def test_entrypoint_loading(plugin, exception):
+    if exception is not None:
+        with pytest.raises(exception):
+            mcomix.plugins._entrypoint_load_plugin(plugin, error=True)
+    else:
+        mcomix.plugins._entrypoint_load_plugin(plugin, error=True)
+
+
+@pytest.mark.parametrize("name", mcomix.plugins.__all__)
+def test_check_all(name):
+    assert hasattr(mcomix.plugins, name), "__all__ contains non-existant name `{}`".format(name)