docs(utils): properly document is_normalized_name vs canonicalize_name - #1291

Won't this have a performance impact? Checking something is cheaper than modifying a string, I'd expect? I'll trigger the CI and see if we have a perf test for this.

Pushed eab1122 to address the lint failure from tests/test_utils.py formatting.

Local verification:

python -m pytest tests/test_utils.py -q
uvx nox -s lint -- --show-diff-on-failure

Good point. I pushed b2988d8 to avoid calling canonicalize_name() from is_normalized_name().

The implementation now checks the same roundtrip conditions directly: already lowercase, no _, no ., and no repeated --. That keeps the leading/trailing hyphen behavior covered by the new tests, while avoiding the extra replace() calls and condensation loop for names that are already normalized.

Local verification:

• python -m pytest tests/test_utils.py tests/test_requirements.py -q
• uvx nox -s lint -- --show-diff-on-failure

Good point — you're right, and I think it reframes this PR.

Since PEP 508 names must start and end with an alphanumeric, -foo/foo- aren't valid names to begin with. Over the domain of valid names, canonicalize_name never yields a leading/trailing hyphen, so the original [a-z0-9]+(?:-[a-z0-9]+)* (with re.ASCII) already matches exactly the set of canonicalize_name fixed points — and it rejects non-ASCII for free. The edge cases I added only differ for inputs that aren't valid names, where the roundtrip "guarantee" is moot anyway.

So I'd rather drop the behavior change: keep the original regex, and instead just fix the docstring, which currently states the roundtrip relationship without noting it only holds for valid names. Happy to reduce this PR to that (revert the regex + the edge-hyphen test, tighten the docstring), or to close it if you'd prefer to touch the docstring separately. Which would you like?

I think fixing the docstring is the right path forward for now. We should look into changing the standards first if we do want the round trip property.

Done — reduced to the docstring change. 2d7c2fa rebases onto current main and drops the regex change and the tests I'd added, so is_normalized_name behaviour is untouched. The docstring now notes the roundtrip only characterizes normalized names for valid names, with doctests for the leading-hyphen case:

>>> canonicalize_name("_not_legal")
'-not-legal'
>>> is_normalized_name("-not-legal")  # roundtrips, but not a valid name
False

Diff is src/packaging/utils.py only (+12/-3); doctests and ruff pass.

Though this worries me: the standard clearly indicate the current regex is correct, leading and trailing hyphens are not allowed - that's from https://peps.python.org/pep-0508/#names. The normalization spec was a different PEP: https://peps.python.org/pep-0503/#normalized-names and it does allow leading/trailing hyphens, though I think it's more likely that's an oversight. There are now consolidated into a single place:

https://peps.python.org/pep-0508/#names

Where you can see the "contradicting" rules next to teach other. Packaging currently implements exactly those rules, though.

(And, in practice, it means you can't put any name in to normalize_name and get a normalized version - leading/trailing symbols break, though the stated guarantee that these are related is currently wrong)

What does packaging.python.org say, as that's the official spec.

Ahh, sorry, I copied and pasted incorrectly. It was supposed to be:

There are now consolidated into a single place:

https://packaging.python.org/en/latest/specifications/name-normalization

Instead I linked to https://peps.python.org/pep-0508/#names again, sorry! They sit next to each other there.