API incompatibility with `importlib.metadata` (or at least the API is not type-safe?)

When 3rd-party MetaPathFinder are implemented using importlib.metadata, the return types in importlib_metadata are not respected, which causes the API to behave in an unexpected way (with unexpected errors).

This is an example similar to the one identified in https://github.com/pypa/pyproject-hooks/pull/195#issuecomment-2088695300 and https://github.com/pypa/setuptools/issues/4338:

mkdir -p /tmp/stash/private_path/_test-0.0.1.dist-info
cat <<EOF > /tmp/stash/private_path/_test-0.0.1.dist-info/METADATA
Name: _test
Version: 0.0.1
EOF

cat <<EOF > /tmp/stash/private_path/_test-0.0.1.dist-info/entry_points.txt
[_test.importlib_metadata]
hello = world
EOF

cat <<EOF > /tmp/stash/install_finder.py
import sys
from importlib.machinery import PathFinder
from importlib.metadata import DistributionFinder, MetadataPathFinder


class _ExampleFinder:
    def __init__(self, private_path):
        self.private_path = private_path


    def find_spec(self, fullname, _path, _target=None):
        if "." in fullname:
            # Rely on importlib to find nested modules based on parent's path
            return None

        # Ignore other items in _path or sys.path and use private_path instead:
        return PathFinder.find_spec(fullname, path=self.private_path)

    def find_distributions(self, context=None):
        context = DistributionFinder.Context(path=self.private_path)
        return MetadataPathFinder.find_distributions(context=context)


sys.meta_path.insert(0, _ExampleFinder(["/tmp/stash/private_path"]))
EOF

cd /tmp/stash/
python3.8 -m venv .venv
.venv/bin/python -m pip install -U importlib-metadata
.venv/bin/python

>>> import install_finder
>>> from importlib_metadata import distribution
>>> distribution("_test").entry_points.select(group="_test.importlib_metadata")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'list' object has no attribute 'select'

The expected behaviour as per API documentation would be:

>>> distribution("_test").entry_points.select(group="_test.importlib_metadata")
EntryPoints((EntryPoint(name='hello', value='world', group='_test.importlib_metadata'),))

It seems that the origin of this problem is a little "lie" in the API definition:

Instead of

importlib_metadata.Distribution.discover(...) -> Iterable[importlib_metadata.Distribution]

what actually happens is:

importlib_metadata.Distribution.discover(...) -> Iterable[importlib_metadata.Distribution | importlib.metadata.Distribution]

and that propagates throughout the whole API.

I haven't tested, but there is potential for other internal errors too, if internally importlib_metadata is relying that the objects will have type importlib_metadata.Distribution to call newer APIs.

It is probably worthy to change the return type of importlib_metadata.Distribution.discover(...) to Iterable[importlib_metadata.Distribution | importlib.metadata.Distribution] and then run the type checkers on the lowest Python supported (I suppose Python 3.8), to see if everything is OK.

It also means that consumers of importlib_metadata cannot rely on the newer APIs (unless they are sure that 3r-party packages installed in their environment are not using importlib.metadata).

Commencez par reproduire l’exemple documenté avec le MetaPathFinder personnalisé et l’environnement Python 3.8 décrit dans l’issue. Examinez Distribution.discover et le flux de discovery associé, puis exécutez des vérificateurs de types sur la baseline prise en charge afin de vérifier que les distributions tierces de importlib.metadata et les résultats de leur entry_points sont traités de manière cohérente.