api.rst

versioningit

Library API

High-Level Functions

get_version

get_next_version

get_cmdclasses

2.2.0

A custom subclass of setuptools.command.sdist.sdist that runs the onbuild step when building an sdist. This class is equivalent to get_cmdclasses()["sdist"], except that it can also be used in the [options]cmdclass field in setup.cfg.

2.2.0

A custom subclass of setuptools.command.build_py.build_py that runs the onbuild step when building a wheel. This class is equivalent to get_cmdclasses()["build_py"], except that it can also be used in the [options]cmdclass field in setup.cfg.

Note

When importing or referring to the sdist and build_py command classes, the .cmdclass submodule needs to be specified; unlike the rest of the library API, they are not importable directly from versioningit.

[options]
cmdclass =
    # Right!
    sdist = versioningit.cmdclass.sdist
    build_py = versioningit.cmdclass.build_py

[options]
cmdclass =
    # Wrong!
    sdist = versioningit.sdist
    build_py = versioningit.build_py

Low-Level Class

Versioningit()

Exceptions

Error

ConfigError

InvalidTagError

InvalidVersionError

MethodError

NoTagError

NotSdistError

NotVCSError

NotVersioningitError

Utilities

VCSDescription

Report

FallbackReport

get_version_from_pkg_info

run_onbuild

get_template_fields_from_distribution

Passing Explicit Configuration

The functions & methods that take a path to a project directory normally read the project's configuration from the pyproject.toml file therein, but they can also be passed a config argument to take the configuration from instead, in which case pyproject.toml will be ignored and need not even exist.

A config argument must be a dict whose structure mirrors the structure of the [tool.versioningit] table in pyproject.toml. For example, the following TOML configuration:

[tool.versioningit.vcs]
method = "git"
match = ["v*"]

[tool.versioningit.next-version]
method = { module = "setup", value = "my_next_version" }

[tool.versioningit.format]
distance = "{next_version}.dev{distance}+{vcs}{rev}"
dirty = "{base_version}+dirty"
distance-dirty = "{next_version}.dev{distance}+{vcs}{rev}.dirty"

corresponds to the following Python config value:

{
    "vcs": {
        "method": "git",
        "match": ["v*"],
    },
    "next-version": {
        "method": {
            "module": "setup",
            "value": "my_next_version",
        },
    },
    "format": {
        "distance": "{next_version}.dev{distance}+{vcs}{rev}",
        "dirty": "{base_version}+dirty",
        "distance-dirty": "{next_version}.dev{distance}+{vcs}{rev}.dirty",
    },
}

This is the same structure that you would get by reading from the pyproject.toml file like so:

import tomli

with open("pyproject.toml", "rb") as fp:
    config = tomli.load(fp)["tool"]["versioningit"]

When passing versioningit configuration as a config argument, an alternative way to specify methods becomes available: in place of a method specification, one can pass a callable object directly.