Wheel Filename Parser

2.1.0 · active · verified Wed Apr 15

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.

Warnings

breaking The 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.
gotcha Renaming 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.
deprecated While `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.

Install

pip install wheel-filename Install latest version

Imports

WheelFilename

from wheel_filename import WheelFilename

ParseError
```
from wheel_filename import ParseError
```

Quickstart

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}")

view raw JSON →