writing-methods.rst

Writing Your Own Methods

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-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 (though it may log a warning).

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: str | pathlib.Path, params: dict[str, Any]) -> versioningit.VCSDescription

param path project_dir

the path to a project directory

param dict params

a collection of user-supplied parameters

returns

a description of the state of the version control repository at the directory

rtype

versioningit.VCSDescription

raises versioningit.errors.NoTagError

If a tag cannot be determined for the repository

raises versioningit.errors.NotVCSError

if project_dir is not under the expected type of version control

tag2version

A custom tag2version method is a callable with the following synopsis:

funcname(*, tag: str, params: dict[str, Any]) -> str

param str tag

a tag retrieved from version control

param dict params

a collection of user-supplied parameters

returns

a version string extracted from tag

rtype

str

raises versioningit.errors.InvalidTagError

if the tag cannot be parsed

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

param str version

a project version (as extracted from a VCS tag)

param Optional[str] branch

the name of the VCS repository's current branch (if any)

param dict params

a collection of user-supplied parameters

return

a version string for use as the {next_version} field in [tool.versioningit.format] format templates.

rtype

str

raises versioningit.errors.InvalidVersionError

if version cannot be parsed

format

A custom format method is a callable with the following synopsis:

funcname(*, description: versioningit.VCSDescription, base_version: str, next_version: str, params: dict[str, Any]) -> str

param description

a versioningit.VCSDescription returned by a vcs method

param str base_version

a version string extracted from the VCS tag

param str next_version

a "next version" calculated by the next-version step

param dict params

a collection of user-supplied parameters

returns

the project's final version string

rtype

str

2.0.0

The version argument was renamed to base_version.

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.

template-fields

A custom template-fields method is a callable with the following synopsis:

funcname(*, version: str, description: Optional[VCSDescription], base_version: Optional[str], next_version: Optional[str], params: dict[str, Any]) -> dict[str, Any]

param str version

the project's final version

param Optional[VCSDescription] description

a versioningit.VCSDescription returned by a vcs method; None if the vcs method failed

param Optional[str] base_version

a version string extracted from the VCS tag; None if the tag2version step or a previous step failed

param Optional[str] next_version

a "next version" calculated by the next-version step; None if the step or a previous one failed

param dict params

a collection of user-supplied parameters

rtype

dict[str, Any]

write

A custom write method is a callable with the following synopsis:

funcname(*, project_dir: str | pathlib.Path, template_fields: dict[str, Any], params: dict[str, Any]) -> None

param path project_dir

the path to a project directory

param dict template_fields

a collection of variables to use in filling out templates, as calculated by the template-fields step

param dict params

a collection of user-supplied parameters

2.0.0

version argument replaced with template_fields

onbuild

1.1.0

A custom onbuild method is a callable with the following synopsis:

funcname(*, file_provider: OnbuildFileProvider, is_source: bool, template_fields: dict[str, Any], params: dict[str, Any]) -> None

Modifies the files about to be included in an sdist or wheel

param file_provider

an object for accessing files being built into an sdist or wheel

param bool is_source

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

param dict template_fields

a collection of variables to use in filling out templates, as calculated by the template-fields step

param dict params

a collection of user-supplied parameters

2.0.0

version argument replaced with template_fields

3.0.0

build_dir argument replaced with file_provider

onbuild methods are provided with instances of the following abstract base classes for operating on:

versioningit.OnbuildFileProvider

versioningit.OnbuildFile

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 and template-fields, the group is spelled with an underscore instead of a hyphen). For example, if you have a custom vcs method implemented as a foobar_vcs() function in mypackage/vcs.py, you would declare it as follows:

If using setup.cfg

[options.entry_points]
versioningit.vcs =
    foobar = mypackage.vcs:foobar_vcs

If using pyproject.toml

[project.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