Library API

High-Level Functions and Classes

versioningit.get_version(project_dir: str | Path = '.', config: dict | None = None, write: bool = False, fallback: bool = True) → str[source]

Determine the version for the project at project_dir.

If config is None, then project_dir must contain a versioningit.toml or pyproject.toml file; if both files are present, the versioningit.toml file is used. This file must then contain either a [tool.versioningit] table or a [tool.hatch.version] table with the source key set to "versioningit"; if it does not, a NoConfigSectionError is raised. If config is not None, then any configuration files in project_dir will be ignored, and the configuration will be taken from config instead. See “Passing Explicit Configuration”.

If write is true, then the file specified in the write subtable of the versioningit configuration, if any, will be updated.

If fallback is true, then if project_dir is not under version control (or if the VCS executable is not installed), versioningit will assume that the directory is an unpacked sdist and will read the version from the PKG-INFO file.

Changed in version 3.2.0: A versioningit.toml file can now be read in place of pyproject.toml

Raises:

NotVCSError – if fallback is false and project_dir is not under version control
NotSdistError – if fallback is true, project_dir is not under version control, and there is no PKG-INFO file in project_dir
NoConfigFileError – if config is None and project_dir does not contain a pyproject.toml or versioningit.toml file
NoConfigSectionError – if config is None and the configuration file does not contain a versioningit configuration table
ConfigError – if any of the values in config are not of the correct type
MethodError – if a method returns a value of the wrong type

versioningit.get_next_version(project_dir: str | Path = '.', config: dict | None = None) → str[source]

Added in version 0.3.0.

Determine the next version after the current VCS-tagged version for project_dir.

If config is None, then project_dir must contain a versioningit.toml or pyproject.toml file; if both files are present, the versioningit.toml file is used. This file must then contain either a [tool.versioningit] table or a [tool.hatch.version] table with the source key set to "versioningit"; if it does not, a NoConfigSectionError is raised. If config is not None, then any configuration files in project_dir will be ignored, and the configuration will be taken from config instead. See “Passing Explicit Configuration”.

Changed in version 3.2.0: A versioningit.toml file can now be read in place of pyproject.toml

Raises:

NotVCSError – if project_dir is not under version control
NoConfigFileError – if config is None and project_dir does not contain a pyproject.toml or versioningit.toml file
NoConfigSectionError – if config is None and the configuration file does not contain a versioningit configuration table
ConfigError – if any of the values in config are not of the correct type
MethodError – if a method returns a value of the wrong type

versioningit.get_cmdclasses(bases: dict[str, type[Command]] | None = None) → dict[str, type[Command]][source]

Added in version 1.1.0.

Return a dict of custom setuptools Command classes, suitable for passing to the cmdclass argument of setuptools.setup(), that run the onbuild step for the project when building an sdist or wheel. Specifically, the dict contains a subclass of setuptools.command.sdist.sdist at the "sdist" key and a subclass of setuptools.command.build_py.build_py at the "build_py" key.

A dict of alternative base classes can optionally be supplied; if the dict contains an "sdist" entry, that entry will be used as the base class for the customized sdist command, and likewise for "build_py". All other classes in the input dict are passed through unchanged.

class versioningit.cmdclass.sdist: Added in version 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.

class versioningit.cmdclass.build_py: Added in version 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

class versioningit.Versioningit[source]

A class for getting a version-controlled project’s current version based on its most recent tag and the difference therefrom

classmethod from_project_dir(project_dir: str | Path = '.', config: dict | None = None) → Versioningit[source]

Construct a Versioningit object for the project rooted at project_dir (default: the current directory).

If config is None, then project_dir must contain a versioningit.toml or pyproject.toml file; if both files are present, the versioningit.toml file is used. This file must then contain either a [tool.versioningit] table or a [tool.hatch.version] table with the source key set to "versioningit"; if it does not, a NoConfigSectionError is raised. If config is not None, then any configuration files in project_dir will be ignored, and the configuration will be taken from config instead. See “Passing Explicit Configuration”.

Changed in version 3.2.0: A versioningit.toml file can now be read in place of pyproject.toml

Raises:

NoConfigFileError – if config is None and project_dir does not contain a pyproject.toml or versioningit.toml file
NoConfigSectionError – if config is None and the configuration file does not contain a versioningit configuration table
ConfigError – if the configuration object/table or any of its subfields are not of the correct type

get_version(write: bool = False, fallback: bool = True) → str[source]

Determine the version for the project.

If write is true, then the file specified in the write subtable of the versioningit configuration, if any, will be updated.

If fallback is true, then if project_dir is not under version control (or if the VCS executable is not installed), versioningit will assume that the directory is an unpacked sdist and will read the version from the PKG-INFO file.

Changed in version 2.0.0: write and fallback arguments added

Raises:

NotVCSError – if fallback is false and project_dir is not under version control
NotSdistError – if fallback is true, project_dir is not under version control, and there is no PKG-INFO file in project_dir
ConfigError – if any of the values in config are not of the correct type
MethodError – if a method returns a value of the wrong type

run(write: bool = False, fallback: bool = True) → Report | FallbackReport[source]

Added in version 2.0.0.

Run all of the steps for the project — aside from “onbuild” and, optionally, “write” — and return an object containing the final version and intermediate values.

If write is true, then the file specified in the write subtable of the versioningit configuration, if any, will be updated.

If fallback is true, then if project_dir is not under version control (or if the VCS executable is not installed), versioningit will assume that the directory is an unpacked sdist and will read the version from the PKG-INFO file, returning a FallbackReport instance instead of a Report.

Raises:

NotVCSError – if fallback is false and project_dir is not under version control
NotSdistError – if fallback is true, project_dir is not under version control, and there is no PKG-INFO file in project_dir
ConfigError – if any of the values in config are not of the correct type
MethodError – if a method returns a value of the wrong type

do_vcs() → VCSDescription[source]

Run the vcs step

Raises:: MethodError – if the method does not return a VCSDescription

do_tag2version(tag: str) → str[source]

Run the tag2version step

Raises:: MethodError – if the method does not return a str

do_next_version(version: str, branch: str | None) → str[source]

Run the next-version step

Raises:: MethodError – if the method does not return a str

do_format(description: VCSDescription, base_version: str, next_version: str) → str[source]

Run the format step

Changed in version 2.0.0: The version argument was renamed to base_version.

Raises:: MethodError – if the method does not return a str

do_template_fields(version: str, description: VCSDescription | None, base_version: str | None, next_version: str | None) → dict[source]

Added in version 2.0.0.

Run the template_fields step

Raises:: MethodError – if the method does not return a dict

do_write(template_fields: dict[str, Any]) → None[source]: Run the write step

Changed in version 2.0.0: version argument replaced with template_fields

do_onbuild(file_provider: OnbuildFileProvider, is_source: bool, template_fields: dict[str, Any]) → None[source]: Added in version 1.1.0.

Run the onbuild step

Changed in version 2.0.0: version argument replaced with template_fields

Changed in version 3.0.0: build_dir argument replaced with file_provider

Exceptions

exception versioningit.Error[source]: Base class of all versioningit-specific errors

exception versioningit.ConfigError[source]

Bases: Error, ValueError

Raised when the versioningit configuration contain invalid settings

exception versioningit.InvalidTagError[source]

Bases: Error, ValueError

Raised by tag2version methods when passed a tag that they cannot work with

exception versioningit.InvalidVersionError[source]

Bases: Error, ValueError

Raised by next-version and template-fields methods when passed a version that they cannot work with

exception versioningit.MethodError[source]

Bases: Error

Raised when a method is invalid or returns an invalid value

exception versioningit.NoTagError[source]

Bases: Error

Raised when a tag cannot be found in version control

exception versioningit.NotSdistError[source]

Bases: Error

Raised when attempting to read a PKG-INFO file from a directory that doesn’t have one

exception versioningit.NotVCSError[source]

Bases: Error

Raised when versioningit is run in a directory that is not under version control or when the relevant VCS program is not installed

exception versioningit.NotVersioningitError[source]

Bases: Error

Raised when versioningit is used on a project that does not have versioningit enabled

exception versioningit.NoConfigFileError(project_dir: Path)[source]

Bases: NotVersioningitError

Added in version 3.2.0.

Raised when versioningit is used on a project that does not contain a versioningit.toml or pyproject.toml file

project_dir: Path: The path to the project directory

exception versioningit.NoConfigSectionError(config_path: Path)[source]

Bases: NotVersioningitError

Added in version 3.2.0.

Raised when versioningit is used on a project whose versioningit.toml or pyproject.toml file does not contain a versioningit configuration table

config_path: Path: The path to the configuration file

Utilities

class versioningit.VCSDescription(tag: str, state: str, branch: str | None, fields: dict[str, Any])[source]

A description of the state of a version control repository

branch: str | None: The name of the repository’s current branch, or None if it cannot be determined or does not apply

fields: dict[str, Any]: A dict of additional information about the repository state to make available to the format method. Custom vcs methods are advised to adhere closely to the set of fields used by the built-in methods.

state: str: The relationship of the repository’s current state to the tag. If the repository state is exactly the tagged state, this field should equal "exact"; otherwise, it will be a string that will be used as a key in the format subtable of the versioningit configuration. Recommended values are "distance", "dirty", and "distance-dirty".

tag: str: The name of the most recent tag in the repository (possibly after applying any match or exclusion rules based on user parameters) from which the current repository state is descended

class versioningit.Report(version: str, description: VCSDescription | None, base_version: str | None, next_version: str | None, template_fields: dict[str, Any], using_default_version: bool)[source]

Added in version 2.0.0.

A report of the intermediate & final values calculated during a versioningit run

base_version: str | None: A version string extracted from the VCS tag; None if the “tag2version” step or a previous step failed

description: VCSDescription | None: A description of the state of the version control repository; None if the “vcs” step failed

next_version: str | None: A “next version” calculated by the “next-version” step; None if the step or a previous one failed

template_fields: dict[str, Any]: A dict of fields for use in templating by the “write” and “onbuild” steps

using_default_version: bool: True iff an error occurred during version calculation, causing a default-version setting to be used

version: str: The final version

class versioningit.FallbackReport(version: str)[source]

Added in version 2.0.0.

A report of the version extracted from a PKG-INFO file in an sdist

version: str: The version

versioningit.get_version_from_pkg_info(project_dir: str | Path) → str[source]

Return the Version field from the PKG-INFO file in project_dir

Raises:

NotSdistError – if there is no PKG-INFO file
ValueError – if the PKG-INFO file does not contain a Version field

versioningit.run_onbuild(*, build_dir: str | Path, is_source: bool, template_fields: dict[str, Any], project_dir: str | Path = '.', config: dict | None = None) → None[source]

Added in version 1.1.0.

Run the onbuild step for the given setuptools project.

This function is intended to be used by custom setuptools command classes that are used in place of versioningit’s command classes but still need to be able to run the onbuild step. The template_fields value can be obtained by passing a command class’s distribution attribute to get_template_fields_from_distribution(); if this returns None, then we are building from an sdist, and run_onbuild() should not be called.

If config is None, then project_dir must contain a versioningit.toml or pyproject.toml file; if both files are present, the versioningit.toml file is used. This file must then contain either a [tool.versioningit] table or a [tool.hatch.version] table with the source key set to "versioningit"; if it does not, a NoConfigSectionError is raised. If config is not None, then any configuration files in project_dir will be ignored, and the configuration will be taken from config instead. See “Passing Explicit Configuration”.

Changed in version 2.0.0: version argument replaced with template_fields

Changed in version 3.2.0: A versioningit.toml file can now be read in place of pyproject.toml

Parameters:

build_dir – The directory containing the in-progress build
is_source – Set to True if building an sdist or other artifact that preserves source paths, False if building a wheel or other artifact that uses installation paths
template_fields – A dict of fields to be used when templating

Raises:

NoConfigFileError – if config is None and project_dir does not contain a pyproject.toml or versioningit.toml file
NoConfigSectionError – if config is None and the configuration file does not contain a versioningit configuration table
ConfigError – if any of the values in config are not of the correct type
MethodError – if a method returns a value of the wrong type

versioningit.get_template_fields_from_distribution(dist: Distribution) → dict[str, Any] | None[source]: Extract the template fields (calculated by the “template-fields” step) that were stashed on the setuptools.Distribution by versioningit’s setuptools hook, for passing to the “onbuild” step. If setuptools is building from an sdist instead of a repository, no template fields will have been calculated, and None will be returned, indicating that the “onbuild” step should not be run.

Passing Explicit Configuration

The functions & methods that take a path to a project directory normally read the project’s configuration from the versioningit.toml or pyproject.toml file therein, but they can also be passed a config argument to take the configuration from instead, in which case any configuration files 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.