[feat] Add API hooks (#20)

Author: slarse

docs/conf.py

@@ -68,9 +68,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.5'
+version = '0.6'
 # The full version, including alpha/beta/rc tags.
-release = '0.5.1'
+release = '0.6.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/implementing.rst

@@ -2,9 +2,9 @@ Implementing hooks and writing internal plugins
 ***********************************************
 Implementing a hook is fairly simple, and works the same way regardless of what
 type of hook it is (core or extension). If you are working with your own fork
-of ``repobee``, all you have to do is write a small module implementing some hooks,
+of RepoBee, all you have to do is write a small module implementing some hooks,
 and drop it into the ``repobee.ext`` sub-package (i.e. the in directory
-``repobee/ext`` in the ``repobee`` repo).
+``repobee/ext`` in the RepoBee repo).
 
 There are two ways to implement hooks: as standalone functions or wrapped in a
 class. In the following two sections, we'll implement the
@@ -16,7 +16,7 @@ Hook functions in a plugin class
 ================================
 Wrapping hook implementations in a class inheriting from
 :py:class:`~repobee_plug.pluginmeta.Plugin` is the recommended way to write
-plugins for ``repobee``. The class does some checks to make sure that all
+plugins for RepoBee. The class does some checks to make sure that all
 public functions have hook function names, which comes in handy if you are
 in the habit of misspelling stuff (aren't we all?). Doing it this way,
 ``exampleplug.py`` would look like this:
@@ -35,12 +35,14 @@ in the habit of misspelling stuff (aren't we all?). Doing it this way,
     class ExamplePlugin(plug.Plugin):
         """Example plugin that implements the act_on_cloned_repo hook."""
 
-        def act_on_cloned_repo(self,
-                               path: Union[str, pathlib.Path]) -> plug.HookResult:
+        def act_on_cloned_repo(
+            self, path: Union[str, pathlib.Path], api,
+        ) -> plug.HookResult:
             """Do something with a cloned repo.
             
             Args:
                 path: Path to the student repo.
+                api: A platform API instance.
             Returns:
                 a plug.HookResult specifying the outcome.
             """
@@ -59,8 +61,8 @@ fact, all public methods in a class deriving from
 :py:class:`~repobee_plug.pluginmeta.Plugin` must have names of hook functions,
 or the class will fail to be created. You can see that the hook returns a
 :py:class:`~repobee_plug.util.HookResult`. This is used for reporting the
-results in ``repobee``, and is entirely optional (not all hooks support it,
-though). Do note that if ``None`` is returned instead, ``repobee`` will not
+results in RepoBee, and is entirely optional (not all hooks support it,
+though). Do note that if ``None`` is returned instead, RepoBee will not
 report anything for the hook. It is recommended that hooks that can return
 ``HookResult`` do. For a comprehensive example of an internal plugin
 implemented with a class, see the built-in `javac plugin`_.

docs/overview.rst

@@ -3,7 +3,7 @@ Plugin system overview
 
 Conventions
 ===========
-For ``repobee`` to discover a plugin and its hooks, the following conventions
+For RepoBee to discover a plugin and its hooks, the following conventions
 need to be adhered to:
 
 1. The PyPi package should be named ``repobee-<plugin>``, where ``<plugin>``
@@ -16,32 +16,36 @@ need to be adhered to:
 
 For an example plugin that follows these conventions, have a look at
 repobee-junit4_.  Granted that the plugin follows these conventions and is
-installed, it can be loaded like any other ``repobee`` plugin (see `Using
+installed, it can be loaded like any other RepoBee plugin (see `Using
 Existing Plugins`_).
 
 Hooks
 =====
-There are two types of hooks in ``repobee``: *core hooks* and *extension
+There are two types of hooks in RepoBee: *core hooks* and *extension
 hooks*.
 
 Core hooks
 ----------
-Core hooks provide core functionality for ``repobee``, and always have a
+Core hooks provide core functionality for RepoBee, and always have a
 default implementation in :py:mod:`repobee.ext.defaults`. Providing a
 different plugin implementation will override this behavior, thereby
-changing some core part of ``repobee``. In general, only one implementation
-of a core hook will run per invocation of ``repobee``. All core hooks are
+changing some core part of RepoBee. In general, only one implementation
+of a core hook will run per invocation of RepoBee. All core hooks are
 defined in :py:mod:`repobee_plug.corehooks`.
 
+.. important::
+
+   Note that the default implementations in :py:mod:`repobee.ext.defaults` may
+   simply be *imported* into the module. They are not necessarily defined
+   there.
+
 Extension hooks
 ---------------
-Extension hooks extend the functionality of ``repobee`` in various ways.
+Extension hooks extend the functionality of RepoBee in various ways.
 Unlike the core hooks, there are no default implementations of the extension
 hooks, and multiple implementations can be run on each invocation of
-``repobee``. All extension hooks are defined in
-:py:mod:`repobee_plug.exthooks`. repobee-junit4_ consists solely of extension hooks,
-and so do all of the `repobee built-ins`_ except for :py:mod:`repobee.ext.defaults`.
+RepoBee. All extension hooks are defined in :py:mod:`repobee_plug.exthooks`.
 
-.. _repobee built-ins: https://repobee.readthedocs.io/en/latest/plugins.html#built-in-plugins
+.. _repobee built-ins: https://repobee.readthedocs.io/en/stable/plugins.html#built-in-plugins
 .. _repobee-junit4: https://github.com/repobee/repobee-junit4
-.. _Using Existing Plugins: https://repobee.readthedocs.io/en/latest/plugins.html#using-existing-plugins
+.. _Using Existing Plugins: https://repobee.readthedocs.io/en/stable/plugins.html#using-existing-plugins

repobee_plug/__init__.py

@@ -6,10 +6,12 @@
 from repobee_plug.util import HookResult
 from repobee_plug.util import Status
 from repobee_plug.corehooks import PeerReviewHook as _peer_hook
+from repobee_plug.corehooks import APIHook as _api_hook
 from repobee_plug.exthooks import CloneHook as _clone_hook
 
 manager = pluggy.PluginManager(__package__)
 manager.add_hookspecs(_clone_hook)
 manager.add_hookspecs(_peer_hook)
+manager.add_hookspecs(_api_hook)
 
 __all__ = ["Plugin", "manager", "repobee_hook", "HookResult", "Status"]

repobee_plug/__version.py

@@ -1 +1 @@
-__version__ = '0.5.1'
+__version__ = "0.6.0"

repobee_plug/corehooks.py

@@ -11,7 +11,7 @@
 .. moduleauthor:: Simon Larsén
 """
 
-from typing import Union, Optional, Iterable, List, Mapping, Callable
+from typing import Union, Optional, Iterable, List, Mapping, Callable, Tuple
 
 from repobee_plug.util import hookspec
 
@@ -21,9 +21,11 @@ class PeerReviewHook:
 
     @hookspec(firstresult=True)
     def generate_review_allocations(
-            self, master_repo_name: str, students: Iterable[str],
-            num_reviews: int,
-            review_team_name_function: Callable[[str, str], str]
+        self,
+        master_repo_name: str,
+        students: Iterable[str],
+        num_reviews: int,
+        review_team_name_function: Callable[[str, str], str],
     ) -> Mapping[str, List[str]]:
         """Generate a (peer_review_team -> reviewers) mapping for each student
         repository (i.e. <student>-<master_repo_name>), where len(reviewers) =
@@ -52,3 +54,25 @@ def generate_review_allocations(
         Returns:
             a (peer_review_team -> reviewers) mapping for each student repository.
         """
+
+
+class APIHook:
+    """Hooks related to platform APIs."""
+
+    @hookspec(firstresult=True)
+    def get_api_class(self):
+        """Return an API platform class. Must be a subclass of apimeta.API.
+        
+        Returns:
+            An apimeta.API subclass.
+        """
+
+    @hookspec(firstresult=True)
+    def api_init_requires(self) -> Tuple[str]:
+        """Return which of the arguments to apimeta.APISpec.__init__ that the
+        given API requires. For example, the GitHubAPI requires all, but the
+        GitLabAPI does not require ``user``.
+
+        Returns:
+            Names of the required arguments.
+        """

repobee_plug/exthooks.py

@@ -23,8 +23,9 @@ class CloneHook:
     """Hook functions related to cloning repos."""
 
     @hookspec
-    def act_on_cloned_repo(self, path: Union[str, pathlib.Path],
-                           api) -> Optional[HookResult]:
+    def act_on_cloned_repo(
+        self, path: Union[str, pathlib.Path], api
+    ) -> Optional[HookResult]:
         """Do something with a cloned repo.
 
         Args:

repobee_plug/pluginmeta.py

@@ -9,8 +9,10 @@
     key: value
     for key, value in [
         *exthooks.CloneHook.__dict__.items(),
-        *corehooks.PeerReviewHook.__dict__.items()
-    ] if callable(value) and not key.startswith('_')
+        *corehooks.PeerReviewHook.__dict__.items(),
+        *corehooks.APIHook.__dict__.items(),
+    ]
+    if callable(value) and not key.startswith("_")
 }
 
 
@@ -35,8 +37,7 @@ def __new__(cls, name, bases, attrdict):
         methods = cls._extract_public_methods(attrdict)
         cls._check_names(methods)
         hooked_methods = {
-            name: util.hookimpl(method)
-            for name, method in methods.items()
+            name: util.hookimpl(method) for name, method in methods.items()
         }
         attrdict.update(hooked_methods)
 
@@ -49,14 +50,16 @@ def _check_names(methods):
         if not method_names.issubset(hook_names):
             raise exception.HookNameError(
                 "public method(s) with non-hook name: {}".format(
-                    ", ".join(method_names - hook_names)))
+                    ", ".join(method_names - hook_names)
+                )
+            )
 
     @staticmethod
     def _extract_public_methods(attrdict):
         return {
             key: value
             for key, value in attrdict.items()
-            if callable(value) and not key.startswith('_')
+            if callable(value) and not key.startswith("_")
         }
 
 

repobee_plug/util.py

@@ -12,11 +12,12 @@
 hookspec = pluggy.HookspecMarker(__package__)
 hookimpl = pluggy.HookimplMarker(__package__)
 
-HookResult = collections.namedtuple('HookResult', ('hook', 'status', 'msg'))
+HookResult = collections.namedtuple("HookResult", ("hook", "status", "msg"))
 
 
 class Status(enum.Enum):
     """Status codes enum."""
-    SUCCESS = 'success'
-    WARNING = 'warning'
-    ERROR = 'error'
+
+    SUCCESS = "success"
+    WARNING = "warning"
+    ERROR = "error"

tests/test_pluginmeta.py

@@ -47,6 +47,12 @@ def generate_review_allocations(
             ):
                 pass
 
+            def get_api_class(self):
+                pass
+
+            def api_init_requires(self):
+                pass
+
     def test_with_private_methods(self):
         """Private methods should be able to have any names."""
 
@@ -70,6 +76,12 @@ def generate_review_allocations(
             ):
                 pass
 
+            def get_api_class(self):
+                pass
+
+            def api_init_requires(self):
+                pass
+
             def _some_method(self, x, y):
                 return x + y