updv

tiny version string updater written in python.

updv updates a version string across a project from a single version value, using a configurable TOML-based configuration file. this keeps version values in source files, package metadata, documentation, and other project files synchronized.

features

• toml-based configuration (.updv.toml)
• simple getopt-based cli frontend
• update multiple files from a single version value
• configurable file creation and failure behavior
• templated paths, patterns, and replacements
• minimal runtime dependencies

dependencies

updv requires at least

• a python 3.11 or newer interpreter

runtime dependencies include

• packaging: to parse and modify version strings

development dependencies include

• pytest: to execute the unit tests

installation

clone the repository and install updv in editable mode.

python -m pip install -e .

or install via PyPI

python -m pip install updv

configuration

create a project configuration from the included example:

cp updv.toml.example .updv.toml

edit .updv.toml to define which files and version values updv should update.

example .updv.toml:

[project]
name = "hello"
version = "0.0.0"
previous_version = "0.0.0"

[project.vars]
changelog_header = "Unreleased"
[project.files.initpy]
path = "src/{name}/__init__.py"
on-missing-file = "fail"
on-no-match = "fail"
enabled = true

pattern = "__version__ = \"{old}\""
replacement = "__version__ = \"{new}\""

[project.files.changelog]
path = "CHANGELOG.md"
on-missing-file = "fail"
on-no-match = "skip"
enabled = true

pattern = "## \\[{changelog_header}\\]"
replacement = "## [{new}] - {date}"

[project.files.version]
path = "VERSION"
on-missing-file = "create"
on-no-match = "write"
enabled = true

pattern = "{old}"
replacement = "{new}"

paths, patterns, and replacements support project and version variables such as {old}, {new}, {name}, and {date}. custom placeholders can be added through the [project.vars] section on the configuration file.

policies

on-missing-file

• create: create an empty file
• skip: skip the file
• fail: fail with an error

on-no-match

• append: append the replacement to the file
• prepend: prepend the replacement to the file
• write: overwrite the file with the replacement
• skip: skip the file
• fail: fail with an error

usage

updv -n 0.2.0 # updates version values to 0.2.0
updv -h # view all available cmd options

testing

running the test suite can be done with pytest

pip install -e ".[dev]" # install dev dependencies
pytest -vs . # run the unit tests

project status

updv is in active development. while functional, it is not yet production-ready for real-world usage.

• CHANGELOG.md -- release history
• CONTRIBUTING.md -- how to report bugs and send patches

license

BSD-3-Clause, see LICENSE