I think when doing this, the part after _ goes into the build number part instead of the version? So that may not do precisely what's intended? Not sure what a better replacement would be, though.

That is correct. I don’t think there’s a real replacement per se; the only alternative that makes sense is to not use such a version at all. (Using .post is a probable solution; build number is another if that works for the use case.)

The description is wrong, but the remedy is correct:

>>> parse_wheel_filename('simple-0.1_1-py2-none-any.whl')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "python3.11/site-packages/pip/_vendor/packaging/utils.py", line 102, in parse_wheel_filename
    version = Version(parts[1])
              ^^^^^^^^^^^^^^^^^
  File "lib/python3.11/site-packages/pip/_vendor/packaging/version.py", line 266, in __init__
    raise InvalidVersion(f"Invalid version: '{version}'")
pip._vendor.packaging.version.InvalidVersion: Invalid version: '0.1_1'


>>> parse_wheel_filename('simple-0.1-1-py2-none-any.whl')
('simple', <Version('0.1')>, (1, ''), frozenset({<py2-none-any @ 140419507927680>}))

I will update the description to be _ is deprecated as a seperator between version and the build tag, use - instead.

With the current special case, anything after the _ is tacked onto the version. So Wheel("simple-0.1_1-py2-none-any.whl") would be a version of 0.1-1. This normalizes to 0.1.post1, so in this case, it would be more appropriate to say that _ is deprecated as a separator between a release segment and an implicit post release segment. However, taking a look an example from the linked issue in the code, translate_toolkit-1.9.0_pinterest3-py27-none-any.whl could be using _ as a separator between the version and build tag (although, it is ambiguous as pinterest3 is not a valid build tag).

On the other hand, I scraped the index pages for the top 8000 PyPI packages and could only find 4 ancient wheels that have this quirk in their filename. It may be simply best to suggest using either a post release or build tag, or neither and call it a day.

j2cli-0.3.0_1-py2-none-any.whl (2014-08-14T16:03:35.935783Z)
j2cli-0.3.1_0-py2-none-any.whl (2014-10-08T13:25:50.237961Z)
password_strength-0.0.1_1-py2-none-any.whl (2014-08-14T15:45:44.306377Z)
password_strength-0.0.2_0-py2-none-any.whl (2014-08-14T16:38:50.239827Z)

Also, technically _ is still allowed in the wheel version as pre or post release separators and packaging will happily parse them:

>>> from packaging.utils import parse_wheel_filename
>>> parse_wheel_filename("six-1.16.0_post1-py3-none-any.whl")
('six', <Version('1.16.0.post1')>, (), frozenset({<py3-none-any @ 129024502605504>}))

So this deprecation warning is technically overly broad, although in fairness, using _ does violate the spirit of the wheel specification as the version should (not a MUST though) be normalized (eliminating the underscore).

I guess the difference between parse_wheel_filename and Wheel.wheel_file_re is more complex than I thought. There are two choices as I see it:

1. Attempt to morely clearly explain the issue in the description, saying the user might need to update the wheel file
2. Attempt to parse first with parse_wheel_filename and then fallback to Wheel.wheel_file_re, this will require moving some existing code around and reworking what types they produce, etc.

I'm strongly inclined to go with "1." as it appears that using _ here is very uncommon. But if "2." is prefered I will implement that.

I prefer (1). If I understand the problem correctly, we'd be warning the user if pip encounters a wheel with _ in the version part of the filename, saying something like "Wheel filename {filename!r} uses an invalid filename format, as the version part {_version!r} is not correctly normalised, and contains an underscore character. Future versions of pip may fail to recognise this wheel." And the resolution could be "rename the wheel to use a correctly normalised version part (this may require updating the version in the project metadata)".

Thanks all, updated!

Although, it will be funny if no one ever reads the message outside this PR 😉

I'm not really sure what this should say (probably a simplified version of the deprecation message), but this should be renamed to 12918.removal.rst which yes can be used for deprecations as well.

Updated.

@notatallshaw Could you file an issue for 25.1, to track this removal?