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
isNone
, thenproject_dir
must contain apyproject.toml
file containing either a[tool.versioningit]
table or a[tool.hatch.version]
table with thesource
key set to"versioningit"
; if it does not, aNotVersioningitError
is raised. Ifconfig
is notNone
, then anypyproject.toml
file inproject_dir
will be ignored, and the configuration will be taken fromconfig
instead. See “Passing Explicit Configuration”.If
write
is true, then the file specified in thewrite
subtable of the versioningit configuration, if any, will be updated.If
fallback
is true, then ifproject_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 thePKG-INFO
file.- Raises:
NotVCSError – if
fallback
is false andproject_dir
is not under version controlNotSdistError – if
fallback
is true,project_dir
is not under version control, and there is noPKG-INFO
file inproject_dir
ConfigError – if any of the values in
config
are not of the correct typeMethodError – 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
isNone
, thenproject_dir
must contain apyproject.toml
file containing either a[tool.versioningit]
table or a[tool.hatch.version]
table with thesource
key set to"versioningit"
; if it does not, aNotVersioningitError
is raised. Ifconfig
is notNone
, then anypyproject.toml
file inproject_dir
will be ignored, and the configuration will be taken fromconfig
instead. See “Passing Explicit Configuration”.- Raises:
NotVCSError – if
project_dir
is not under version controlConfigError – if any of the values in
config
are not of the correct typeMethodError – 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 setuptoolsCommand
classes, suitable for passing to thecmdclass
argument ofsetuptools.setup()
, that run theonbuild
step for the project when building an sdist or wheel. Specifically, thedict
contains a subclass ofsetuptools.command.sdist.sdist
at the"sdist"
key and a subclass ofsetuptools.command.build_py.build_py
at the"build_py"
key.A
dict
of alternative base classes can optionally be supplied; if thedict
contains an"sdist"
entry, that entry will be used as the base class for the customizedsdist
command, and likewise for"build_py"
. All other classes in the inputdict
are passed through unchanged.
- class versioningit.cmdclass.sdist
Added in version 2.2.0.
A custom subclass of
setuptools.command.sdist.sdist
that runs theonbuild
step when building an sdist. This class is equivalent toget_cmdclasses()["sdist"]
, except that it can also be used in the[options]cmdclass
field insetup.cfg
.
- class versioningit.cmdclass.build_py
Added in version 2.2.0.
A custom subclass of
setuptools.command.build_py.build_py
that runs theonbuild
step when building a wheel. This class is equivalent toget_cmdclasses()["build_py"]
, except that it can also be used in the[options]cmdclass
field insetup.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 atproject_dir
(default: the current directory).If
config
isNone
, thenproject_dir
must contain apyproject.toml
file containing either a[tool.versioningit]
table or a[tool.hatch.version]
table with thesource
key set to"versioningit"
; if it does not, aNotVersioningitError
is raised. Ifconfig
is notNone
, then anypyproject.toml
file inproject_dir
will be ignored, and the configuration will be taken fromconfig
instead. See “Passing Explicit Configuration”.- Raises:
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 thewrite
subtable of the versioningit configuration, if any, will be updated.If
fallback
is true, then ifproject_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 thePKG-INFO
file.Changed in version 2.0.0:
write
andfallback
arguments added- Raises:
NotVCSError – if
fallback
is false andproject_dir
is not under version controlNotSdistError – if
fallback
is true,project_dir
is not under version control, and there is noPKG-INFO
file inproject_dir
ConfigError – if any of the values in
config
are not of the correct typeMethodError – 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 thewrite
subtable of the versioningit configuration, if any, will be updated.If
fallback
is true, then ifproject_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 thePKG-INFO
file, returning aFallbackReport
instance instead of aReport
.- Raises:
NotVCSError – if
fallback
is false andproject_dir
is not under version controlNotSdistError – if
fallback
is true,project_dir
is not under version control, and there is noPKG-INFO
file inproject_dir
ConfigError – if any of the values in
config
are not of the correct typeMethodError – 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
stepChanged in version 2.0.0: The
version
argument was renamed tobase_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
stepChanged in version 2.0.0:
version
argument replaced withtemplate_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
stepChanged in version 2.0.0:
version
argument replaced withtemplate_fields
Changed in version 3.0.0:
build_dir
argument replaced withfile_provider
Exceptions
- 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
andtemplate-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
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 theformat
method. Customvcs
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 theformat
subtable of the versioningit configuration. Recommended values are"distance"
,"dirty"
, and"distance-dirty"
.
- 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
- 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
- versioningit.get_version_from_pkg_info(project_dir: str | Path) str [source]
Return the Version field from the
PKG-INFO
file inproject_dir
- Raises:
NotSdistError – if there is no
PKG-INFO
fileValueError – 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 theonbuild
step. Thetemplate_fields
value can be obtained by passing a command class’sdistribution
attribute toget_template_fields_from_distribution()
; if this returnsNone
, then we are building from an sdist, andrun_onbuild()
should not be called.If
config
isNone
, thenproject_dir
must contain apyproject.toml
file containing a[tool.versioningit]
table; if it does not, aNotVersioningitError
is raised. Ifconfig
is notNone
, then anypyproject.toml
file inproject_dir
will be ignored, and the configuration will be taken fromconfig
instead; see “Passing Explicit Configuration”.Changed in version 2.0.0:
version
argument replaced withtemplate_fields
- Parameters:
- Raises:
if
config
isNone
andproject_dir
does not contain apyproject.toml
fileif the
pyproject.toml
file does not contain a[tool.versioningit]
table
ConfigError – if any of the values in
config
are not of the correct typeMethodError – 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
byversioningit
’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, andNone
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 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.