Registry / serialization / wheel-filename

wheel-filename

library2.1.0pypypi✓ verified 86d ago

wheel-filename is a Python library that enables verification and parsing of wheel filenames into their constituent fields. It strictly adheres to the wheel standard (PEP 427), with minor exceptions for version component validation and case-insensitive `.whl` extension matching. The current version is 2.1.0, and releases follow an as-needed cadence to maintain standard compliance and address any reported issues.

serialization

pip install wheel-filename

github ↗package ↗

INSTALL

IMPORT

SIG · WHEEL-FILENAME

wheel-filename

serializationpythonv2.1.0

Install

1.5s avg

Import

35ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.1.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.030s · 17.8MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.5s · import 0.026s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

WheelFilename

✓ from wheel_filename import WheelFilename

ParseError

✓ from wheel_filename import ParseError

Demonstrates how to parse a valid wheel filename and access its components, and how to handle `ParseError` for invalid filenames.

from wheel_filename import WheelFilename, ParseError filename = 'pip-18.0-py2.py3-none-any.whl' try: pwf = WheelFilename.parse(filename) print(f"Project: {pwf.project}") print(f"Version: {pwf.version}") print(f"Python Tags: {pwf.python_tags}") print(f"ABI Tags: {pwf.abi_tags}") print(f"Platform Tags: {pwf.platform_tags}") print(f"String representation: {str(pwf)}") print(f"Tag Triples: {list(pwf.tag_triples())}") except ParseError as e: print(f"Error parsing filename '{e.filename}': {e}") invalid_filename = 'my_package-1.0.whl' try: WheelFilename.parse(invalid_filename) except ParseError as e: print(f"Caught expected error for '{e.filename}': {e}")

Debug

Known issues

breakingThe library strictly adheres to PEP 427 for wheel filename parsing. Filenames that do not conform to this standard, including those with non-PEP 440 compliant versions or incorrectly structured components, will raise a `ParseError`.

fix

Ensure all wheel filenames strictly follow PEP 427. Verify version components are valid, and do not contain characters not permitted by the standard. Refer to PEP 427 for the correct filename convention.

affects: All versions

gotchaRenaming a wheel file will almost certainly make it invalid and unusable by package installers like `pip`. The filename itself encodes critical metadata about the package, its version, and compatibility. Changing the filename breaks this encoding.

fix

Never manually rename `.whl` files. If a wheel file is incorrectly named, it should be regenerated by the package author or a correctly named wheel should be obtained. Tools that consume wheel files (like `pip`) rely on the filename's integrity.

affects: All versions

deprecatedWhile `wheel-filename` aims for strict adherence to PEP 427, older `pip` versions had more lenient parsing logic. Recent `pip` versions (e.g., 25.1 and 25.3) are moving towards strict validation using the `packaging` library, which aligns with `wheel-filename`'s strict approach. This means wheels that might have been accepted by older `pip` versions but are not PEP 427 compliant will now be rejected by `pip` and by `wheel-filename`.

fix

As a package publisher, ensure all distributed wheel filenames are fully compliant with PEP 427 and PEP 440 to maintain compatibility with modern packaging tools. As a user, if encountering issues, check if the wheel filename is valid against the PEPs.

affects: Pip 25.1+ (affecting consumption of non-compliant wheels)

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'wheel_filename'

The `wheel-filename` package is either not installed or is imported using the incorrect package name (dashes vs. underscores).

fix

Install the package using `pip install wheel-filename` and ensure the import statement uses `wheel_filename` (with an underscore): `from wheel_filename import parse_wheel_filename`.

wheel_filename.InvalidWheelFilename: Filename doesn't match wheel filename specification (PEP 427)

The input string provided to `parse_wheel_filename` or `is_valid_wheel_filename` does not conform to the PEP 427 wheel filename standard.

fix

Ensure the filename string strictly follows the wheel specification (e.g., `package_name-version-python_tag-abi_tag-platform_tag.whl`), or catch the `InvalidWheelFilename` exception for malformed inputs.

TypeError: expected string or bytes-like object

A non-string or non-bytes-like object was passed as the filename argument to a function like `parse_wheel_filename` or `is_valid_wheel_filename`.

fix

Provide a valid string (or bytes) object representing the wheel filename to the parsing or validation function.

Upgrade

Version history

2.1.0latest on PyPI · released Dec 20, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/wheelodex/wheel-filename ↗

packagehttps://pypi.org/project/wheel-filename/ ↗