feat(providers): add a commitizen.provider endpoint for alternative versions providers

Author: noirbizarre

commitizen/commands/bump.py

@@ -21,6 +21,7 @@
     NotAllowed,
     NoVersionSpecifiedError,
 )
+from commitizen.providers import get_provider
 
 logger = getLogger("commitizen")
 
@@ -91,14 +92,14 @@ def find_increment(self, commits: List[git.GitCommit]) -> Optional[str]:
 
     def __call__(self):  # noqa: C901
         """Steps executed to bump."""
+        provider = get_provider(self.config)
+        current_version: str = provider.get_version()
+
         try:
-            current_version_instance: Version = Version(self.bump_settings["version"])
+            current_version_instance: Version = Version(current_version)
         except TypeError:
             raise NoVersionSpecifiedError()
 
-        # Initialize values from sources (conf)
-        current_version: str = self.config.settings["version"]
-
         tag_format: str = self.bump_settings["tag_format"]
         bump_commit_message: str = self.bump_settings["bump_message"]
         version_files: List[str] = self.bump_settings["version_files"]
@@ -270,7 +271,7 @@ def __call__(self):  # noqa: C901
             check_consistency=self.check_consistency,
         )
 
-        self.config.set_key("version", str(new_version))
+        provider.set_version(str(new_version))
 
         if is_files_only:
             raise ExpectedExit()

commitizen/commands/version.py

@@ -4,6 +4,7 @@
 from commitizen import out
 from commitizen.__version__ import __version__
 from commitizen.config import BaseConfig
+from commitizen.providers import get_provider
 
 
 class Version:
@@ -21,14 +22,14 @@ def __call__(self):
             out.write(f"Python Version: {self.python_version}")
             out.write(f"Operating System: {self.operating_system}")
         elif self.parameter.get("project"):
-            version = self.config.settings["version"]
+            version = get_provider(self.config).get_version()
             if version:
                 out.write(f"{version}")
             else:
                 out.error("No project information in this project.")
         elif self.parameter.get("verbose"):
             out.write(f"Installed Commitizen Version: {__version__}")
-            version = self.config.settings["version"]
+            version = get_provider(self.config).get_version()
             if version:
                 out.write(f"Project Version: {version}")
             else:

commitizen/defaults.py

@@ -29,6 +29,7 @@ class Settings(TypedDict, total=False):
     name: str
     version: Optional[str]
     version_files: List[str]
+    version_provider: Optional[str]
     tag_format: Optional[str]
     bump_message: Optional[str]
     allow_abort: bool
@@ -56,6 +57,7 @@ class Settings(TypedDict, total=False):
     "name": "cz_conventional_commits",
     "version": None,
     "version_files": [],
+    "version_provider": "commitizen",
     "tag_format": None,  # example v$version
     "bump_message": None,  # bumped v$current_version to $new_version
     "allow_abort": False,

commitizen/exceptions.py

@@ -29,6 +29,7 @@ class ExitCode(enum.IntEnum):
     UNRECOGNIZED_CHARACTERSET_ENCODING = 22
     GIT_COMMAND_ERROR = 23
     INVALID_MANUAL_VERSION = 24
+    VERSION_PROVIDER_UNKNOWN = 25
 
 
 class CommitizenException(Exception):
@@ -163,3 +164,7 @@ class GitCommandError(CommitizenException):
 
 class InvalidManualVersion(CommitizenException):
     exit_code = ExitCode.INVALID_MANUAL_VERSION
+
+
+class VersionProviderUnknown(CommitizenException):
+    exit_code = ExitCode.VERSION_PROVIDER_UNKNOWN

commitizen/providers.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import cast
+
+import importlib_metadata as metadata
+
+from commitizen.config.base_config import BaseConfig
+from commitizen.exceptions import VersionProviderUnknown
+
+ENTRYPOINT = "commitizen.provider"
+DEFAULT = "commitizen"
+
+
+class VersionProvider(ABC):
+    """
+    Abstract base class for version providers.
+
+    Each version provider should inherit and implement this class.
+    """
+
+    config: BaseConfig
+
+    def __init__(self, config: BaseConfig):
+        self.config = config
+
+    @abstractmethod
+    def get_version(self) -> str:
+        """
+        Get the current version
+        """
+        ...
+
+    @abstractmethod
+    def set_version(self, version: str):
+        """
+        Set the new current version
+        """
+        ...
+
+
+class CommitizenProvider(VersionProvider):
+    """
+    Default version provider: Fetch and set version in commitizen config.
+    """
+
+    def get_version(self) -> str:
+        return self.config.settings["version"]  # type: ignore
+
+    def set_version(self, version: str):
+        self.config.set_key("version", version)
+
+
+def get_provider(config: BaseConfig) -> VersionProvider:
+    """
+    Get the version provider as defined in the configuration
+
+    :raises VersionProviderUnknown: if the provider named by `version_provider` is not found.
+    """
+    provider_name = config.settings["version_provider"] or DEFAULT
+    try:
+        (ep,) = metadata.entry_points(name=provider_name, group=ENTRYPOINT)
+    except ValueError:
+        raise VersionProviderUnknown(f'Version Provider "{provider_name}" unknown.')
+    provider_cls = ep.load()
+    return cast(VersionProvider, provider_cls(config))

docs/config.md

@@ -7,6 +7,7 @@
 | `name`                     | `str`  | `"cz_conventional_commits"` | Name of the committing rules to use                                                                                                                                                             |
 | `version`                  | `str`  | `None`                      | Current version. Example: "0.1.2"                                                                                                                                                               |
 | `version_files`            | `list` | `[ ]`                       | Files were the version will be updated. A pattern to match a line, can also be specified, separated by `:` [See more][version_files]                                                            |
+| `version_provider`         | `str`  | `commitizen`                | Version provider used to read and write version [See more](#version-providers)                                                            |
 | `tag_format`               | `str`  | `None`                      | Format for the git tag, useful for old projects, that use a convention like `"v1.2.1"`. [See more][tag_format]                                                                                  |
 | `update_changelog_on_bump` | `bool` | `false`                     | Create changelog when running `cz bump`                                                                                                                                                         |
 | `gpg_sign`                 | `bool` | `false`                     | Use gpg signed tags instead of lightweight tags.                                                                                                                                                |
@@ -111,6 +112,54 @@ commitizen:
       - fg:#858585 italic
 ```
 
+## Version providers
+
+Commitizen can read and write version from different sources.
+By default, it use the `commitizen` one which is using the `version` field from the commitizen settings.
+But you can use any `commitizen.provider` entrypoint as value for `version_provider`.
+
+### Custom version provider
+
+You can add you own version provider by extending `VersionProvider` and exposing it on the `commitizen.provider` entrypoint.
+
+Here a quick example of a `my-provider` provider reading and writing version in a `VERSION` file.
+
+`my_provider.py`
+
+```python
+from pathlib import Path
+from commitizen.providers import VersionProvider
+
+
+class MyProvider(VersionProvider):
+    file = Path() / "VERSION"
+
+    def get_version(self) -> str:
+        return self.file.read_text()
+
+    def set_version(self, version: str):
+        self.file.write_text(version)
+
+```
+
+`setup.py`
+
+```python
+from setuptools import setup
+
+setup(
+    name='my-commitizen-provider',
+    version='0.1.0',
+    py_modules=['my_provider'],
+    install_requires=['commitizen'],
+    entry_points = {
+        'commitizen.provider': [
+            'my-provider = my_provider:MyProvider',
+        ]
+    }
+)
+```
+
 [version_files]: bump.md#version_files
 [tag_format]: bump.md#tag_format
 [bump_message]: bump.md#bump_message

docs/exit_codes.md

@@ -30,4 +30,6 @@ These exit codes can be found in `commitizen/exceptions.py::ExitCode`.
 | NotAllowed                  | 20        | `--incremental` cannot be combined with a `rev_range`                                                       |
 | NoneIncrementExit           | 21        | The commits found are not eligible to be bumped                                                             |
 | CharacterSetDecodeError     | 22        | The character encoding of the command output could not be determined                                        |
-| GitCommandError             | 23       | Unexpected failure while calling a git command                                                              |
+| GitCommandError             | 23        | Unexpected failure while calling a git command                                                              |
+| InvalidManualVersion        | 24        | Manually provided version is invalid                                                                        |
+| VersionProviderUnknown      | 25        | `version_provider` setting is set to an unknown version provider indentifier                                |

pyproject.toml

@@ -104,6 +104,9 @@ cz_conventional_commits = "commitizen.cz.conventional_commits:ConventionalCommit
 cz_jira = "commitizen.cz.jira:JiraSmartCz"
 cz_customize = "commitizen.cz.customize:CustomizeCommitsCz"
 
+[tool.poetry.plugins."commitizen.provider"]
+commitizen = "commitizen.providers:CommitizenProvider"
+
 [tool.isort]
 profile = "black"
 known_first_party = ["commitizen", "tests"]

tests/commands/test_bump_command.py

@@ -4,6 +4,7 @@
 from unittest.mock import MagicMock
 
 import pytest
+from pytest_mock import MockerFixture
 
 import commitizen.commands.bump as bump
 from commitizen import cli, cmd, git
@@ -754,3 +755,23 @@ def test_bump_manual_version_disallows_major_version_zero(mocker):
         "--major-version-zero cannot be combined with MANUAL_VERSION"
     )
     assert expected_error_message in str(excinfo.value)
+
+
+@pytest.mark.usefixtures("tmp_git_project")
+def test_bump_use_version_provider(mocker: MockerFixture):
+    mock = mocker.MagicMock(name="provider")
+    mock.get_version.return_value = "0.0.0"
+    get_provider = mocker.patch(
+        "commitizen.commands.bump.get_provider", return_value=mock
+    )
+
+    create_file_and_commit("fix: fake commit")
+    testargs = ["cz", "bump", "--yes", "--changelog"]
+    mocker.patch.object(sys, "argv", testargs)
+
+    cli.main()
+
+    assert git.tag_exist("0.0.1")
+    get_provider.assert_called_once()
+    mock.get_version.assert_called_once()
+    mock.set_version.assert_called_once_with("0.0.1")

tests/commands/test_version_command.py

@@ -1,8 +1,12 @@
 import platform
 import sys
 
+import pytest
+from pytest_mock import MockerFixture
+
 from commitizen import commands
 from commitizen.__version__ import __version__
+from commitizen.config.base_config import BaseConfig
 
 
 def test_version_for_showing_project_version(config, capsys):
@@ -70,3 +74,30 @@ def test_version_for_showing_commitizen_system_info(config, capsys):
     assert f"Commitizen Version: {__version__}" in captured.out
     assert f"Python Version: {sys.version}" in captured.out
     assert f"Operating System: {platform.system()}" in captured.out
+
+
+@pytest.mark.parametrize("project", (True, False))
+@pytest.mark.usefixtures("tmp_git_project")
+def test_version_use_version_provider(
+    mocker: MockerFixture,
+    config: BaseConfig,
+    capsys: pytest.CaptureFixture,
+    project: bool,
+):
+    version = "0.0.0"
+    mock = mocker.MagicMock(name="provider")
+    mock.get_version.return_value = version
+    get_provider = mocker.patch(
+        "commitizen.commands.version.get_provider", return_value=mock
+    )
+
+    commands.Version(
+        config,
+        {"report": False, "project": project, "commitizen": False, "verbose": True},
+    )()
+    captured = capsys.readouterr()
+
+    assert version in captured.out
+    get_provider.assert_called_once()
+    mock.get_version.assert_called_once()
+    mock.set_version.assert_not_called()

tests/test_conf.py

@@ -38,6 +38,7 @@
 _settings = {
     "name": "cz_jira",
     "version": "1.0.0",
+    "version_provider": "commitizen",
     "tag_format": None,
     "bump_message": None,
     "allow_abort": False,
@@ -54,6 +55,7 @@
 _new_settings = {
     "name": "cz_jira",
     "version": "2.0.0",
+    "version_provider": "commitizen",
     "tag_format": None,
     "bump_message": None,
     "allow_abort": False,

tests/test_version_providers.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+
+from commitizen.config.base_config import BaseConfig
+from commitizen.exceptions import VersionProviderUnknown
+from commitizen.providers import CommitizenProvider, get_provider
+
+if TYPE_CHECKING:
+    from pytest_mock import MockerFixture
+
+
+def test_default_version_provider_is_commitizen_config(config: BaseConfig):
+    provider = get_provider(config)
+
+    assert isinstance(provider, CommitizenProvider)
+
+
+def test_raise_for_unknown_provider(config: BaseConfig):
+    config.settings["version_provider"] = "unknown"
+    with pytest.raises(VersionProviderUnknown):
+        get_provider(config)
+
+
+def test_commitizen_provider(config: BaseConfig, mocker: MockerFixture):
+    config.settings["version"] = "42"
+    mock = mocker.patch.object(config, "set_key")
+
+    provider = CommitizenProvider(config)
+    assert provider.get_version() == "42"
+
+    provider.set_version("43.1")
+    mock.assert_called_once_with("version", "43.1")