Merge pull request #1066 from tiran/proposal-wheel-build-tag-hook

[proposal] wheel_build_tag hook for unique wheel file names

Author: LalatenduMohanty

docs/proposals/wheel-build-tag-hook.md

@@ -0,0 +1,138 @@
+# Unique wheel file names with a `wheel_build_tag` hook
+
+- Author: Christian Heimes
+- Created: 2026-04-16
+- Status: Open
+- GitHub issue: [#1059](https://github.com/python-wheel-build/fromager/issues/1059)
+
+## What
+
+This enhancement proposes a new configurable hook, `build_tag_hook`, for
+injecting custom suffixes into the
+[wheel build tag](https://packaging.python.org/en/latest/specifications/binary-distribution-format/),
+producing unique wheel file names that encode platform, accelerator stack,
+and dependency ABI information.
+
+## Why
+
+Fromager-built wheels are platform-specific and may depend on:
+
+- **OS / distribution version**, e.g. Fedora 43, RHEL 9.6, RHEL 10.1
+- **AI accelerator stack**, e.g. CUDA 13.1 vs CUDA 12.9, ROCm 7.1
+- **Torch ABI**, which is unstable across versions; a wheel compiled for
+  Torch 2.10.0 may have a different ABI than one compiled for Torch 2.11.0
+
+Currently, wheel filenames carry none of this information, making it
+difficult to invalidate caches, distinguish builds for different stacks, or
+replace outdated wheels with correctly-targeted rebuilds.
+
+## Goals
+
+- introduce a `build_tag_hook` option in the `wheels` section of the global
+  settings file
+- allow the hook to contribute ordered suffix segments to the wheel build tag
+- produce unique, deterministic wheel file names that reflect the build
+  environment
+
+## Non-goals
+
+- Filtering or selecting wheels by build tag at install time. `pip install`
+  and `uv pip install` only use the build tag for sorting, not for filtering.
+- Sharing wheels across indexes. While unique file names enable this in
+  principle, the mechanics of cross-index sharing are out of scope.
+- Accessing wheel content, the build environment, or ELF dependency info from
+  within the hook. The hook must work identically whether a wheel is freshly
+  built or retrieved from cache.
+- Validation of annotations such as "depends on libtorch". A validation
+  system for `build_wheel` may be added in the future.
+- Package override hook. It would complicate the design and there is no
+  compelling use-case for package-specific tags.
+
+## How
+
+### Wheel spec background
+
+The wheel filename format is:
+
+```
+{distribution}-{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}.whl
+```
+
+The [build tag](https://packaging.python.org/en/latest/specifications/binary-distribution-format/)
+is optional, must start with a digit, and must not contain `-`. Fromager
+already fills the numeric part from the variant + package changelog and sets
+the string suffix to `""`. This proposal extends that suffix with
+hook-provided segments (e.g. `_el9.6_rocm7.1_torch2.10.0`).
+
+### Configuration
+
+The hook is configured in the global settings file under a new `wheels`
+section. The callable is specified as a dotted import path using Pydantic's
+`ImportString` type for validation and loading.
+
+```yaml
+wheels:
+  build_tag_hook: "mypackage.hooks:build_tag_hook"
+```
+
+When `build_tag_hook` is not set, no suffix is appended to the build tag.
+
+### Hook signature
+
+```python
+def build_tag_hook(
+    *,
+    ctx: context.WorkContext,
+    req: Requirement,
+    version: Version,
+    wheel_tags: frozenset[Tag],
+) -> typing.Sequence[str]:
+    ...
+```
+
+The hook returns `typing.Sequence[str]`, a sequence of suffix segments
+(e.g. `["el9.6", "rocm7.1", "torch2.10.0"]`). The segments are joined
+with `_` and appended to the existing build tag.
+
+Each segment must only contain alphanumeric ASCII characters or dot
+(`[a-zA-Z0-9.]`). When the hook returns any other character or raises an
+exception, the build fails.
+
+### Example hook
+
+```{literalinclude} wheel_tag_example_hook.py
+:start-at: example_hook
+```
+
+### Hook scope
+
+The hook can access `ctx` (variant, package settings, annotations),
+`wheel_tags` (to distinguish purelib vs platlib), and standard library
+APIs like `os.environ` and `platform.freedesktop_os_release()`.
+
+The hook **cannot** access wheel content, the build environment, or ELF
+dependency info. These are unavailable when wheels come from cache, and the
+hook must produce the same result regardless of source.
+
+### Examples
+
+| Wheel | Build tag | OS | Stack |
+| -- | -- | -- | -- |
+| `flash_attn-2.8.3-8_el9.6_rocm7.1_torch2.10.0-cp312-cp312-linux_x86_64.whl` | `8_el9.6_rocm7.1_torch2.10.0` | RHEL 9.6 | ROCm |
+| `torch-2.10.0-7_el9.6_rocm7.1-cp312-cp312-linux_x86_64.whl` | `7_el9.6_rocm7.1` | RHEL 9.6 | ROCm |
+| `torch-2.9.1-8_fc43_cuda13.0-cp312-cp312-linux_x86_64.whl` | `8_fc43_cuda13.0` | Fedora 43 | CUDA |
+| `pillow-12.2.0-2_el9.6-cp312-cp312-linux_x86_64.whl` | `2_el9.6` | RHEL 9.6 | any |
+| `fromager-0.79.0-2-py3-none-any.whl` | `2` (no suffix) | any | any |
+
+Pure-python wheels (`py3-none-any`) receive no suffix, while platlib wheels
+get progressively more specific tags based on their dependencies.
+
+## Limitations
+
+A single index still cannot contain both CUDA and ROCm builds of the same
+package. `pip` and `uv` only use the build tag for sorting, not filtering.
+The upcoming [Wheel.Next](https://wheelnext.dev/) initiative
+([PEP 817](https://peps.python.org/pep-0817/) /
+[PEP 825](https://peps.python.org/pep-0825/)) aims to address this with
+wheel variants. Hook logic for accelerator selection may be reusable when
+that standard lands.

docs/proposals/wheel_tag_example_hook.py

@@ -0,0 +1,53 @@
+import functools
+import os
+import platform
+import typing
+
+from packaging.requirements import Requirement
+from packaging.tags import Tag
+from packaging.version import Version
+
+from fromager import context
+
+
+def example_hook(
+    *,
+    ctx: context.WorkContext,
+    req: Requirement,
+    version: Version,
+    wheel_tags: frozenset[Tag],
+) -> typing.Sequence[str]:
+    result: list[str] = []
+    platlib = any(tag.platform != "any" for tag in wheel_tags)
+    if platlib:
+        # fc43, el9.6, ...
+        result.append(get_distro_tag())
+    pbi = ctx.package_build_info(req)
+
+    # example how to use annotations and ctx.variant for custom flags
+    if pbi.annotations.get("example.accelerator-specific") == "true":
+        # cpu, cuda13.0, ...
+        if ctx.variant.startswith("cpu"):
+            result.append("cpu")
+        elif ctx.variant.startswith("cuda"):
+            cv = Version(os.environ["CUDA_VERSION"])
+            result.append(f"cuda{cv.major}.{cv.minor}")
+        else:
+            raise NotImplementedError(ctx.variant)
+    return result
+
+
+@functools.cache
+def get_distro_tag() -> str:
+    info = platform.freedesktop_os_release()
+    ids = [info["ID"]]  # always defined
+    if "ID_LIKE" in info:  # ids in precedence order
+        ids.extend(info["ID_LIKE"].split())
+    version_id = info.get("VERSION_ID", "")
+    for ident in ids:
+        if ident == "rhel":  # RHEL and CentOS
+            return f"el{version_id}"
+        elif ident == "fedora":
+            return f"fc{version_id}"
+    # other distros
+    return f"{ids[0]}{version_id}".replace("_", "").replace("-", "")

docs/spelling_wordlist.txt

@@ -36,6 +36,7 @@ json
 keyring
 lexicographically
 libcurl
+libtorch
 linter
 linters
 localhost
@@ -67,6 +68,7 @@ setuptools
 statelessly
 stderr
 stdin
+stdlib
 stdout
 subcommand
 subcommands