uv-dynamic-versioning

The project provides two distinct plugins to handle dynamic project metadata:

1. Version source plugin: Used to determine and set the project version based on your Version Control System (VCS).
2. Metadata hook plugin: Used to dynamically set dependencies and optional-dependencies based on the VCS version. This is particularly useful in monorepo architectures where dependencies might change depending on the version or context.

To protect against supply chain attacks, you can use uv's build-constraint-dependencies to pin the dependencies used during the build process (e.g., hatchling and uv-dynamic-versioning).

1. Generate the pinned dependency list using the following command:

$ printf '%s\n' hatchling uv-dynamic-versioning | uv pip compile - --no-annotate --no-header --quiet | jq -R -s 'split("\n") | map(select(length > 0))'

2. Copy the resulting JSON array output.
3. Paste it into your pyproject.toml under the [tool.uv] section.

$ printf '%s\n' hatchling uv-dynamic-versioning | uv pip compile - --no-annotate --no-header --quiet | jq -R -s 'split("\n") | map(select(length > 0))'

[tool.uv]
build-constraint-dependencies = [
  # Paste output here
]

You can expose your package version via a __version__ attribute in your __init__.py by reading it from the installed package metadata.

Note: importlib.metadata can be relatively slow. Avoid this method if performance is critical. Additionally, this approach may fail if the package is installed in development mode. To handle cases where the package is not yet installed (e.g., during local development), use a try/except block to catch importlib.metadata.PackageNotFoundError and provide a fallback version.

import importlib.metadata

try:
    __version__ = importlib.metadata.version(__name__)
except importlib.metadata.PackageNotFoundError:
    __version__ = "0.0.0"

To write the version to a specific file during the build process, you can use Hatch's official version build hook. This allows you to generate a version file (e.g., _version.py) that your code can then import.

Important: The generated version file should not be committed to Version Control (VCS). You should add the path of the generated file to your .gitignore.

[tool.hatch.build.hooks.version]
path = "path/to/_version.py"
template = '''
version = "{version}"
'''

To use uv-dynamic-versioning to set your project version based on your Version Control System (VCS), you must configure your pyproject.toml to use hatchling as the build backend and declare the version as dynamic.

1. Update [build-system] to require both hatchling and uv-dynamic-versioning.
2. In the [project] section, remove the static version key and add version to the dynamic list.

Example configuration:

[build-system]
requires = ["hatchling", "uv-dynamic-versioning"]
build-backend = "hatchling.build"

[project]
name = "your-package"
dynamic = ["version"]

[build-system]
requires = ["hatchling", "uv-dynamic-versioning"]
build-backend = "hatchling.build"

[project]
name = "..."
dynamic = ["version"]

The uv-dynamic-versioning metadata hook allows you to dynamically define dependencies and optional-dependencies using Jinja2 templates based on your VCS version.

To use the hook, you must:

1. Add [tool.hatch.metadata.hooks.uv-dynamic-versioning] to your pyproject.toml.
2. Define your dependencies as Jinja2 templates within that section.
3. Remove the static dependencies list from the [project] section.
4. Add dependencies to the project.dynamic list in pyproject.toml to signal that they are managed dynamically.

[project]
name = "..."
dynamic = ["dependencies"]

[tool.hatch.metadata.hooks.uv-dynamic-versioning]
dependencies = ["foo=={{ version }}"]

To use uv-dynamic-versioning, you must update or add the build-system section in your project's configuration file (e.g., pyproject.toml) to include uv-dynamic-versioning in the requires list. This project is designed to work with hatchling as the build backend.

Note: This plugin currently does not work with the uv build backend (see astral-sh/uv#14561).

[build-system]
requires = ["hatchling", "uv-dynamic-versioning"]
build-backend = "hatchling.build"

The metadata hook supports two main configuration keys. Both require the corresponding field to be listed in project.dynamic within your pyproject.toml.

• dependencies: A list of Jinja2 templates defining your project's core dependencies.
• optional-dependencies: A list of Jinja2 templates defining your project's optional dependencies.

Both keys have access to the same set of Jinja2 variables and functions provided by the underlying versioning engine.

You can control the final version string using format (simple substitutions) or format-jinja (complex logic).

Simple Formatting (format)

Use placeholders like {base}, {stage}, {revision}, {distance}, {commit}, {dirty}, {tagged_metadata}, {branch}, and {timestamp}.

format = "v{base}+{distance}.{commit}"

Advanced Formatting (format-jinja)

Use Jinja2 templates for complex logic. When format-jinja is set, format is ignored. Available variables include version (a dunamai.Version object), base, stage, revision, distance, commit, dirty, env, branch, and timestamp.

Example: Conditional formatting based on distance

format-jinja = "{% if distance == 0 %}{{ base }}{% else %}{{ base }}+{{ distance }}.{{ commit }}{% endif %}"

Because uv-dynamic-versioning makes your project's metadata dynamic, you should configure uv's cache keys to ensure the cache is invalidated correctly when your version source changes.

Add cache-keys to your [tool.uv] configuration to track changes in pyproject.toml and Git commits/tags.

[tool.uv]
cache-keys = [{ file = "pyproject.toml" }, { git = { commit = true, tags = true }}]

Instead of using Git or other VCS, you can use the from-file section to read the version from a specific file.

• source (string): Path to the file relative to pyproject.toml.
• pattern (string): A regular expression to extract the version. The first capture group must contain the version.

[tool.uv-dynamic-versioning.from-file]
source = "VERSION.txt"
pattern = '(?P<version>\d+\.\d+\.\d+)'