feat(plugins): Switch to an importlib.metadata.EntryPoint-based plugin loading

Plugins are now loaded using the `commitizen.plugin` entrypoint
while legacy plugin are not loaded anymore but a warning is raised when one is seen.

Fixes commitizen-tools#495

BREAKING CHANGE: Plugins are now exposed as `commitizen.plugin` entrypoints

Author: noirbizarre

commitizen/_compat.py

@@ -0,0 +1,6 @@
+import sys
+
+if sys.version_info < (3, 10):
+    import importlib_metadata as metadata
+else:
+    from importlib import metadata

commitizen/cz/__init__.py

@@ -3,10 +3,8 @@
 import warnings
 from typing import Dict, Iterable, Type
 
+from commitizen._compat import metadata
 from commitizen.cz.base import BaseCommitizen
-from commitizen.cz.conventional_commits import ConventionalCommitsCz
-from commitizen.cz.customize import CustomizeCommitsCz
-from commitizen.cz.jira import JiraSmartCz
 
 
 def discover_plugins(path: Iterable[str] = None) -> Dict[str, Type[BaseCommitizen]]:
@@ -19,21 +17,19 @@ def discover_plugins(path: Iterable[str] = None) -> Dict[str, Type[BaseCommitize
     Returns:
         Dict[str, Type[BaseCommitizen]]: Registry with found plugins
     """
-    plugins = {}
-    for _finder, name, _ispkg in pkgutil.iter_modules(path):
-        try:
-            if name.startswith("cz_"):
-                plugins[name] = importlib.import_module(name).discover_this
-        except AttributeError as e:
-            warnings.warn(UserWarning(e.args[0]))
-            continue
-    return plugins
-
-
-registry: Dict[str, Type[BaseCommitizen]] = {
-    "cz_conventional_commits": ConventionalCommitsCz,
-    "cz_jira": JiraSmartCz,
-    "cz_customize": CustomizeCommitsCz,
-}
-
-registry.update(discover_plugins())
+    for _, name, _ in pkgutil.iter_modules(path):
+        if name.startswith("cz_"):
+            mod = importlib.import_module(name)
+            if hasattr(mod, "discover_this"):
+                warnings.warn(
+                    UserWarning(
+                        f"Legacy plugin '{name}' has been ignored: please expose it the 'commitizen.plugin' entrypoint"
+                    )
+                )
+
+    return {
+        ep.name: ep.load() for ep in metadata.entry_points(group="commitizen.plugin")
+    }
+
+
+registry: Dict[str, Type[BaseCommitizen]] = discover_plugins()

pyproject.toml

@@ -71,6 +71,7 @@ pyyaml = ">=3.08"
 argcomplete = ">=1.12.1,<2.1"
 typing-extensions = "^4.0.1"
 charset-normalizer = "^2.1.0"
+importlib_metadata = { version = ">=3.6", python = "<3.10" }
 
 [tool.poetry.dev-dependencies]
 ipython = "^7.2"
@@ -101,6 +102,11 @@ pytest-xdist = "^2.5.0"
 cz = "commitizen.cli:main"
 git-cz = "commitizen.cli:main"
 
+[tool.poetry.plugins."commitizen.plugin"]
+cz_conventional_commits = "commitizen.cz.conventional_commits:ConventionalCommitsCz"
+cz_jira = "commitizen.cz.jira:JiraSmartCz"
+cz_customize = "commitizen.cz.customize:CustomizeCommitsCz"
+
 [tool.isort]
 profile = "black"
 known_first_party = ["commitizen", "tests"]

tests/test_factory.py

@@ -1,10 +1,15 @@
 import sys
+from textwrap import dedent
 
 import pytest
 
 from commitizen import BaseCommitizen, defaults, factory
+from commitizen._compat import metadata
 from commitizen.config import BaseConfig
 from commitizen.cz import discover_plugins
+from commitizen.cz.conventional_commits import ConventionalCommitsCz
+from commitizen.cz.customize import CustomizeCommitsCz
+from commitizen.cz.jira import JiraSmartCz
 from commitizen.exceptions import NoCommitizenFoundException
 
 
@@ -24,17 +29,19 @@ def test_factory_fails():
     assert "The committer has not been found in the system." in str(excinfo)
 
 
-@pytest.mark.parametrize(
-    "module_content, plugin_name, expected_plugins",
-    [
-        ("", "cz_no_plugin", {}),
-    ],
-)
-def test_discover_plugins(module_content, plugin_name, expected_plugins, tmp_path):
-    no_plugin_folder = tmp_path / plugin_name
-    no_plugin_folder.mkdir()
-    init_file = no_plugin_folder / "__init__.py"
-    init_file.write_text(module_content)
+def test_discover_plugins(tmp_path):
+    legacy_plugin_folder = tmp_path / "cz_legacy"
+    legacy_plugin_folder.mkdir()
+    init_file = legacy_plugin_folder / "__init__.py"
+    init_file.write_text(
+        dedent(
+            """\
+    class Plugin: pass
+
+    discover_this = Plugin
+    """
+        )
+    )
 
     sys.path.append(tmp_path.as_posix())
     with pytest.warns(UserWarning) as record:
@@ -43,6 +50,43 @@ def test_discover_plugins(module_content, plugin_name, expected_plugins, tmp_pat
 
     assert (
         record[0].message.args[0]
-        == f"module '{plugin_name}' has no attribute 'discover_this'"
+        == "Legacy plugin 'cz_legacy' has been ignored: please expose it the 'commitizen.plugin' entrypoint"
+    )
+    assert "cz_legacy" not in discovered_plugins
+
+
+def test_discover_external_plugin(mocker):
+    class Plugin:
+        pass
+
+    class OtherPlugin:
+        pass
+
+    ep_plugin = metadata.EntryPoint("test", "some:Plugin", "commitizen.plugin")
+    ep_other_plugin = metadata.EntryPoint(
+        "not-selected", "some:OtherPlugin", "commitizen.not_a_plugin"
     )
-    assert expected_plugins == discovered_plugins
+    eps = [ep_plugin, ep_other_plugin]
+
+    mocker.patch.object(ep_plugin, "load", return_value=Plugin)
+    mocker.patch.object(ep_other_plugin, "load", return_value=OtherPlugin)
+
+    def mock_entrypoints(**kwargs):
+        group = kwargs.get("group")
+        return metadata.EntryPoints(ep for ep in eps if ep.group == group)
+
+    mocker.patch.object(metadata, "entry_points", side_effect=mock_entrypoints)
+
+    assert discover_plugins() == {"test": Plugin}
+
+
+def test_discover_internal_plugins():
+    expected = {
+        "cz_conventional_commits": ConventionalCommitsCz,
+        "cz_jira": JiraSmartCz,
+        "cz_customize": CustomizeCommitsCz,
+    }
+
+    discovered = discover_plugins()
+
+    assert set(expected.items()).issubset(set(discovered.items()))