tag_formatter

Callback to be used for formatting a tag name before template substitution.

Note

This option is completely ignored if Read some file content as current version or Execute some callback function to get current version schemas are used. Please set up your VERSION file or callback to return proper version in the first place.

Type

str or callable

Default value

None

Usage

It is possible to use (see Release is a git tag) tag name in version number.

But tags should have PEP 440 compatible name, like:

  • 1.2

  • 1.2.3

  • 1.2.3a4

  • 1.2.3b4

  • 1.2.3rc4

  • 1.2.3.pre4

  • 1.2.3.post4

  • 1.2.3.dev4

In case of using tag names like release/1.2.3 or rc-1.2, you’ll get version number which pip cannot understand.

To fix that you can define a callback which will receive current tag name and return a properly formatted one:

  • mypkg/util.py file:

    import re
    
    
    def format_tag_name(name):
        # If tag has name like "release/1.2.3", take only "1.2.3" part
        pattern = re.compile(r"release\/(?P<tag>[^\d.]+)")
    
        match = pattern.search(name)
        if match:
            return match.group("tag")
    
        # just left properly named tages intact
        if name.startswith("v"):
            return name
    
        # fail in case of wrong tag names like "release/unknown"
        raise ValueError(f"Wrong tag name: {name}")
    
  • setup.py file:

    from mypkg.util import format_tag_name
    
    setuptools.setup(
        ...,
        setuptools_git_versioning={
            "enabled": True,
            "dev_template": "{tag}.dev{ccount}",
            "dirty_template": "{tag}.dev{ccount}",
            "tag_formatter": format_tag_name,
        },
    )
    
  • pyproject.toml file:

    [build-system]
    # __legacy__ is required to have access to package
    # during build step
    build-backend = "setuptools.build_meta:__legacy__"
    
    [tool.setuptools-git-versioning]
    enabled = true
    dev_template = "{tag}.dev{ccount}"
    dirty_template = "{tag}.dev{ccount}"
    tag_formatter = "mypkg.util:format_tag_name"
    

    Note

    Please pay attention to build-backend item in your config, it is important for setuptools-git-versioning to access your module source code.

Possible values

  • None

    Disables this feature

  • function/lambda (setup.py only)

  • function full name in format "some.module:function_name"

    Function should have signature (str) -> str. It accepts original tag name and returns formatted one

    Warning

    Exception will be raised if module or function/lambda is missing or has invalid signature

  • regexp like ".*(?P<tag>\d+).*"

    Regexp should have capture group named "tag" matching the expected tag name

    Warning

    Exception will be raised if regexp is invalid or does not have expected capture group

    Warning

    Exception will also be raised if tag name does not match regexp. So this regexp should be able to handle all possible tags in the repo