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()

docs/customization.md

@@ -190,8 +190,8 @@ The basic steps are:
 
 1. Inheriting from `BaseCommitizen`
 2. Give a name to your rules.
-3. Expose the class at the end of your file assigning it to `discover_this`
-4. Create a python package starting with `cz_` using `setup.py`, `poetry`, etc
+3. Create a python package using `setup.py`, `poetry`, etc
+4. Expose the class as a `commitizen.plugin` entrypoint
 
 Check an [example](convcomms) on how to configure `BaseCommitizen`.
 
@@ -205,7 +205,7 @@ See [commitizen_cz_template](https://github.com/commitizen-tools/commitizen_cz_t
 
 ### Custom commit rules
 
-Create a file starting with `cz_`, for example `cz_jira.py`. This prefix is used to detect the plug-in. Same method [flask uses]
+Create a Python module, for example `cz_jira.py`.
 
 Inherit from `BaseCommitizen`, and you must define `questions` and `message`. The others are optional.
 
@@ -257,8 +257,6 @@ class JiraCz(BaseCommitizen):
         """
         return 'We use this because is useful'
 
-
-discover_this = JiraCz  # used by the plug-in system
 ```
 
 The next file required is `setup.py` modified from flask version.
@@ -272,7 +270,12 @@ setup(
     py_modules=['cz_jira'],
     license='MIT',
     long_description='this is a long description',
-    install_requires=['commitizen']
+    install_requires=['commitizen'],
+    entry_points = {
+        'commitizen.plugin': [
+            'cz_jira = cz_jira:JiraCz'
+        ]
+    }
 )
 ```
 
@@ -287,8 +290,6 @@ doing `pip install .`
 
 If you feel like it should be part of this repo, create a PR.
 
-[flask uses]: http://flask.pocoo.org/docs/0.12/extensiondev/
-
 ### Custom bump rules
 
 You need to define 2 parameters inside your custom `BaseCommitizen`.
@@ -381,3 +382,56 @@ from commitizen.cz.exception import CzException
 class NoSubjectProvidedException(CzException):
     ...
 ```
+
+### Migrating from legacy plugin format
+
+Commitizen migrated to a new plugin format relying on `importlib.metadata.EntryPoint`.
+Migration should be straight-forward for legacy plugins:
+
+- Remove the `discover_this` line from you plugin module
+- Expose the plugin class under as a `commitizen.plugin` entrypoint.
+
+The name of the plugin is now determined by the name of the entrypoint.
+
+#### Example
+
+If you were having a `CzPlugin` class in a `cz_plugin.py` module like this:
+
+```python
+from commitizen.cz.base import BaseCommitizen
+
+class PluginCz(BaseCommitizen):
+    ...
+
+discover_this = PluginCz
+```
+
+Then remove the `discover_this` line:
+
+```python
+from commitizen.cz.base import BaseCommitizen
+
+class PluginCz(BaseCommitizen):
+    ...
+```
+
+and expose the class as entrypoint in you setuptools:
+
+```python
+from setuptools import setup
+
+setup(
+    name='MyPlugin',
+    version='0.1.0',
+    py_modules=['cz_plugin'],
+    ...
+    entry_points = {
+        'commitizen.plugin': [
+            'plugin = cz_plugin:PluginCz'
+        ]
+    }
+    ...
+)
+```
+
+Then your plugin will be available under the name `plugin`.

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()))