Writing Your Own Methods
Changed in version 1.0.0: User parameters, previously passed as keyword arguments, are now passed as
a single params argument.
If you need to customize how a versioningit step is carried out, you can
write a custom function in a Python module in your project directory and point
versioningit to that function as described under
“Specifying the Method”.
When a custom function is called, it will be passed a step-specific set of
arguments, as documented below, plus all of the parameters specified in the
step’s subtable in pyproject.toml. (The arguments are passed as
keyword arguments, so custom methods need to give them the same names as
documented here.) For example, given the below configuration:
[tool.versioningit.vcs]
method = { module = "ving_methods", value = "my_vcs", module-dir = "tools" }
tag-dir = "tags"
annotated-only = true
versioningit will carry out the vcs step by calling my_vcs() in
ving_methods.py in the tools/ directory with the arguments
project_dir (set to the directory in which the pyproject.toml file
is located) and params={"tag-dir": "tags", "annotated-only": True}.
If a user-supplied parameter to a method is invalid, the method should raise a
versioningit.errors.ConfigError. If a method is passed a parameter that it
does not recognize, it should ignore it.
If you choose to store your custom methods in your setup.py, be sure to
place the call to setup() under an if __name__ == "__main__": guard so
that the module can be imported without executing setup().
If you store your custom methods in a module other than setup.py that
is not part of the project’s Python package (e.g., if the module is stored in a
tools/ directory), you need to ensure that the module is included in
your project’s sdists but not in wheels.
If your custom method depends on any third-party libraries, they must be listed
in your project’s build-system.requires.
vcs
A custom vcs method is a callable with the following synopsis:
- funcname(*, project_dir: Union[str, pathlib.Path], params: Dict[str, Any]) versioningit.VCSDescription
- Parameters
project_dir (path) – the path to a project directory
params (dict) – a collection of user-supplied parameters
- Returns
a description of the state of the version control repository at the directory
- Return type
- Raises
versioningit.errors.NoTagError – If a tag cannot be determined for the repository
versioningit.errors.NotVCSError – if
project_diris not under the expected type of version control
tag2version
A custom tag2version method is a callable with the following synopsis:
next-version
A custom next-version method is a callable with the following synopsis:
- funcname(*, version: str, branch: Optional[str], params: Dict[str, Any]) str
- Parameters
- Returns
a version string for use as the
{next_version}field in[tool.versioningit.format]format templates.- Return type
- Raises
versioningit.errors.InvalidVersionError – if
versioncannot be parsed
format
A custom format method is a callable with the following synopsis:
- funcname(*, description: versioningit.VCSDescription, version: str, next_version: str, params: Dict[str, Any]) str
- Parameters
description – a
versioningit.VCSDescriptionreturned by avcsmethodversion (str) – a version string extracted from the VCS tag
next_version (str) – a “next version” calculated by the
next-versionstepparams (dict) – a collection of user-supplied parameters
- Returns
the project’s final version string
- Return type
Note that the format method is not called if description.state is
"exact", in which case the version returned by the tag2version step is
used as the final version.
write
A custom write method is a callable with the following synopsis:
onbuild
A custom onbuild method is a callable with the following synopsis:
- funcname(*, build_dir: Union[str, pathlib.Path], is_source: bool, version: str, params: Dict[str, Any]) None
Modifies one or more files in
build_dir- Parameters
build_dir (path) – the path to the directory where the project is being built
is_source (bool) – true if an sdist or other artifact that preserves source paths is being built, false if a wheel or other artifact that uses installation paths is being built
version (str) – the project’s final version
params (dict) – a collection of user-supplied parameters
Distributing Your Methods in an Extension Package
If you want to make your custom versioningit methods available for others
to use, you can package them in a Python package and distribute it on PyPI.
Simply create a Python package as normal that contains the method function, and
specify the method function as an entry point of the project. The name of the
entry point group is versioningit.STEP (though, for next-version, the
group is spelled with an underscore instead of a hyphen:
versioningit.next_version). For example, if you have a custom vcs
method implemented as a foobar_vcs() function in mypackage/vcs.py,
you would declare it in setup.cfg as follows:
[options.entry_points]
versioningit.vcs =
foobar = mypackage.vcs:foobar_vcs
Once your package is on PyPI, package developers can use it by including it in
their build-system.requires and specifying the name of the entry point (For
the entry point above, this would be foobar) as the method name in the
appropriate subtable. For example, a user of the foobar method for the
vcs step would specify it as:
[tool.versioningit.vcs]
method = "foobar"
# Parameters go here