Misleading upload error message regarding local version

[webknjaz]

I was just pointed to https://github.com/gcovr/gcovr/actions/runs/16126694419/job/45507427524#step:10:210 with an explanation that "upload failed because of the development version", which I knew was incorrect.
It was due to the local version specifier that PEP 440 forbids.

The error message states that but doesn't mention PEP 440 or a place where it's defined:

400 The use of local versions in
<Version('8.4.dev26+g5f7e08fb2')> is not allowed. See
https://packaging.python.org/specifications/core-metadata for more
information.

The URL in the message points to the generic core packaging metadata web page that has no mention of PEP 440 or versioning limitations. The version provided does comply with the metadata spec, and so this is clearly a source of confusion for people who wouldn't know where to look.

Looks like the error message should point to different URLs depending on the cause of rejection. Or contain other clues regarding what's happening.

For this problem, the correct link would be https://packaging.python.org/en/latest/specifications/version-specifiers/#local-version-identifiers or at least https://peps.python.org/pep-0440/#local-version-identifiers.

P.S. I also noticed that Version.__repr__() seems to be leaking into the error message. So that's another/related area of improvement.

[di]

Thanks for the issue, I agree the error message is confusing. Part of the problem here is that the complete error message is coming from two different places:

a) the part specifically about the local version here:

warehouse/warehouse/forklift/metadata.py

Lines 113 to 120 in 5a3e4b3

	# We don't allow the use of the "local version" field when releasing to PyPI
	if metadata.version.local:
	errors.append(
	InvalidMetadata(
	"version",
	f"The use of local versions in {metadata.version!r} is not allowed.",
	)
	)

b) the part about a general metadata failure here:

warehouse/warehouse/forklift/legacy.py

Lines 624 to 640 in 5a3e4b3

	# Return an error for the field, using the first error that we can find
	# for that field
	error = errors[field_name][0]
	error_msg = str(error)
	request.metrics.increment(
	"warehouse.upload.failed", tags=["reason:invalid-metadata"]
	)
	raise _exc_with_message(
	HTTPBadRequest,
	" ".join(
	[
	error_msg + ("." if not error_msg.endswith(".") else ""),
	"See https://packaging.python.org/specifications/core-metadata "
	"for more information.",
	]
	),
	)

We may want to special-case this error instead.

P.S. I also noticed that Version.repr() seems to be leaking into the error message. So that's another/related area of improvement.

Looks like that's due to the formatting string in the first half of the error message -- I agree this should be the repr for a string instead.

[di]

Also, this probably could instead link to our own help page about why we don't permit local version identifiers.