comver 0.2.0__py3-none-any.whl

comver/error.py

@@ -0,0 +1,82 @@
+# SPDX-FileCopyrightText: © 2025 open-nudge <https://github.com/open-nudge>
+# SPDX-FileContributor: szymonmaszke <github@maszke.co>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Custom exceptions of `comver`."""
+
+from __future__ import annotations
+
+
+class ComverError(Exception):
+    """Base class for all exceptions raised by `comver`."""
+
+
+class MessageUnrecognizedError(ComverError):
+    """Raised when the message is not recognized by any regexes."""
+
+    def __init__(self, message: str) -> None:
+        """Initialize the error.
+
+        Args:
+            message:
+                The message which was not recognized by any regexes.
+
+        """
+        self.message: str = message
+
+        super().__init__(
+            f"Message '{message}' is not recognized by any of the provided regexes."
+        )
+
+
+class VersionFormatError(ComverError):
+    """Raised when the string version is not properly formatted.
+
+    Proper format should consist of three dot-separated elements,
+    e.g. `7.23.1`.
+
+    """
+
+    def __init__(self, version: str) -> None:
+        """Initialize the error.
+
+        Args:
+            version:
+                String version with incorrect formatting.
+
+        """
+        self.version: str = version
+
+        super().__init__(
+            f"Version should consist of three dot separated elements (MAJOR.MINOR.PATCH), got: {version}"
+        )
+
+
+class VersionNotNumericError(ComverError):
+    """Raised when the string version contains non-numeric elements.
+
+    Proper format should consist of three dot-separated numeric elements,
+    e.g. `7.23.1`. This error is raised, if there is a version like
+    `1.2.0a1`.
+
+    Warning:
+        Only
+        [semantic Python versioning](https://packaging.python.org/en/latest/discussions/versioning/)
+        is allowed, e.g. no `1.2.0a1` for alpha releases
+
+    """
+
+    def __init__(self, version: str) -> None:
+        """Initialize the error.
+
+        Args:
+            version:
+                Properly formatted string version with non-numeric elements.
+
+        """
+        self.version: str = version
+
+        super().__init__(
+            f"One of the MAJOR, MINOR, PATCH is not an integer. Expected <INT>.<INT>.<INT>, got: {version}"
+        )

comver/plugin.py

@@ -0,0 +1,241 @@
+# SPDX-FileCopyrightText: © 2025 open-nudge <https://github.com/open-nudge>
+# SPDX-FileContributor: szymonmaszke <github@maszke.co>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Extensions and plugins integrating `comver` with third party systems.
+
+Most of the extensions are tailored to the Python ecosystem, and its
+packagae managers specifically.
+
+__Currently supported third party tools:__
+
+- [`pdm`](https://pdm-project.org/en/latest/) package manager.
+- [`hatch`](https://hatch.pypa.io/1.9/plugins/version-source/reference/)
+    package manager.
+
+Warning:
+    Check out guidelines and tutorials for information about CLI/plugin
+    usage and suggested configuration. This section should be of interest
+    to people wanting to use the API directly (e.g. new integrations).
+
+"""
+
+from __future__ import annotations
+
+import typing
+
+from importlib.util import find_spec
+
+from comver._version import Version, VersionCommit
+
+if typing.TYPE_CHECKING:
+    import git
+
+    from comver.type_definitions import OptionalStringsOrPatterns
+
+
+def pdm(  # noqa: PLR0913
+    message_includes: OptionalStringsOrPatterns = None,
+    message_excludes: OptionalStringsOrPatterns = None,
+    path_includes: OptionalStringsOrPatterns = None,
+    path_excludes: OptionalStringsOrPatterns = None,
+    author_name_includes: OptionalStringsOrPatterns = None,
+    author_name_excludes: OptionalStringsOrPatterns = None,
+    author_email_includes: OptionalStringsOrPatterns = None,
+    author_email_excludes: OptionalStringsOrPatterns = None,
+    major_regexes: OptionalStringsOrPatterns = None,
+    minor_regexes: OptionalStringsOrPatterns = None,
+    patch_regexes: OptionalStringsOrPatterns = None,
+    unrecognized_message: typing.Literal["ignore", "error"] | None = None,
+    repository: str | git.Repo | None = None,
+) -> str:
+    """Entrypoint for `pdm`'s `[tool.pdm.version]` `pyproject.toml` specifier.
+
+    Example `pyproject.toml` usage:
+
+    ```toml
+    [build-system]
+    build-backend = "pdm.backend"
+
+    requires = [
+        "comver>=0.1.0",
+        "pdm-backend>=2",
+    ]
+
+    [tool.pdm.version]
+    source = "call"
+    getter = "commition.plugin.pdm:git"
+    ```
+
+    This function uses
+    [`Version.from_git_configured`][comver._version.Version.from_git_configured]
+    under the hood, __but only outputs the last yielded version `iterable`__.
+
+    Tip:
+        Plugin can be configured by `[tool.comver]` section.
+
+    Args:
+        message_includes:
+            Commit message regexes against which the commit is included.
+            Default: From config OR all paths are included.
+        message_excludes:
+            Commit message regexes against which the commit is excluded.
+            Default: From config OR no paths are excluded.
+        path_includes:
+            Path regexes against which the commit is included.
+            Default: From config OR all paths are included.
+        path_excludes:
+            Path regexes against which the commit is excluded.
+            Default: From config OR no paths are excluded.
+        author_name_includes:
+            Commit author names regexes against
+            which the commit is included.
+            Default: From config OR all names are included.
+        author_name_excludes:
+            Commit author names regexes against
+            which the commit is excluded.
+            Default: From config OR no names are excluded.
+        author_email_includes:
+            Commit author email regexes against
+            which the commit is included.
+            Default: From config OR all emails are included.
+        author_email_excludes:
+            Commit author email regexes against
+            which the commit is excluded.
+            Default: From config OR no emails are excluded.
+        major_regexes:
+            The regexes by which the major version is found.
+            Default: From config OR matches `feat!:` and `fix!:`
+            messages OR `BREAKING CHANGE` anywhere in the message.
+        minor_regexes:
+            The regex for the minor version.
+            Default: From config OR matches messages starting with `feat:`.
+        patch_regexes:
+            The regex for the patch version.
+            Default: From config OR matches messages starting with `fix:`.
+        unrecognized_message:
+            The behavior for unrecognized messages. It can be
+            either "exclude" or "error".
+            Default: From config OR "ignore"
+        repository:
+            The `git` repository.
+            Default: From config OR will be searched
+            in the parent directories.
+
+    Returns:
+        Calculated version as string (compatible with `pdm` interface).
+
+    """
+    version = VersionCommit()
+    for version in Version.from_git_configured(  # noqa: B007
+        message_includes=message_includes,
+        message_excludes=message_excludes,
+        path_includes=path_includes,
+        path_excludes=path_excludes,
+        author_name_includes=author_name_includes,
+        author_name_excludes=author_name_excludes,
+        author_email_includes=author_email_includes,
+        author_email_excludes=author_email_excludes,
+        major_regexes=major_regexes,
+        minor_regexes=minor_regexes,
+        patch_regexes=patch_regexes,
+        unrecognized_message=unrecognized_message,
+        repository=repository,
+    ):
+        pass
+
+    return str(version.version)
+
+
+if find_spec("hatchling"):
+    from hatchling.plugin import hookimpl
+    from hatchling.version.source.plugin.interface import VersionSourceInterface
+
+    class ComverVersionSource(VersionSourceInterface):
+        """Get the project version for the `hatchling` build backend.
+
+        This class implements the `VersionSourceInterface` from Hatchling
+        and allows integration of the `comver` plugin with Hatch-based
+        projects.
+
+        Tip:
+            See [plugins](https://hatch.pypa.io/1.13/plugins/version-source/reference/)
+            for more information
+
+        This function uses
+        [`Version.from_git_configured`][comver._version.Version.from_git_configured]
+        under the hood, __but only outputs the last version
+        yielded from `iterable`__.
+
+        > [!IMPORTANT]
+        > Plugin can also be configured by `[tool.hatch.version]`, not only
+        > `[tool.comver`]. The former takes precedence if both exist.
+
+        """
+
+        PLUGIN_NAME: str = "comver"  # pyright: ignore [reportIncompatibleUnannotatedOverride]
+
+        def get_version_data(self) -> dict[str, str]:  # pyright: ignore [reportImplicitOverride]
+            """Get the version data to be used by Hatchling.
+
+            Returns:
+                A dictionary with the resolved version string,
+                under the "version" key.
+            """
+            version = VersionCommit()
+            for version in Version.from_git_configured(  # noqa: B007
+                message_includes=self.config.get("message_includes"),  # pyright: ignore [reportUnknownArgumentType]
+                message_excludes=self.config.get("message_excludes"),  # pyright: ignore [reportUnknownArgumentType]
+                path_includes=self.config.get("path_includes"),  # pyright: ignore [reportUnknownArgumentType]
+                path_excludes=self.config.get("path_excludes"),  # pyright: ignore [reportUnknownArgumentType]
+                author_name_includes=self.config.get("author_name_includes"),  # pyright: ignore [reportUnknownArgumentType]
+                author_name_excludes=self.config.get("author_name_excludes"),  # pyright: ignore [reportUnknownArgumentType]
+                author_email_includes=self.config.get("author_email_includes"),  # pyright: ignore [reportUnknownArgumentType]
+                author_email_excludes=self.config.get("author_email_excludes"),  # pyright: ignore [reportUnknownArgumentType]
+                repository=self.root,
+            ):
+                pass
+
+            return {"version": str(version.version)}
+
+        def set_version(  # pyright: ignore [reportIncompatibleMethodOverride, reportImplicitOverride]
+            self,
+            _: str,
+            __: dict[str, str],
+        ) -> typing.NoReturn:  # pragma: no cover
+            """Setting the version is not supported by the comver plugin.
+
+            This method exists to fulfill the interface, but always raises
+            `NotImplementedError`.
+
+            Args:
+                _:
+                    The version string (ignored).
+                __:
+                    Additional data (ignored).
+
+            Raises:
+                NotImplementedError:
+                    Always raised to indicate that setting the
+                    version is unsupported.
+            """
+            error = "comver plugin does not support setting the version."
+            raise NotImplementedError(error)
+
+    @hookimpl
+    def hatch_register_version_source() -> type[ComverVersionSource]:
+        """Automatically register hatchling plugin.
+
+        Note:
+            This function is called implicitly to register
+            `comver` for `hatchling` backend.
+
+        Returns:
+            ComverVersionSource class
+
+        """
+        return ComverVersionSource
+
+else:  # pragma: no cover
+    pass

comver/py.typed.license

@@ -0,0 +1,4 @@
+SPDX-FileCopyrightText: © 2025 open-nudge <https://github.com/open-nudge>
+SPDX-FileContributor: szymonmaszke <github@maszke.co>
+
+SPDX-License-Identifier: Apache-2.0

comver/type_definitions.py

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: © 2025 open-nudge <https://github.com/open-nudge>
+# SPDX-FileContributor: szymonmaszke <github@maszke.co>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Type definitions of `comver`.
+
+Important:
+    This module is a simplification for `typing` of complex types
+    and should be used __eventually__ by third party plugin developers.
+
+"""
+
+from __future__ import annotations
+
+import re
+
+from collections.abc import Iterable
+
+StringOrPattern = str | re.Pattern[str]
+"""Either `string` or compiled `re.Pattern`."""
+
+StringsOrPatterns = Iterable[StringOrPattern]
+"""Iterable of `StringOrPattern`."""
+
+OptionalStringsOrPatterns = Iterable[StringOrPattern] | None
+"""Iterable of `StringOrPattern` or `None`."""

comver-0.2.0.dist-info/METADATA

@@ -0,0 +1,329 @@
+Metadata-Version: 2.4
+Name: comver
+Version: 0.2.0
+Summary: Commit-based semantic versioning - highly configurable and tag-free.
+Author: open-nudge
+Maintainer: open-nudge
+License-Expression: Apache-2.0
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Project-URL: Changelog, https://github.com/open-nudge/comver/blob/master/CHANGELOG.md
+Project-URL: Documentation, https://open-nudge.github.io/comver
+Project-URL: Homepage, https://open-nudge.github.io/comver
+Project-URL: Issues, https://github.com/open-nudge/comver/issues
+Project-URL: Repository, https://github.com/open-nudge/comver
+Requires-Python: >=3.11
+Requires-Dist: loadfig>=0.1.0
+Requires-Dist: GitPython>=3
+Provides-Extra: hatchling
+Requires-Dist: hatchling>=1.27.0; extra == "hatchling"
+Description-Content-Type: text/markdown
+
+<!--
+SPDX-FileCopyrightText: © 2025 open-nudge <https://github.com/open-nudge>
+SPDX-FileContributor: szymonmaszke <github@maszke.co>
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# comver
+
+<!-- mkdocs remove start -->
+
+<!-- vale off -->
+
+<!-- pyml disable-num-lines 30 line-length-->
+
+<p align="center">
+    <em>Commit-based semantic versioning - highly configurable and tag-free.</em>
+</p>
+
+<div align="center">
+
+<a href="https://pypi.org/project/comver">![PyPI - Python Version](https://img.shields.io/pypi/v/comver?style=for-the-badge&label=release&labelColor=grey&color=blue)
+</a>
+<a href="https://pypi.org/project/comver">![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fopen-nudge%2Fcomver%2Fmain%2Fpyproject.toml&style=for-the-badge&label=python&labelColor=grey&color=blue)
+</a>
+<a href="https://opensource.org/licenses/Apache-2.0">![License](https://img.shields.io/badge/License-Apache_2.0-blue?style=for-the-badge)
+</a>
+<a>![Coverage Hardcoded](https://img.shields.io/badge/coverage-100%25-green?style=for-the-badge)
+</a>
+<a href="https://scorecard.dev/viewer/?uri=github.com/open-nudge/comver">![OSSF-Scorecard Score](https://img.shields.io/ossf-scorecard/github.com/open-nudge/comver?style=for-the-badge&label=OSSF)
+</a>
+
+</div>
+
+<p align="center">
+✨ <a href="#features">Features</a>
+🚀 <a href="#quick-start">Quick start</a>
+📚 <a href="https://open-nudge.github.io/comver">Documentation</a>
+🤝 <a href="#contribute">Contribute</a>
+👍 <a href="https://github.com/open-nudge/comver/blob/main/ADOPTERS.md">Adopters</a>
+📜 <a href="#legal">Legal</a>
+</p>
+<!-- vale on -->
+
+______________________________________________________________________
+
+<!-- mkdocs remove end -->
+
+## Features
+
+__comver__ is a tool for calculating __[semantic versioning](https://semver.org/)__
+of your project __using only commit messages__ - no tags required!
+
+- __Separation of concerns__: versioning focuses on technical aspects,
+    not marketing. You can now use tags solely for communication.
+- __Highly configurable__: include only relevant commits by filtering via
+    `message`, `author`, `email`, __or even commit path__.
+- __Immutable__: version is calculated directly from the commit history.
+    Tags can now be used more meaningfully (e.g., to mark a major milestone
+    or release).
+- __Batteries-included__: integrate with [pdm](https://pdm-project.org/en/latest/),
+    [Hatch](https://hatch.pypa.io/latest/) or [uv](https://docs.astral.sh/uv/).
+- __Verifiable__: verify that a specific version was generated from a
+    given commit chain - more resistant to tampering like
+    [dependency substitution attacks](https://docs.aws.amazon.com/codeartifact/latest/ug/dependency-substitution-attacks.html)
+
+## Why?
+
+Semantic versioning based on Git tags has a few limitations:
+
+- Teams may avoid bumping the `major` version due to the
+    perceived weight of the change.
+    [__Double versioning scheme__](https://open-nudge.github.io/comver/tutorials/why);
+    one version for technical changes, another for public releases is
+    a viable mitigation.
+- Tag creation by `bot`s (e.g. during automated releases) lead to problems
+    with `branch protection` (see [here](https://github.com/orgs/community/discussions/25305)).
+- Not all commits are relevant for release versions
+    (e.g., CI changes, bot updates, or tooling config),
+    yet many schemes count them in. With filtering, `comver` can exclude
+    such noise.
+- Tags are mutable by default and can be re-pointed. By calculating the version
+    based on commits, and combining it with the commit
+    `sha` and a config `checksum`, you get verifiable and reproducible results.
+
+## Quick start
+
+> [!NOTE]
+> You can jump straight into the action and check `comver`
+> [tutorials](https://open-nudge.github.io/comver/tutorials).
+
+### Installation
+
+```sh
+> pip install comver
+```
+
+### Calculate version
+
+> [!IMPORTANT]
+> Although written in Python, comver can be used
+> with any programming language.
+
+If your commits follow the Conventional Commits format, run:
+
+```sh
+> comver calculate
+```
+
+This will output a version string in the `MAJOR.MINOR.PATCH` format:
+
+```sh
+23.1.3 # Output
+```
+
+> [!IMPORTANT]
+> You can use [plugins](https://open-nudge.github.io/comver/tutorials/plugins)
+> to integrate this versioning scheme
+> with [`pdm`](https://github.com/pdm-project/pdm) or
+> [`hatch`](https://github.com/pypa/hatch). More below!
+
+<!-- mkdocs remove start -->
+
+### Configuration
+
+Configuration can be done either in `pyproject.toml`
+(recommended for `Python`-first project) or in a separate
+`.comver.toml` file (recommended for non-python projects):
+
+<table>
+<tr>
+<th>pyproject.toml</th>
+<th>.comver.toml</th>
+</tr>
+<tr>
+<td>
+
+```toml
+[tool.comver]
+# Only commits to these paths are considered
+path_includes = [
+  "src/*",
+  "pyproject.toml",
+]
+
+# Commits done by GitHub Actions bot are discarded
+author_name_excludes = [
+  "github-actions[bot]",
+]
+```
+
+</td>
+<td>
+
+```toml
+# No [tool.comver] needed here
+# Source only commits considered
+path_includes = [
+  "src/*",
+]
+
+# Commits messages with [no version] are discarded
+message_excludes = [
+  ".*\[no version\].*",
+  ".*\[skipversion\].*",
+]
+```
+
+</td>
+</tr>
+</table>
+
+> [!TIP]
+> See suggested configuration examples [here](https://open-nudge.github.io/comver/tutorials/configuration)
+
+### Integrations
+
+> [!NOTE]
+> You can use `comver` with [`uv`](https://github.com/astral-sh/uv)
+> by selecting the appropriate [build backend](https://docs.astral.sh/uv/concepts/build-backend/#choosing-a-build-backend),
+> such as `hatchling`.
+
+To integrate `comver` with [`pdm`](https://pdm-project.org/en/latest/)
+or [`hatch`](https://hatch.pypa.io/latest/) add the following to
+your `pyproject.toml`:
+
+<table>
+<tr>
+<th>PDM</th>
+<th>Hatch</th>
+</tr>
+<tr>
+<td>
+
+```toml
+# Register comver for the build process
+[build-system]
+build-backend = "pdm.backend"
+
+requires = [
+  "pdm-backend",
+  "comver>=0.1.0",
+]
+
+# Setup versioning for PDM
+[tool.pdm.version]
+source = "call"
+getter = "comver.plugin:pdm"
+
+# Comver-specific settings
+[tool.comver]
+...
+```
+
+</td>
+<td>
+
+```toml
+# Register comver for the build process
+[build-system]
+build-backend = "hatchling.build"
+
+requires = [
+  "comver>=0.1.0",
+  "hatchling",
+]
+
+# Setup versioning for Hatchling
+[tool.hatch.version]
+source = "comver"
+
+
+# Comver-specific settings
+[tool.comver]
+...
+```
+
+</td>
+</tr>
+</table>
+
+> [!TIP]
+> See more in the [documentation](https://open-nudge.github.io/comver/tutorials/plugins)
+
+### Verification
+
+To verify that a version was produced from the same Git tree and configuration,
+first use the calculate command with additional flags:
+
+```sh
+comver calculate --sha --checksum
+```
+
+This outputs three space-separated values:
+
+```sh
+<VERSION> <SHA> <CHECKSUM>
+```
+
+> [!TIP]
+> Append `--format=json` for machine-friendly output
+
+Before the next release provide these values to the `comver verify`
+to ensure the version was previously generated from the
+same codebase and config:
+
+```sh
+comver verify <VERSION> <SHA> <CHECKSUM>
+```
+
+If inconsistencies are found, you'll receive feedback, for example:
+
+> Provided checksum and the checksum of configuration do not match.
+
+> [!TIP]
+> Explore verification workflows in the [tutorials](https://open-nudge.github.io/comver/tutorials/verification)
+
+<!-- md-dead-link-check: off -->
+
+## Contribute
+
+We welcome your contributions! Start here:
+
+- [Code of Conduct](/CODE_OF_CONDUCT.md)
+- [Contributing Guide](/CONTRIBUTING.md)
+- [Roadmap](/ROADMAP.md)
+- [Changelog](/CHANGELOG.md)
+- [Report security vulnerabilities](/SECURITY.md)
+- [Open an Issue](https://github.com/open-nudge/comver/issues)
+
+## Legal
+
+- This project is licensed under the _Apache 2.0 License_ - see
+    the [LICENSE](/LICENSE.md) file for details.
+- This project is copyrighted by _open-nudge_ - the
+    appropriate copyright notice is included in each file.
+
+<!-- mkdocs remove end -->
+
+<!-- md-dead-link-check: on -->