`packages_distributions` relies on setuptools implementation detail

[konstin]

This is a follow-up to #402.

packages_distributions reads top_level.txt to determine the names. This file isn't part of any PEP and to my knowledge only implemented by setuptools, as a historical artifact from eggs. This leads users to believe that build backends not supporting this function have a bug (astral-sh/uv#16423).

Would it be possible to update the documentation to accurately reflect that this is not a problem with some PEP 660 build backends not supplying top-level names, but that this function is generally not expected to work with editable installs at all, with the historical exception of setuptools?

(This may change with PEP 794)

importlib_metadata/importlib_metadata/__init__.py

Lines 1133 to 1134 in 95ecf2a

	def _top_level_declared(dist):
	return (dist.read_text('top_level.txt') or '').split()

[jaraco]

I'd accept a pull request to document this limitation. I would like to see some proper, formal support for a package to represent deterministically the top-level names that it exposes.

[stefanor]

That is at least used in a context where the file not existing is probably not a problem:

importlib_metadata/importlib_metadata/__init__.py

Line 1144 in d8a7576

for pkg in _top_level_declared(dist) or _top_level_inferred(dist):

I wouldn't say it's relying on this file.

[konstin]

I consider it a bug in the sense it makes an importlib function rely on non-spec behavior of setuptools. See the uv bug for an MRE, where a user ran into a specific case where it doesn't work when not using setuptools: astral-sh/uv#16423

[bunny-therapist]

Shouldn't this function be updated now that PEP 794 has been accepted?

It seems like both in importlib_metadata and in cpython itself, nothing has changed in packages_distributions?

[molloyzak13]

reply_target: #526
PEP 794 replaces what top_level.txt does, but build backends need to ship the new dist-info metadata first. until they do, packages_distributions() is stuck reading the old file. not really a bug in importlib_metadata, just waiting on the ecosystem side.

[bunny-therapist]

PEP 794 is supported by

• warehouse (i.e. pypi)
• hatch
• uv build backend
• packaging

It looks like setuptools does not have it yet, but they have an issue and a PR

Is it setuptools that importlib_metadata is waiting for? Is this planned? I would expect importlib_metadata to eventually read metadata according to PEP 794 with the old functionality (top_level.txt) as a fallback.