feat(wheels): add configurable build tag hook for wheel filenames

Implement the accepted proposal from docs/proposals/wheel-build-tag-hook.md
(issue #1059, tracking issue #1181).

Add a `wheels.build_tag_hook` option in global settings that lets downstream
projects append environment-specific suffixes (OS, accelerator, torch ABI)
to wheel build tags via a user-defined callable. The hook receives ctx, req,
version, and wheel_tags and returns suffix segments joined with `_`.

- Add `WheelSettings` model with `build_tag_hook: ImportString` to settings
- Add `get_build_tag()` and `_validate_build_tag_segments()` to wheels.py
- Update `add_extra_metadata_to_wheels()`, bootstrapper cache checks, and
  `_is_wheel_built()` to use computed build tags
- Minimal finder update to match suffixed build tag filenames
- Validate hook output: reject single strings, invalid chars, non-strings
- No behavior change when hook is not configured

Closes: #1181

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Justin Larkin <jlarkin@redhat.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Signed-off-by: Justin Larkin <jlarkin@redhat.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Signed-off-by: Justin Larkin <jlarkin@redhat.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Signed-off-by: Justin Larkin <jlarkin@redhat.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Signed-off-by: Justin Larkin <jlarkin@redhat.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 3 people

src/fromager/bootstrapper/_cache.py

@@ -86,22 +86,29 @@ def _look_for_existing_wheel(
     search_in: pathlib.Path,
 ) -> tuple[pathlib.Path | None, pathlib.Path | None]:
     pbi = ctx.package_build_info(req)
-    expected_build_tag = pbi.build_tag(resolved_version)
+    base_build_tag = pbi.build_tag(resolved_version)
     logger.info(
-        f"looking for existing wheel for version {resolved_version} with build tag {expected_build_tag} in {search_in}"
+        f"looking for existing wheel for version {resolved_version} with build tag {base_build_tag} in {search_in}"
     )
     wheel_filename = finders.find_wheel(
         downloads_dir=search_in,
         req=req,
         dist_version=str(resolved_version),
-        build_tag=expected_build_tag,
+        build_tag=base_build_tag,
     )
     if not wheel_filename:
         return None, None
-    _, _, build_tag, _ = wheels.extract_info_from_wheel_file(req, wheel_filename)
-    if expected_build_tag and expected_build_tag != build_tag:
+    _, _, actual_build_tag, wheel_tags = wheels.extract_info_from_wheel_file(
+        req, wheel_filename
+    )
+    expected_build_tag = wheels.get_build_tag(
+        ctx=ctx, req=req, version=resolved_version, wheel_tags=wheel_tags
+    )
+    expected = expected_build_tag or (0, "")
+    actual = actual_build_tag or (0, "")
+    if expected != actual:
         logger.info(
-            f"found wheel for {resolved_version} in {wheel_filename} but build tag does not match. Got {build_tag} but expected {expected_build_tag}"
+            f"found wheel for {resolved_version} in {wheel_filename} but build tag does not match. Got {actual_build_tag} but expected {expected_build_tag}"
         )
         return None, None
     logger.info(f"found existing wheel {wheel_filename}")
@@ -129,16 +136,19 @@ def _download_wheel_from_cache(
         results = resolver.find_all_matching_from_provider(provider, pinned_req)
         wheel_url, _ = results[0]
         wheelfile_name = pathlib.Path(urlparse(wheel_url).path)
-        pbi = ctx.package_build_info(req)
-        expected_build_tag = pbi.build_tag(resolved_version)
+        _, _, actual_build_tag, wheel_tags = wheels.extract_info_from_wheel_file(
+            req, wheelfile_name
+        )
+        expected_build_tag = wheels.get_build_tag(
+            ctx=ctx, req=req, version=resolved_version, wheel_tags=wheel_tags
+        )
         logger.info(f"has expected build tag {expected_build_tag}")
-        changelogs = pbi.get_changelog(resolved_version)
-        logger.debug(f"has change logs {changelogs}")
 
-        _, _, build_tag, _ = wheels.extract_info_from_wheel_file(req, wheelfile_name)
-        if expected_build_tag and expected_build_tag != build_tag:
+        expected = expected_build_tag or (0, "")
+        actual = actual_build_tag or (0, "")
+        if expected != actual:
             logger.info(
-                f"found wheel for {resolved_version} in cache but build tag does not match. Got {build_tag} but expected {expected_build_tag}"
+                f"found wheel for {resolved_version} in cache but build tag does not match. Got {actual_build_tag} but expected {expected_build_tag}"
             )
             return None, None
 

src/fromager/commands/build.py

@@ -485,39 +485,8 @@ def _is_wheel_built(
             wheel_server_urls=wheel_server_urls,
         )
         logger.info("found candidate wheel %s", url)
-        pbi = wkctx.package_build_info(req)
-        build_tag_from_settings = pbi.build_tag(resolved_version)
-        build_tag = build_tag_from_settings if build_tag_from_settings else (0, "")
         wheel_basename = downloads.extract_filename_from_url(url)
-        _, _, build_tag_from_name, _ = parse_wheel_filename(wheel_basename)
-        existing_build_tag = build_tag_from_name if build_tag_from_name else (0, "")
-        if (
-            existing_build_tag[0] > build_tag[0]
-            and existing_build_tag[1] == build_tag[1]
-        ):
-            raise ValueError(
-                f"{dist_name}: changelog for version {resolved_version} is inconsistent. Found build tag {existing_build_tag} but expected {build_tag}"
-            )
-        if existing_build_tag != build_tag:
-            logger.info(
-                f"candidate wheel build tag {existing_build_tag} does not match expected build tag {build_tag}"
-            )
-            return None
-
-        wheel_filename: pathlib.Path | None = None
-        if url.startswith(wkctx.wheel_server_url):
-            logging.debug("found wheel on local server")
-            wheel_filename = wkctx.wheels_downloads / wheel_basename
-            if not wheel_filename.exists():
-                logger.info("wheel not found in local cache, preparing to download")
-                wheel_filename = None
-
-        if not wheel_filename:
-            # if the found wheel was on an external server, then download it
-            logger.info("downloading wheel from %s", url)
-            wheel_filename = wheels.download_wheel(req, url, wkctx.wheels_downloads)
-
-        return wheel_filename
+        _, _, build_tag_from_name, wheel_tags = parse_wheel_filename(wheel_basename)
     except Exception:
         logger.debug(
             "could not locate prebuilt wheel %s-%s on %s",
@@ -529,6 +498,37 @@ def _is_wheel_built(
         logger.info("could not locate prebuilt wheel")
         return None
 
+    # Compute expected build tag outside the broad exception handler
+    # so hook validation errors propagate instead of being swallowed.
+    expected_tag = wheels.get_build_tag(
+        ctx=wkctx, req=req, version=resolved_version, wheel_tags=wheel_tags
+    )
+    build_tag = expected_tag if expected_tag else (0, "")
+    existing_build_tag = build_tag_from_name if build_tag_from_name else (0, "")
+    if existing_build_tag[0] > build_tag[0] and existing_build_tag[1] == build_tag[1]:
+        raise ValueError(
+            f"{dist_name}: changelog for version {resolved_version} is inconsistent. Found build tag {existing_build_tag} but expected {build_tag}"
+        )
+    if existing_build_tag != build_tag:
+        logger.info(
+            f"candidate wheel build tag {existing_build_tag} does not match expected build tag {build_tag}"
+        )
+        return None
+
+    wheel_filename: pathlib.Path | None = None
+    if url.startswith(wkctx.wheel_server_url):
+        logging.debug("found wheel on local server")
+        wheel_filename = wkctx.wheels_downloads / wheel_basename
+        if not wheel_filename.exists():
+            logger.info("wheel not found in local cache, preparing to download")
+            wheel_filename = None
+
+    if not wheel_filename:
+        logger.info("downloading wheel from %s", url)
+        wheel_filename = wheels.download_wheel(req, url, wkctx.wheels_downloads)
+
+    return wheel_filename
+
 
 def _build_parallel(
     wkctx: context.WorkContext,

src/fromager/finders.py

@@ -162,30 +162,27 @@ def find_wheel(
     """
     filename_prefix = _dist_name_to_filename(req.name)
     canonical_name = canonicalize_name(req.name)
-    # if build tag is 0 then we can ignore to handle non tagged wheels for backward compatibility
-    candidate_bases_build_tag = f"{build_tag[0]}{build_tag[1]}-" if build_tag else ""
 
-    candidate_bases = set(
-        [
-            # First check if the file is there using the canonically
-            # transformed name.
-            f"{filename_prefix}-{dist_version}-{candidate_bases_build_tag}",
-            # If that didn't work, try the canonical dist name. That's not
-            # "correct" but we do see it. (charset-normalizer-3.3.2-
-            # and setuptools-scm-8.0.4-) for example
-            f"{canonical_name}-{dist_version}-{candidate_bases_build_tag}",
-            # If *that* didn't work, try the dist name we've been
-            # given as a dependency. That's not "correct", either but we do
-            # see it. (oslo.messaging-14.7.0-) for example
-            f"{req.name}-{dist_version}-{candidate_bases_build_tag}",
-            # Sometimes the sdist uses '.' instead of '-' in the
-            # package name portion.
-            f"{req.name.replace('-', '.')}-{dist_version}-{candidate_bases_build_tag}",
-        ]
-    )
-    # Case-insensitive globbing was added to Python 3.12, but we
-    # have to run with older versions, too, so do our own name
-    # comparison.
+    build_tag_prefixes: list[str] = []
+    if build_tag:
+        build_tag_prefixes.append(f"{build_tag[0]}{build_tag[1]}-")
+        if not build_tag[1]:
+            build_tag_prefixes.append(f"{build_tag[0]}_")
+    else:
+        build_tag_prefixes.append("")
+
+    name_variants = [
+        filename_prefix,
+        canonical_name,
+        req.name,
+        req.name.replace("-", "."),
+    ]
+
+    candidate_bases: list[str] = []
+    for name in name_variants:
+        for btp in build_tag_prefixes:
+            candidate_bases.append(f"{name}-{dist_version}-{btp}")
+
     for base in candidate_bases:
         logger.debug('looking for wheel as "%s"', base)
         for filename in downloads_dir.glob("*.whl"):

src/fromager/packagesettings/__init__.py

@@ -12,6 +12,7 @@
     ResolverDist,
     SbomSettings,
     VariantInfo,
+    WheelSettings,
 )
 from ._pbi import PackageBuildInfo
 from ._resolver import (
@@ -88,6 +89,7 @@
     "Variant",
     "VariantChangelog",
     "VariantInfo",
+    "WheelSettings",
     "default_update_extra_environ",
     "get_extra_environ",
     "pep440_tag_matcher",

src/fromager/packagesettings/_models.py

@@ -33,6 +33,39 @@
 logger = logging.getLogger(__name__)
 
 
+class WheelSettings(pydantic.BaseModel):
+    """Global wheel build settings
+
+    ::
+
+      wheels:
+        build_tag_hook: "mypackage.hooks:build_tag_hook"
+
+    .. versionadded:: 0.92.0
+    """
+
+    model_config = MODEL_CONFIG
+
+    build_tag_hook: pydantic.ImportString[typing.Callable[..., typing.Any]] | None = (
+        None
+    )
+    """Callable that returns suffix segments for the wheel build tag.
+
+    The callable receives keyword-only arguments ``ctx``, ``req``,
+    ``version``, and ``wheel_tags`` and returns
+    ``Sequence[str]`` of suffix segments.
+
+    Only invoked when the package already has a non-empty build tag
+    from its changelog entry for the given version; otherwise the hook
+    is skipped and no build tag is added.  The callable must be
+    deterministic and independent of wheel contents, build environment,
+    or ELF metadata so fresh builds and cache lookups compute the same
+    tag.
+
+    .. versionadded:: 0.92.0
+    """
+
+
 class SbomSettings(pydantic.BaseModel):
     """Global SBOM generation settings
 

src/fromager/packagesettings/_settings.py

@@ -13,7 +13,7 @@
 from pydantic import Field
 
 from .. import overrides
-from ._models import ExternalCommands, PackageSettings, SbomSettings
+from ._models import ExternalCommands, PackageSettings, SbomSettings, WheelSettings
 from ._pbi import PackageBuildInfo
 from ._typedefs import MODEL_CONFIG, GlobalChangelog, Package, Variant
 
@@ -55,6 +55,14 @@ class SettingsFile(pydantic.BaseModel):
     .. versionadded:: 0.92.0
     """
 
+    wheels: WheelSettings | None = None
+    """Wheel build settings
+
+    Configures wheel build tag hooks and other wheel-specific options.
+
+    .. versionadded:: 0.92.0
+    """
+
     @classmethod
     def from_string(
         cls,
@@ -193,6 +201,13 @@ def external_commands(self) -> ExternalCommands:
         """
         return self._settings.external_commands
 
+    @property
+    def build_tag_hook(self) -> typing.Callable[..., typing.Any] | None:
+        """Get the wheel build tag hook callable, or None if not configured."""
+        if self._settings.wheels is None:
+            return None
+        return self._settings.wheels.build_tag_hook
+
     def variant_changelog(self) -> list[str]:
         """Get global changelog for current variant"""
         return list(self._settings.changelog.get(self.variant, []))

src/fromager/wheels.py

@@ -4,6 +4,7 @@
 import logging
 import os
 import pathlib
+import re
 import shutil
 import sys
 import tempfile
@@ -38,12 +39,67 @@
 
 logger = logging.getLogger(__name__)
 
+_BUILD_TAG_SEGMENT_RE = re.compile(r"^[a-zA-Z0-9.]+$")
+
 FROMAGER_BUILD_SETTINGS = "fromager-build-settings"
 FROMAGER_ELF_PROVIDES = "fromager-elf-provides.txt"
 FROMAGER_ELF_REQUIRES = "fromager-elf-requires.txt"
 FROMAGER_BUILD_REQ_PREFIX = "fromager"
 
 
+def _validate_build_tag_segments(segments: list[str]) -> None:
+    """Validate that each segment matches ``[a-zA-Z0-9.]``."""
+    for seg in segments:
+        if not isinstance(seg, str):
+            raise ValueError(
+                f"build_tag_hook must return strings, got {type(seg).__name__}"
+            )
+        if not _BUILD_TAG_SEGMENT_RE.match(seg):
+            raise ValueError(
+                f"build tag hook returned invalid segment {seg!r}: "
+                "each segment must match [a-zA-Z0-9.]"
+            )
+
+
+def get_build_tag(
+    *,
+    ctx: context.WorkContext,
+    req: Requirement,
+    version: Version,
+    wheel_tags: frozenset[Tag],
+) -> BuildTag:
+    """Compute the full build tag including any hook-provided suffix.
+
+    Calls ``pbi.build_tag(version)`` for the numeric base, then invokes
+    the configured ``build_tag_hook`` (if any) to append environment
+    suffix segments.
+
+    .. versionadded:: 0.92.0
+    """
+    pbi = ctx.package_build_info(req)
+    base_tag = pbi.build_tag(version)
+    if not base_tag:
+        return base_tag
+
+    hook = ctx.settings.build_tag_hook
+    if hook is None:
+        return base_tag
+
+    raw = hook(ctx=ctx, req=req, version=version, wheel_tags=wheel_tags)
+    if isinstance(raw, (str, bytes)):
+        raise ValueError(
+            "build_tag_hook must return a sequence of strings, not a single string"
+        )
+    segments = list(raw)
+    _validate_build_tag_segments(segments)
+
+    if not segments:
+        return base_tag
+
+    suffix = base_tag[1] + "_" + "_".join(segments)
+    return (base_tag[0], suffix)
+
+
 def _log_existing_sboms(
     req: Requirement,
     dist_info_dir: pathlib.Path,
@@ -264,8 +320,11 @@ def add_extra_metadata_to_wheels(
             )
             sbom.write_sbom(sbom=sbom_doc, dist_info_dir=dist_info_dir)
 
-        build_tag_from_settings = pbi.build_tag(version)
-        build_tag = build_tag_from_settings if build_tag_from_settings else (0, "")
+        build_tag = get_build_tag(
+            ctx=ctx, req=req, version=version, wheel_tags=wheel_tags
+        )
+        if not build_tag:
+            build_tag = (0, "")
 
         cmd = [
             "wheel",