Merge pull request #118 from jwodder/gh-117

Add `{normalized_version}` field for `write` and `onbuild` steps

Author: jwodder

CHANGELOG.md

@@ -1,3 +1,8 @@
+v3.3.0 (in development)
+-----------------------
+- Added `{normalized_version}` to the fields available to the `write` and
+  `onbuild` steps
+
 v3.2.0 (2025-06-10)
 -------------------
 - Support reading configuration from a `versioningit.toml` file instead of

docs/changelog.rst

@@ -3,6 +3,12 @@
 Changelog
 =========
 
+v3.3.0 (in development)
+-----------------------
+- Added ``{normalized_version}`` to the fields available to the ``write`` and
+  ``onbuild`` steps
+
+
 v3.2.0 (2025-06-10)
 -------------------
 - Support reading configuration from a :file:`versioningit.toml` file instead

docs/configuration.rst

@@ -395,13 +395,20 @@ The ``[tool.versioningit.template-fields]`` Subtable
 
 .. versionadded:: 2.0.0
 
+.. versionadded:: 3.3.0
+
+    The ``{normalized_version}`` field
+
 The ``template-fields`` subtable controls the fields available for the
 templates of the ``write`` and ``onbuild`` steps.  ``versioningit`` provides
 one ``template-fields`` method, ``"basic"`` (the default), which provides the
 following template fields:
 
 - ``{version}`` — the project's final version
 
+- ``{normalized_version}`` — the project's final version, normalized as per
+  :pep:`440`; if the version string cannot be normalized, it is left as-is
+
 - ``{version_tuple}`` — a string representation of a tuple of ``{version}``'s
   components; see below for how to configure how the version is split up
 

src/versioningit/__init__.py

@@ -44,7 +44,7 @@
 <https://versioningit.rtfd.io> for more information.
 """
 
-__version__ = "3.2.0"
+__version__ = "3.3.0.dev1"
 __author__ = "John Thorvald Wodder II"
 __author_email__ = "versioningit@varonathe.org"
 __license__ = "MIT"

src/versioningit/basics.py

@@ -3,6 +3,7 @@
 from pathlib import Path
 import re
 from typing import Any, Optional
+from packaging.version import Version
 from .core import VCSDescription
 from .errors import ConfigError, InvalidTagError
 from .logging import log, warn_extra_fields
@@ -194,4 +195,8 @@ def basic_template_fields(
         fields["next_version"] = next_version
     fields["version"] = version
     fields["version_tuple"] = version_tuple
+    try:
+        fields["normalized_version"] = str(Version(version))
+    except ValueError:
+        fields["normalized_version"] = version
     return fields

test/data/repos/git/onbuild-write-norming.json

@@ -0,0 +1,18 @@
+{
+    "version": "0.1.0-r2",
+    "pkg_version": "0.1.0.post2",
+    "next_version": "0.2.0",
+    "files": [
+        {
+            "sdist_path": "src/mypackage/_version.py",
+            "wheel_path": "mypackage/_version.py",
+            "contents": "__raw_version__ = \"0.1.0-r2\"\n__version__ = \"0.1.0.post2\"\n"
+        },
+        {
+            "sdist_path": "src/mypackage/__init__.py",
+            "wheel_path": "mypackage/__init__.py",
+            "in_project": false,
+            "contents": "\"\"\" A test package \"\"\"\n\n__raw_version__ = \"0.1.0-r2\"\n__version__ = \"0.1.0.post2\"\n"
+        }
+    ]
+}

test/data/repos/git/onbuild-write-norming.zip

@@ -64,11 +64,20 @@ class ErrorDetails(BaseModel):
 
 class CaseDetails(BaseModel):
     version: str
+    # Version reported by packaging metadata rather than by versioningit;
+    # differs from `version` when normalization happens:
+    pkg_version: Union[str, None] = None
     next_version: Union[str, ErrorDetails]
     local_modules: List[str] = Field(default_factory=list)
     files: List[File] = Field(default_factory=list)
     logmsgs: List[LogMsg] = Field(default_factory=list)
 
+    def get_pkg_version(self) -> str:
+        if self.pkg_version is not None:
+            return self.pkg_version
+        else:
+            return self.version
+
 
 def mkcases(
     subdir: str,
@@ -142,13 +151,13 @@ def test_end2end(
         f.check(srcdir, "project")
 
     sdist_src = unpack_sdist(srcdir / "dist", tmp_path)
-    assert get_version_from_pkg_info(sdist_src) == details.version
+    assert get_version_from_pkg_info(sdist_src) == details.get_pkg_version()
     for f in details.files:
         f.check(sdist_src, "sdist")
 
     wheel_src, wheel_dist_info = unpack_wheel(srcdir / "dist", tmp_path)
     metadata = (wheel_dist_info / "METADATA").read_text(encoding="utf-8")
-    assert parse_version_from_metadata(metadata) == details.version
+    assert parse_version_from_metadata(metadata) == details.get_pkg_version()
     for f in details.files:
         f.check(wheel_src, "wheel")
 
@@ -383,7 +392,7 @@ def test_build_wheel_directly(repopath: str, tmp_path: Path) -> None:
 
     wheel_src, wheel_dist_info = unpack_wheel(srcdir / "dist", tmp_path)
     metadata = (wheel_dist_info / "METADATA").read_text(encoding="utf-8")
-    assert parse_version_from_metadata(metadata) == details.version
+    assert parse_version_from_metadata(metadata) == details.get_pkg_version()
     for f in details.files:
         f.check(wheel_src, "wheel")
 
@@ -408,7 +417,7 @@ def test_editable_mode(cmd: list[str], tmp_path: Path) -> None:
     try:
         assert get_repo_status(srcdir) == status
         info = readcmd(sys.executable, "-m", "pip", "show", "mypackage")
-        assert parse_version_from_metadata(info) == details.version
+        assert parse_version_from_metadata(info) == details.get_pkg_version()
         version_var = readcmd(
             sys.executable, "-c", "import mypackage; print(mypackage.__version__)"
         )
@@ -438,7 +447,7 @@ def test_editable_mode_hatch(tmp_path: Path) -> None:
     try:
         assert get_repo_status(srcdir) == status
         info = readcmd(sys.executable, "-m", "pip", "show", "mypackage")
-        assert parse_version_from_metadata(info) == details.version
+        assert parse_version_from_metadata(info) == details.get_pkg_version()
         version_var = readcmd(
             sys.executable, "-c", "import mypackage; print(mypackage.__version__)"
         )
@@ -472,13 +481,13 @@ def test_setup_py(tmp_path: Path) -> None:
         f.check(srcdir, "project")
 
     sdist_src = unpack_sdist(srcdir / "dist", tmp_path)
-    assert get_version_from_pkg_info(sdist_src) == details.version
+    assert get_version_from_pkg_info(sdist_src) == details.get_pkg_version()
     for f in details.files:
         f.check(sdist_src, "sdist")
 
     wheel_src, wheel_dist_info = unpack_wheel(srcdir / "dist", tmp_path)
     metadata = (wheel_dist_info / "METADATA").read_text(encoding="utf-8")
-    assert parse_version_from_metadata(metadata) == details.version
+    assert parse_version_from_metadata(metadata) == details.get_pkg_version()
     for f in details.files:
         f.check(wheel_src, "wheel")
 

test/test_end2end.py

@@ -97,6 +97,7 @@ def test_basic_template_fields(
         "build_date": BUILD_DATE,
         "branch": "main",
         "version": version,
+        "normalized_version": version,
         "version_tuple": version_tuple,
         "base_version": "0.1.0",
         "next_version": "0.2.0",
@@ -141,7 +142,11 @@ def test_basic_template_fields_bad_pep440_version() -> None:
             None,
             None,
             None,
-            {"version": "1.2.3.post5", "version_tuple": '(1, 2, 3, "post5")'},
+            {
+                "version": "1.2.3.post5",
+                "version_tuple": '(1, 2, 3, "post5")',
+                "normalized_version": "1.2.3.post5",
+            },
         ),
         (
             DESCRIPTION,
@@ -155,6 +160,7 @@ def test_basic_template_fields_bad_pep440_version() -> None:
                 "rev": "abcdef0",
                 "build_date": BUILD_DATE,
                 "branch": "main",
+                "normalized_version": "1.2.3.post5",
             },
         ),
         (
@@ -170,6 +176,7 @@ def test_basic_template_fields_bad_pep440_version() -> None:
                 "build_date": BUILD_DATE,
                 "branch": "main",
                 "base_version": "1.2.3",
+                "normalized_version": "1.2.3.post5",
             },
         ),
     ],
@@ -190,3 +197,45 @@ def test_basic_template_fields_none_inputs(
         )
         == fields
     )
+
+
+def test_basic_template_fields_nonnormalized_version() -> None:
+    assert basic_template_fields(
+        version="2025.06.01",
+        description=DESCRIPTION,
+        base_version="2025.06.01",
+        next_version="2025.07.01",
+        params={},
+    ) == {
+        "distance": 5,
+        "vcs": "g",
+        "rev": "abcdef0",
+        "build_date": BUILD_DATE,
+        "branch": "main",
+        "version": "2025.06.01",
+        "normalized_version": "2025.6.1",
+        "version_tuple": "(2025, 6, 1)",
+        "base_version": "2025.06.01",
+        "next_version": "2025.07.01",
+    }
+
+
+def test_basic_template_fields_nonpep440_version() -> None:
+    assert basic_template_fields(
+        version="2025.06.01j",
+        description=DESCRIPTION,
+        base_version="2025.06.01",
+        next_version="2025.07.01",
+        params={},
+    ) == {
+        "distance": 5,
+        "vcs": "g",
+        "rev": "abcdef0",
+        "build_date": BUILD_DATE,
+        "branch": "main",
+        "version": "2025.06.01j",
+        "normalized_version": "2025.06.01j",
+        "version_tuple": '(2025, 6, "01j")',
+        "base_version": "2025.06.01",
+        "next_version": "2025.07.01",
+    }