Library API

High-Level Functions

versioningit.get_version(project_dir: Union[str, pathlib.Path] = '.', config: Optional[dict] = None, write: bool = False, fallback: bool = True) → str

Determine the version for the project at project_dir.

If config is None, then project_dir must contain a pyproject.toml file containing a [tool.versioningit] table; if it does not, a NotVersioningitError is raised. If config is not None, then any pyproject.toml file 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 [tool.versioningit.write] subtable, 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.

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

• NotVersioningitError –

  • if config is None and project_dir does not contain a pyproject.toml file

  • if the pyproject.toml file does not contain a [tool.versioningit] 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: Union[str, pathlib.Path] = '.', config: Optional[dict] = None) → str

New 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 pyproject.toml file containing a [tool.versioningit] table; if it does not, a NotVersioningitError is raised. If config is not None, then any pyproject.toml file in project_dir will be ignored, and the configuration will be taken from config instead; see “Passing Explicit Configuration”.

Raises

• NotVCSError – if project_dir is not under version control

• NotVersioningitError –

  • if config is None and project_dir does not contain a pyproject.toml file

  • if the pyproject.toml file does not contain a [tool.versioningit] 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: Optional[Dict[str, Type[Command]]] = None) → Dict[str, Type[Command]]

New 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.

Low-Level Class

class versioningit.Versioningit

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: Union[str, pathlib.Path] = '.', config: Optional[dict] = None) → versioningit.core.Versioningit

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 pyproject.toml file containing a [tool.versioningit] table; if it does not, a NotVersioningitError is raised. If config is not None, then any pyproject.toml file in project_dir will be ignored, and the configuration will be taken from config instead. See “Passing Explicit Configuration”.

Raises

• NotVersioningitError –

  • if config is None and project_dir does not contain a pyproject.toml file

  • if config is None and the pyproject.toml file does not contain a [tool.versioningit] table

• ConfigError – if the tool.versioningit key, config, or any subfields are not of the correct type

get_version() → str

Determine the version for project_dir

Raises

MethodError – if a method returns a value of the wrong type

do_vcs() → versioningit.core.VCSDescription

Run the vcs step

Raises

MethodError – if the method does not return a VCSDescription

do_tag2version(tag: str) → str

Run the tag2version step

Raises

MethodError – if the method does not return a str

do_next_version(version: str, branch: Optional[str]) → str

Run the next-version step

Raises

MethodError – if the method does not return a str

do_format(description: versioningit.core.VCSDescription, version: str, next_version: str) → str

Run the format step

Raises

MethodError – if the method does not return a str

do_write(version: str) → None

Run the write step

do_onbuild(build_dir: Union[str, pathlib.Path], is_source: bool, version: str) → None

New in version 1.1.0.

Run the onbuild step

Exceptions

exception versioningit.Error

Base class of all versioningit-specific errors

exception versioningit.ConfigError

Bases: versioningit.errors.Error, ValueError

Raised when the versioningit configuration contain invalid settings

exception versioningit.InvalidTagError

Bases: versioningit.errors.Error, ValueError

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

exception versioningit.InvalidVersionError

Bases: versioningit.errors.Error, ValueError

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

exception versioningit.MethodError

Bases: versioningit.errors.Error

Raised when a method is invalid or returns an invalid value

exception versioningit.NoTagError

Bases: versioningit.errors.Error

Raised when a tag cannot be found in version control

exception versioningit.NotSdistError

Bases: versioningit.errors.Error

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

exception versioningit.NotVCSError

Bases: versioningit.errors.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

Bases: versioningit.errors.Error

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

Utilities

class versioningit.VCSDescription(tag: str, state: str, branch: Optional[str], fields: Dict[str, Any])

A description of the state of a version control repository

branch: Optional[str]

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 [tool.versioningit.format] subtable. 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

versioningit.get_version_from_pkg_info(project_dir: Union[str, pathlib.Path]) → str

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: Union[str, pathlib.Path], is_source: bool, version: str, project_dir: Union[str, pathlib.Path] = '.', config: Optional[dict] = None) → None

New in version 1.1.0.

Run the onbuild step for the given project.

If config is None, then project_dir must contain a pyproject.toml file containing a [tool.versioningit] table; if it does not, a NotVersioningitError is raised. If config is not None, then any pyproject.toml file in project_dir will be ignored, and the configuration will be taken from config instead; see “Passing Explicit Configuration”.

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

• version – The project’s version

Raises

• NotVersioningitError –

  • if config is None and project_dir does not contain a pyproject.toml file

  • if the pyproject.toml file does not contain a [tool.versioningit] 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

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 = "{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": "{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.