{"id":6482,"library":"wheel-filename","title":"Wheel Filename Parser","description":"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.","status":"active","version":"2.1.0","language":"en","source_language":"en","source_url":"https://github.com/wheelodex/wheel-filename","tags":["packaging","wheel","parsing","PEP 427"],"install":[{"cmd":"pip install wheel-filename","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"WheelFilename","correct":"from wheel_filename import WheelFilename"},{"symbol":"ParseError","correct":"from wheel_filename import ParseError"}],"quickstart":{"code":"from wheel_filename import WheelFilename, ParseError\n\nfilename = 'pip-18.0-py2.py3-none-any.whl'\ntry:\n    pwf = WheelFilename.parse(filename)\n    print(f\"Project: {pwf.project}\")\n    print(f\"Version: {pwf.version}\")\n    print(f\"Python Tags: {pwf.python_tags}\")\n    print(f\"ABI Tags: {pwf.abi_tags}\")\n    print(f\"Platform Tags: {pwf.platform_tags}\")\n    print(f\"String representation: {str(pwf)}\")\n    print(f\"Tag Triples: {list(pwf.tag_triples())}\")\nexcept ParseError as e:\n    print(f\"Error parsing filename '{e.filename}': {e}\")\n\ninvalid_filename = 'my_package-1.0.whl'\ntry:\n    WheelFilename.parse(invalid_filename)\nexcept ParseError as e:\n    print(f\"Caught expected error for '{e.filename}': {e}\")","lang":"python","description":"Demonstrates how to parse a valid wheel filename and access its components, and how to handle `ParseError` for invalid filenames."},"warnings":[{"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.","message":"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`.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"deprecated","affected_versions":"Pip 25.1+ (affecting consumption of non-compliant wheels)"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}