feat: format-jinja-imports (#77)

Author: ninoseki

docs/version_source.md

@@ -148,6 +148,26 @@ You may configure the following options under `[tool.uv-dynamic-versioning]`:
   """
   ```
 
+- `format-jinja-imports` (array of tables, default: empty):
+  This defines additional things to import and make available to the `format-jinja` template.
+  Each table must contain a `module` key and may also contain an `item` key. Consider this example:
+
+  ```toml
+  format-jinja-imports = [
+      { module = "foo" },
+      { module = "bar", item = "baz" },
+  ]
+  ```
+
+  This is roughly equivalent to:
+
+  ```python
+  import foo
+  from bar import baz
+  ```
+
+  `foo` and `baz` would then become available in the Jinja formatting.
+
 - `style` (string, default: unset): One of: `pep440`, `semver`, `pvp`. These are pre-configured output formats. If you set both a `style` and a `format`, then the format will be validated against the style's rules. If `style` is unset, the default output format will follow PEP 440, but a custom `format` will only be validated if `style` is set explicitly.
   Regardless of the style you choose, the dynamic version is ultimately subject to Hatchling's validation as well, and Hatchling is designed around PEP 440 versions. Hatchling can usually understand SemVer/etc input, but sometimes, Hatchling may reject an otherwise valid version format.
 - `latest-tag` (boolean, default: false): If true, then only check the latest tag for a version, rather than looking through all the tags until a suitable one is found to match the `pattern`.

src/uv_dynamic_versioning/schemas.py

@@ -71,6 +71,29 @@ def from_dict(cls, data: dict) -> FromFile:
         return cls(**validated_data)
 
 
+@dataclass
+class FormatJinjaImport:
+    module: str
+    item: str | None = None
+
+    def _validate_module(self):
+        if not isinstance(self.module, str):
+            raise ValueError("module must be a string")
+
+    def _validate_item(self):
+        if self.item is not None and not isinstance(self.item, str):
+            raise ValueError("item must be a string or None")
+
+    def __post_init__(self):
+        self._validate_module()
+        self._validate_item()
+
+    @classmethod
+    def from_dict(cls, data: dict) -> FormatJinjaImport:
+        validated_data = _normalize(cls, data)
+        return cls(**validated_data)
+
+
 @dataclass
 class UvDynamicVersioning:
     vcs: Vcs = Vcs.Any
@@ -81,6 +104,7 @@ class UvDynamicVersioning:
     pattern_prefix: str | None = None
     format: str | None = None
     format_jinja: str | None = None
+    format_jinja_imports: list[FormatJinjaImport] | None = None
     style: Style | None = None
     latest_tag: bool = False
     strict: bool = False
@@ -143,6 +167,17 @@ def _validate_format_jinja(self):
         if self.format_jinja is not None and not isinstance(self.format_jinja, str):
             raise ValueError("format-jinja must be a string or None")
 
+    def _validate_format_jinja_imports(self):
+        if self.format_jinja_imports is not None:
+            if not isinstance(self.format_jinja_imports, list):
+                raise ValueError("format-jinja-imports must be a list or None")
+
+            for item in self.format_jinja_imports:
+                if not isinstance(item, FormatJinjaImport):
+                    raise ValueError(
+                        "format-jinja-imports must contain only FormatJinjaImport instances"
+                    )
+
     def _validate_style(self):
         if self.style is not None and not isinstance(self.style, Style):
             raise ValueError(f"style is invalid - {self.style}")
@@ -197,6 +232,7 @@ def __post_init__(self):
         self._validate_pattern_prefix()
         self._validate_format()
         self._validate_format_jinja()
+        self._validate_format_jinja_imports()
         self._validate_style()
         self._validate_tag_dir()
         self._validate_tag_branch()
@@ -239,6 +275,15 @@ def from_dict(cls, data: dict) -> UvDynamicVersioning:
                 validated_data["from_file"]
             )
 
+        if "format_jinja_imports" in validated_data and isinstance(
+            validated_data["format_jinja_imports"], list
+        ):
+            validated_data["format_jinja_imports"] = [
+                FormatJinjaImport.from_dict(item)
+                for item in validated_data["format_jinja_imports"]
+                if isinstance(item, dict)
+            ]
+
         return cls(**validated_data)
 
 

src/uv_dynamic_versioning/template.py

@@ -4,6 +4,7 @@
 import os
 import re
 from datetime import datetime
+from importlib import import_module
 
 import jinja2
 from dunamai import (
@@ -65,4 +66,14 @@ def render_template(
         "serialize_pvp": serialize_pvp,
         "serialize_semver": serialize_semver,
     }
-    return jinja2.Template(template).render(**default_context)
+
+    custom_context = {}
+    if config.format_jinja_imports:
+        for entry in config.format_jinja_imports:
+            module = import_module(entry.module)
+            if entry.item is not None:
+                custom_context[entry.item] = getattr(module, entry.item)
+            else:
+                custom_context[entry.module] = module
+
+    return jinja2.Template(template).render(**default_context, **custom_context)

tests/test_main.py

@@ -60,3 +60,32 @@ def test_get_version_with_invalid_combination_of_format_jinja_and_style():
     assert config.style == Style.Pep440
     with pytest.raises(ValueError):
         get_version(config)
+
+
+def test_get_version_with_format_jinja_imports_with_module_only():
+    config = schemas.UvDynamicVersioning.from_dict(
+        {
+            "format-jinja": "{{ math.pow(2, 2) }}",
+            "format-jinja-imports": [
+                {
+                    "module": "math",
+                }
+            ],
+        }
+    )
+    assert get_version(config)[0] == "4.0"
+
+
+def test_get_version_with_format_jinja_imports_with_item():
+    config = schemas.UvDynamicVersioning.from_dict(
+        {
+            "format-jinja": "{{ pow(2, 2) }}",
+            "format-jinja-imports": [
+                {
+                    "module": "math",
+                    "item": "pow",
+                }
+            ],
+        }
+    )
+    assert get_version(config)[0] == "4.0"