Skip to content

Version source plugins

Known third-party

  • hatch-vcs - uses your preferred version control system (like Git)

Built-in

Regex

See the documentation for versioning.

Updates

Setting the version is supported.

Configuration

The version source plugin name is regex.

[tool.hatch.version]
source = "regex"

[version]
source = "regex"
Options
Option Description
path (required) A relative path to a file containing the project's version
pattern A regular expression that has a named group called version that represents the version

Code

Updates

Setting the version is not supported.

Configuration

The version source plugin name is code.

[tool.hatch.version]
source = "code"

[version]
source = "code"
Options
Option Description
path (required) A relative path to a Python file that will be loaded
expression A Python expression that when evaluated in the context of the loaded file returns the version. The default expression is simply __version__.

VersionSourceInterface (ABC)

Example usage:

from hatchling.version.source.plugin.interface import VersionSourceInterface


class SpecialVersionSource(VersionSourceInterface):
    PLUGIN_NAME = 'special'
    ...

from hatchling.plugin import hookimpl

from .plugin import SpecialVersionSource


@hookimpl
def hatch_register_version_source():
    return SpecialVersionSource
Source code in hatchling/version/source/plugin/interface.py 
class VersionSourceInterface(ABC):  # no cov
    """
    Example usage:

    === ":octicons-file-code-16: plugin.py"

        ```python
        from hatchling.version.source.plugin.interface import VersionSourceInterface


        class SpecialVersionSource(VersionSourceInterface):
            PLUGIN_NAME = 'special'
            ...
        ```

    === ":octicons-file-code-16: hooks.py"

        ```python
        from hatchling.plugin import hookimpl

        from .plugin import SpecialVersionSource


        @hookimpl
        def hatch_register_version_source():
            return SpecialVersionSource
        ```
    """

    PLUGIN_NAME = ''
    """The name used for selection."""

    def __init__(self, root, config):
        self.__root = root
        self.__config = config

    @property
    def root(self):
        """
        The root of the project tree as a string.
        """
        return self.__root

    @property
    def config(self):
        """
        === ":octicons-file-code-16: pyproject.toml"

            ```toml
            [tool.hatch.version]
            ```

        === ":octicons-file-code-16: hatch.toml"

            ```toml
            [version]
            ```
        """
        return self.__config

    @abstractmethod
    def get_version_data(self) -> dict:
        """
        This should return a mapping with a `version` key representing the current version of the project and will be
        displayed when invoking the [`version`](../cli/reference.md#hatch-version) command without any arguments.

        The mapping can contain anything else and will be passed to
        [set_version](version-source.md#hatchling.version.source.plugin.interface.VersionSourceInterface.set_version)
        when updating the version.
        """

    def set_version(self, version: str, version_data: dict):
        """
        This should update the version to the first argument with the data provided during retrieval.
        """
        raise NotImplementedError

PLUGIN_NAME

The name used for selection.

config property readonly 

[tool.hatch.version]

[version]

root property readonly

The root of the project tree as a string.

get_version_data(self) -> dict

This should return a mapping with a version key representing the current version of the project and will be displayed when invoking the version command without any arguments.

The mapping can contain anything else and will be passed to set_version when updating the version.

Source code in hatchling/version/source/plugin/interface.py 
@abstractmethod
def get_version_data(self) -> dict:
    """
    This should return a mapping with a `version` key representing the current version of the project and will be
    displayed when invoking the [`version`](../cli/reference.md#hatch-version) command without any arguments.

    The mapping can contain anything else and will be passed to
    [set_version](version-source.md#hatchling.version.source.plugin.interface.VersionSourceInterface.set_version)
    when updating the version.
    """

set_version(self, version: str, version_data: dict)

This should update the version to the first argument with the data provided during retrieval.

Source code in hatchling/version/source/plugin/interface.py 
def set_version(self, version: str, version_data: dict):
    """
    This should update the version to the first argument with the data provided during retrieval.
    """
    raise NotImplementedError
Last update: February 17, 2022