feat: filenames

[henryiii]

This builds on #409 and #1009 to add a packaging.filenames module.

Compared to #1009, this:

• Avoids inheritance and removes the Filename.from_filename method, which isn't usable without manual checking anyway due to not knowing which type is produced.
• strict= is a (required) argument of .from_filename now. Most logic is there.
• Classic functions use this new infrastructure
• Utility functions related to names are moved, but re-exported for back-compat
• Docs added
• underscore=True option added to canonicalize_name, better perf than just replacing - with _ afterwards

Decisions to be made or validated:

• With strict=True, maybe we should require sorted tag sets? (I think so, based on todo in [DRAFT] Add packaging.filenames API #1009)
• I made .name the traditionally canonical name, rather than the underscore one, I think that's best?
• The classic (strict=False) method checks for __ for some reason. It's the only one it doesn't normalize. Maybe that should be pulled out to just the classic function?
• We don't need one that strips final 0's from versions, right?

Todos:

• Enforce compressed tag set ordering with strict=True
• General alignment w/ error messages vs. what PyPI uses
• Fill out tests to handle 100% coverage

Closes:

• Close Utility functions to compose file distribution names #408
• Close feat: add packaging.utils.compose_wheel_filename and compose_sdist_filename #409
• Close Ambiguous version parsing in parse_sdist_filename #527
• Close Bug: parse_wheel_filename permits non-normalized versions. #873
• Close Bug: parse_wheel_filenames accepts wheel filenames with unsorted compressed tag sets #909
• Close [DRAFT] Add packaging.filenames API #1009

AI usage disclaimer: I used copilot in VSCode to help fill out the coverage in 997c5a8, and some help with docs before that.

[henryiii]

@di, don't know how to do the "General alignment w/ error messages vs. what PyPI uses" step.

[di]

@di, don't know how to do the "General alignment w/ error messages vs. what PyPI uses" step.

So this was basically, packaging has one set of exception messages for when certain errors happen here, PyPI has a different, but similar set. Ideally we'd just be able to catch these errors and relay the message that originates from packaging, but they are not 1:1, so I was hoping to align them to simplify them.

[henryiii]

I like the idea of waiting till Variants are ready to add this, so someone using the new API is also aware of variants. #1148.

[henryiii]

This is getting stable again, dropping my design points while working on it:

• This isn't a dataclass; the dataclass version was quite a bit slower (10-30%)
• I'm not fond of .validate() being called on an existing filename, but it solved several issues:
  • Keeping the filename (similar to the proposed Version change) means you can access the original file on disk without a seperate storage
  • Doing it this way saves a second parse; pretty much every other design, like a standalone validate_wheel_filename function, reparses
  • Keeping it out of the constructor means you can handle the errors and still access the normalized name without a second parse
• parameter order: tags can't be optional (as it can't be empty), but build_tag is usually not given, so I've ordered it with build tags afterwards (vs. matchign the order in the wheel filename). I made build_tag and variant keyword only to reduce confusion.
• Pickles are the original string, not as fast but very easy to keep stable. copy/deepcopy don't need to do anything since it's immutable.
• Exception groups allow .validate() to not have any parameters, and instead the user can see what's wrong and skip stuff they don't care about (it's possible to rebuild the original less strict behavior for example)
• I didn't set up a shared base class because the code savings wasn't worth it for just two classes, IMO. But it's mostly a matter of taste, I could be convinced to go with a shared base class.
• We lose a little performance (7-8%), but I don't think it's avoidable, as the ambiguous parse from variant or build_tag for 6 element wheel names costs a little. I've tried to keep it minimal.

Performance:

🤖 AI text below 🤖

Each value is in µs per filename, averaged over two runs.

Operation	3.12 main	3.12 branch	3.14 main	3.14 branch
parse_wheel_filename	1.33	1.42 (+7%)	1.23	1.33 (+8%)
parse_sdist_filename	0.46	0.48	0.41	0.43
WheelFilename.from_filename	—	1.45	—	1.37
WheelFilename.from_filename + validate()	—	2.76 (was 3.77)	—	2.63 (was 3.61)
WheelFilename.to_filename	—	0.78	—	0.77
SourceDistributionFilename.from_filename	—	0.51	—	0.47
SourceDistributionFilename.from_filename + validate()	—	0.97 (was 1.70)	—	0.85 (was 1.55)
SourceDistributionFilename.to_filename	—	0.32	—	0.30