Improve metadata validation and handling of invalid distributions

[sepehr-rs]

What does this PR do?

This PR addresses #13638 by introducing a centralized metadata validation layer for installed distributions. Invalid distributions are now detected consistently, with clearer warning messages explaining the underlying issue, while commands such as show and uninstall continue to operate on invalid installations where possible to help users recover from broken distributions.

I'm happy to hear any feedback on the overall approach or implementation.

PR Checklist:

• I agree to follow the PSF Code of Conduct.
• I have read and have followed the CONTRIBUTING.md file.
• I have added a news file fragment (or this PR does not need one).
• I have read and followed the AI_POLICY.md file, and if any AI tools were used, I have disclosed it below.

Assisted-by: Claude (code review)

[sepehr-rs]

CI is currently failing in two cases, and I wanted to check on the intended behavior before fixing them.

1. Invalid names in .egg-info distributions: Existing tests expect packages with invalid names (e.g. _leadingunderscore, trailingdash-) to be filtered out even for legacy .egg-info installs. The new validate_distribution intentionally skips validation for non-.dist-info distributions, so these now pass through. Should name validation also apply to .egg-info, or is the current behavior preferred?

2. Legacy version strings: There are existing tests using a package with version 2010i that expect pip list/pip freeze to succeed without warnings. The new validation system now warns and skips these packages, causing those tests to fail.

The second one feels like the bigger design question. Pip has tolerated legacy version strings till now, so skipping these distributions in list/freeze could be a behavior change. Should we keep the old behavior, or is the stricter validation intentional and the tests should be updated?

Happy to implement either approach.

[2ykwang]

might be moot depending on the design outcome, but left a small test nit I noticed while reading.

[ichard26]

To answer your design questions:

1. Invalid names in .egg-info distributions: Existing tests expect packages with invalid names (e.g. _leadingunderscore, trailingdash-) to be filtered out even for legacy .egg-info installs. The new validate_distribution intentionally skips validation for non-.dist-info distributions, so these now pass through. Should name validation also apply to .egg-info, or is the current behavior preferred?

We should maintain the old behaviour here. The goal here to become stricter over time.

2. Legacy version strings: There are existing tests using a package with version 2010i that expect pip list/pip freeze to succeed without warnings. The new validation system now warns and skips these packages, causing those tests to fail.

Legacy versions are still part of the packaging standards and are perfectly legal when using the === version operator. A distribution shouldn't be skipped solely because it uses legacy versions (not all everything in pip handles legacy versions well, but we still support them).

Also, have you checked the performance implications of this metadata validation layer? I left some comments on performance in the linked issue: #13638 (comment)

[sepehr-rs]

Thanks a lot for the review @ichard26!
Sure, I will audit the code to make sure legacy versions and .egg-info invalid names are now supported.

Also, have you checked the performance implications of this metadata validation layer?

Oh, thanks for flagging this. I benchmarked four commands (pip check, pip list, pip freeze, pip list --format=freeze) across environment sizes from 50 to 500 packages, comparing pip 26.2.1 against this PR.

The listing commands show no meaningful overhead; the slope difference is ≤0.03 ms/package and within noise throughout. pip check is the only command with a real cost: roughly +0.16 ms/package (baseline ~0.26 ms/pkg vs patched ~0.42 ms/pkg), which is linear with package count.

I've attached a plot showing the scaling behaviour:

Also, keep in mind that benchmark script only creates valid packages, not invalid ones. Since the code returns early on the first validation failure, corrupt packages are cheaper to validate than valid ones; so real-world overhead on pip check should be at or below these numbers in environments with invalid distributions.

Here's the benchmark script that I created with the help of Claude in case you want to run it yourself.