Move plugins to BaseConfig.plugins_for_nox_sessions and add tests

Author: ArBridgeman

doc/changes/unreleased.md

@@ -10,3 +10,4 @@ and replaces them with `format:fix` and `format:check`.
 ## Feature
 
 * #614: Replaced `path_filters` with `BaseConfig.add_to_excluded_python_paths` and `BaseConfig.excluded_python_paths`
+* #626: Replaced `plugins` with `BaseConfig.plugins_for_nox_sessions`

doc/user_guide/customization.rst

@@ -65,16 +65,15 @@ Plugin Registration
 
 Once the plugin class has been defined, it must be registered in the Nox configuration. This is done by adding the class to the `plugins` list within the `Config` data class.
 
-In the Nox `Config` data class, you should amend the `plugins` list to include the new plugin:
+In the Nox `PROJECT_CONFIG`, you should amend the `plugins_for_nox_sessions` tuple to include the new plugin:
 
 .. code-block:: python
 
-    @dataclass(frozen=True)
-    class Config:
-        """Project-specific configuration used by Nox infrastructure."""
-        # ... other configuration attributes ...
+    from exasol.toolbox.config import BaseConfig
 
-        plugins = [UpdateTemplates]  # register the plugin
+    PROJECT_CONFIG = BaseConfig(
+        plugins_for_nox_sessions=(UpdateTemplates,), # register the plugin
+    )
 
 When Nox runs, it will instantiate `UpdateTemplates` with no arguments and integrate the hooks defined by the plugin into the execution lifecycle. All registered plugins’ hooks are called at their designated points in the Nox workflow.
 

doc/user_guide/getting_started.rst

@@ -91,7 +91,7 @@ example shown below.
 
 .. note::
 
-   For further details on plugins, see the customization section.
+   For further details on plugins, see :ref:`plugins` in the Customization section.
 
 .. collapse:: noxconfig.py
 

exasol/toolbox/config.py

@@ -1,5 +1,7 @@
+import inspect
 from typing import (
     Annotated,
+    Any,
 )
 
 from pydantic import (
@@ -10,14 +12,50 @@
     computed_field,
 )
 
+from exasol.toolbox.nox.plugin import (
+    METHODS_SPECIFIED_FOR_HOOKS,
+    PLUGIN_ATTR_NAME,
+)
 from exasol.toolbox.util.version import Version
 
 
+def validate_plugin_hook(plugin_class: type[Any]):
+    """
+    Checks methods in a class for at least one specific pluggy @hookimpl marker
+    and verifies that this method is also specified in
+    `exasol.toolbox.nox.plugins.NoxTasks`.
+    """
+    has_hook_implementation = False
+    not_specified_decorated_methods = []
+    for name, method in inspect.getmembers(plugin_class, inspect.isroutine):
+        if hasattr(method, PLUGIN_ATTR_NAME):
+            has_hook_implementation = True
+            if name not in METHODS_SPECIFIED_FOR_HOOKS:
+                not_specified_decorated_methods.append(name)
+
+    if not has_hook_implementation:
+        raise ValueError(
+            f"No methods in `{plugin_class.__name__}` were found to be decorated"
+            "with `@hookimpl`"
+        )
+
+    if not_specified_decorated_methods:
+        raise ValueError(
+            f"{len(not_specified_decorated_methods)} method(s) were "
+            "decorated with `@hookimpl`, but these methods were not "
+            "specified in `exasol.toolbox.nox.plugins.NoxTasks`: "
+            f"{not_specified_decorated_methods}"
+        )
+
+    return plugin_class
+
+
 def valid_version_string(version_string: str) -> str:
     Version.from_string(version_string)
     return version_string
 
 
+ValidPluginHook = Annotated[type[object], AfterValidator(validate_plugin_hook)]
 ValidVersionStr = Annotated[str, AfterValidator(valid_version_string)]
 
 DEFAULT_EXCLUDED_PATHS = {
@@ -68,6 +106,16 @@ class BaseConfig(BaseModel):
         `exasol.toolbox.config.DEFAULT_EXCLUDED_PATHS`.
         """,
     )
+    plugins_for_nox_sessions: tuple[ValidPluginHook, ...] = Field(
+        default=(),
+        description="""
+        This is used to provide hooks to extend one or more of the Nox sessions provided
+        by the python-toolbox. As described on the plugins pages:
+            - https://exasol.github.io/python-toolbox/main/user_guide/customization.html#plugins
+            - https://exasol.github.io/python-toolbox/main/developer_guide/plugins.html,
+        possible plugin options are defined in `exasol.toolbox.nox.plugins.NoxTasks`.
+        """,
+    )
     model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
 
     @computed_field  # type: ignore[misc]

exasol/toolbox/nox/plugin.py

@@ -1,6 +1,9 @@
+import inspect
+
 import pluggy
 
 _PLUGIN_MARKER = "python-toolbox-nox"
+PLUGIN_ATTR_NAME = f"{_PLUGIN_MARKER}_impl"
 hookspec = pluggy.HookspecMarker("python-toolbox-nox")
 hookimpl = pluggy.HookimplMarker("python-toolbox-nox")
 
@@ -105,6 +108,24 @@ def post_integration_tests_hook(self, session, config, context):
     def plugin_manager(config) -> pluggy.PluginManager:
         pm = pluggy.PluginManager(_PLUGIN_MARKER)
         pm.add_hookspecs(NoxTasks)
-        for plugin in getattr(config, "plugins", []):
+        plugin_attribute = "plugins_for_nox_sessions"
+
+        if not hasattr(config, plugin_attribute):
+            raise AttributeError(
+                "in the noxconfig.py file, the class Config should inherit "
+                "from `exasol.toolbox.config.BaseConfig`. This is used to "
+                f"set the default `{plugin_attribute}`. If the allowed "
+                f"`{plugin_attribute} needs to differ in your project and is an "
+                "input parameter (not property), you can set it in the PROJECT_CONFIG statement."
+            )
+
+        for plugin in getattr(config, plugin_attribute, ()):
             pm.register(plugin())
         return pm
+
+
+METHODS_SPECIFIED_FOR_HOOKS = [
+    name
+    for name, method in inspect.getmembers(NoxTasks, inspect.isroutine)
+    if hasattr(method, f"{_PLUGIN_MARKER}_spec")
+]

noxconfig.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-from collections.abc import Iterable
 from pathlib import Path
 
 from exasol.toolbox.config import BaseConfig
@@ -56,7 +55,6 @@ class Config(BaseConfig):
     source: Path = Path("exasol/toolbox")
     importlinter: Path = Path(__file__).parent / ".import_linter_config"
     version_file: Path = Path(__file__).parent / "exasol" / "toolbox" / "version.py"
-    plugins: Iterable[object] = (UpdateTemplates,)
 
 
 PROJECT_CONFIG = Config(
@@ -73,4 +71,5 @@ class Config(BaseConfig):
     # The PTB does not have integration tests run with an Exasol DB,
     # so for running in the CI, we take the first element.
     exasol_versions=(BaseConfig().exasol_versions[0],),
+    plugins_for_nox_sessions=(UpdateTemplates,),
 )

project-template/{{cookiecutter.repo_name}}/noxconfig.py

@@ -16,6 +16,5 @@ class Config(BaseConfig):
             / "{{cookiecutter.package_name}}"
             / "version.py"
     )
-    plugins: Iterable[object] = ()
 
 PROJECT_CONFIG = Config()

test/unit/config_test.py

@@ -6,6 +6,8 @@
     BaseConfig,
     valid_version_string,
 )
+from exasol.toolbox.nox.plugin import hookimpl
+from exasol.toolbox.util.version import Version
 
 
 class TestBaseConfig:
@@ -86,3 +88,43 @@ def test_pyupgrade_argument(minimum_python_version):
 def test_excluded_python_paths(add_to_excluded_python_paths, expected):
     conf = BaseConfig(add_to_excluded_python_paths=add_to_excluded_python_paths)
     assert sorted(conf.excluded_python_paths) == sorted(expected)
+
+
+class WithHook:
+    @hookimpl
+    def prepare_release_update_version(self, session, config, version: Version) -> None:
+        print("This is a simple, silly hook.")
+
+
+class WithNotSpecifiedHook:
+    @hookimpl
+    def not_specified_anywhere(self, session, config, version: Version) -> None:
+        print("This is not a properly prepared hook.")
+
+
+class WithoutHook:
+    def prepare_release_update_version(self, session, config, version: Version) -> None:
+        print("This is not a properly prepared hook.")
+
+
+class TestPlugins:
+    @staticmethod
+    def test_works_when_empty():
+        BaseConfig(plugins_for_nox_sessions=())
+
+    @staticmethod
+    def test_works_for_hook(capsys):
+        BaseConfig(plugins_for_nox_sessions=(WithHook,))
+
+    @staticmethod
+    def test_raises_exception_method_with_hook_not_specified():
+        with pytest.raises(ValidationError) as ex:
+            BaseConfig(plugins_for_nox_sessions=(WithNotSpecifiedHook,))
+        assert "1 method(s) were decorated with `@hookimpl`, but" in str(ex.value)
+        assert "['not_specified_anywhere']" in str(ex.value)
+
+    @staticmethod
+    def test_raises_exception_without_hook():
+        with pytest.raises(ValidationError) as ex:
+            BaseConfig(plugins_for_nox_sessions=(WithoutHook,))
+        assert "No methods in `WithoutHook`" in str(ex.value)