Wheel Variant Experimental Support #2037
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
hcho3
changed the title
hcho3
added a commit
to hcho3/pep_xxx_wheel_variants
that referenced
this pull request
Sep 15, 2025
hcho3
added a commit
to hcho3/pep_xxx_wheel_variants
that referenced
this pull request
Sep 15, 2025
cjames23
reviewed
Sep 26, 2025
Comment on lines
14
to
37
| # Common variant info keys (used in pyproject.toml and variants.json) | ||
| VARIANT_INFO_DEFAULT_PRIO_KEY: Literal["default-priorities"] = "default-priorities" | ||
| VARIANT_INFO_FEATURE_KEY: Literal["feature"] = "feature" | ||
| VARIANT_INFO_NAMESPACE_KEY: Literal["namespace"] = "namespace" | ||
| VARIANT_INFO_PROPERTY_KEY: Literal["property"] = "property" | ||
| VARIANT_INFO_PROVIDER_DATA_KEY: Literal["providers"] = "providers" | ||
| VARIANT_INFO_PROVIDER_ENABLE_IF_KEY: Literal["enable-if"] = "enable-if" | ||
| VARIANT_INFO_PROVIDER_OPTIONAL_KEY: Literal["optional"] = "optional" | ||
| VARIANT_INFO_PROVIDER_PLUGIN_API_KEY: Literal["plugin-api"] = "plugin-api" | ||
| VARIANT_INFO_PROVIDER_PLUGIN_USE_KEY: Literal["plugin-use"] = "plugin-use" | ||
| VARIANT_INFO_PROVIDER_REQUIRES_KEY: Literal["requires"] = "requires" | ||
|
|
||
| PYPROJECT_TOML_TOP_KEY = "variant" | ||
|
|
||
| VARIANTS_JSON_SCHEMA_KEY: Literal["$schema"] = "$schema" | ||
| VARIANTS_JSON_SCHEMA_URL = "https://variants-schema.wheelnext.dev/v0.0.2.json" | ||
| VARIANTS_JSON_VARIANT_DATA_KEY: Literal["variants"] = "variants" | ||
|
|
||
| VALIDATION_VARIANT_LABEL_REGEX = re.compile(rf"[0-9a-z._]{{1,{VARIANT_LABEL_LENGTH}}}") | ||
|
|
||
| VALIDATION_NAMESPACE_REGEX = re.compile(r"[a-z0-9_]+") | ||
| VALIDATION_FEATURE_NAME_REGEX = re.compile(r"[a-z0-9_]+") | ||
| VALIDATION_VALUE_REGEX = re.compile(r"[a-z0-9_.]+") | ||
|
|
Contributor
There was a problem hiding this comment.
Why not just use variantlib itself to obtain these?
Hatch uses the ruff formatter as code style.
konstin
pushed a commit
to hcho3/pep_xxx_wheel_variants
that referenced
this pull request
Oct 7, 2025
konstin
added a commit
to wheelnext/pep_xxx_wheel_variants
that referenced
this pull request
Oct 7, 2025
* Sync to pypa/hatch#2037 * . --------- Co-authored-by: konstin <[email protected]>
cjames23
reviewed
Nov 8, 2025
| ) | ||
| else: | ||
| command = ['python', '-u', '-m', 'hatchling', 'build', '--target', target] | ||
| command = [sys.executable, '-u', '-m', 'hatchling', 'build', '--target', target] |
Contributor
There was a problem hiding this comment.
Does this need to change to sys.executable?
Comment on lines
+63
to
+64
| variant_props: list[str] | None = None, # noqa: ARG002 | ||
| variant_label: str | None = None, # noqa: ARG002 |
Contributor
There was a problem hiding this comment.
If these are not used as part of the interface for other plugins these should be removed. And my understanding of variants is that these would only ever be applicable to the wheel implementation.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
WheelNext & Wheel Variants
Caution
This is an an experimental feature currently being formalized as a PEP.
This is not an official feature of the Python Ecosystem & Standards.
This PR is part of the work being conducted by the WheelNext open-source initiative.
This PR introduces the feature of "Wheel Variant" into hatch & hatchling as a proof-of-concept.
Hopefully, this will give a good idea on:
How do "Wheel Variants" work ?
Wheel Variant is a proposed extension to the wheel specification designed to make platform-specific package distribution easier for package maintainers, and installation more smooth for end users. The key concepts are:
A Provider Plugin system, allowing vendors and communities to ship small, install-time packages that can detect system capabilities (e.g., CUDA version, CPU features).
A declarative metadata format for wheels to express their specific requirements (e.g.,
nvidia :: cuda_version_lower_bound :: 12.8). Yes, absolutely inspired by Python classifier format.A mechanism for installers to automatically run these plugins to match the user's system with the best-fitting variant wheel, simplifying the user experience to a familiar
[uv] pip install torch.We have carefully designed this system to ensure that installers unaware of variants will safely ignore them, maintaining backward compatibility with the existing ecosystem.
Links and Resources:
uvPR Details
--variant-propertyto allow users to build variant wheels with a given variant specifier. Example:variant.jsoninto the wheel, whenever the wheel is variant-enabled.TODOs
python -m build.cc @DEKHTIARJonathan, @warsaw