Detect the presence of metadata without reading it.

`_prefer_valid` decided validity by consulting `metadata`, which runs the
whole METADATA file through the email parser only for the result to be
discarded. Give `PathDistribution` a `_has_metadata` that detects the
metadata file without opening it, and make it the preference's predicate.

The interface offers nothing as cheap for a distribution that isn't one of
ours: `locate_file` resolves against the package root rather than the
metadata, and every other member loads the metadata or parses it. So those
fall back to `read_text`, which also closes a gap, as the `MetadataNotFound`
of a distribution deriving from `importlib.metadata` is a different class
and escaped the preference rather than marking the distribution invalid.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: jaraco

importlib_metadata/__init__.py

@@ -27,15 +27,14 @@
 from importlib import import_module
 from importlib.abc import MetaPathFinder
 from itertools import starmap
-from typing import Any
+from typing import Any, TypeVar
 
 from ._collections import FreezableDefaultDict, Pair
 from ._compat import (
     NullFinder,
     install,
     localize,
 )
-from ._context import ExceptionTrap
 from ._functools import apply, compose, method_cache, noop, pass_none, passthrough
 from ._itertools import always_iterable, bucket, unique_everseen
 from ._meta import (
@@ -67,6 +66,9 @@
 ]
 
 
+_D = TypeVar('_D', bound=IDistribution)
+
+
 class PackageNotFoundError(ModuleNotFoundError):
     """The package was not found."""
 
@@ -520,18 +522,14 @@ def discover(
         )
 
     @staticmethod
-    def _prefer_valid(dists: Iterable[Distribution]) -> Iterable[Distribution]:
+    def _prefer_valid(dists: Iterable[_D]) -> Iterable[_D]:
         """
         Prefer (move to the front) distributions that have metadata.
 
         Ref python/importlib_resources#489.
         """
 
-        has_metadata = ExceptionTrap(MetadataNotFound).passes(
-            operator.attrgetter('metadata')
-        )
-
-        buckets = bucket(dists, has_metadata)
+        buckets = bucket(dists, _has_metadata)
         return itertools.chain(buckets[True], buckets[False])
 
     @staticmethod
@@ -1078,6 +1076,22 @@ def read_text(self, filename: str | os.PathLike[str]) -> str | None:
 
     read_text.__doc__ = Distribution.read_text.__doc__
 
+    @property
+    def _has_metadata(self) -> bool:
+        """
+        Detect the metadata file without opening it
+        (python/importlib_metadata#534).
+
+        An old-style egg-info file, whose metadata is the
+        distribution's own path, is read; there is nothing to detect
+        without reading it.
+        """
+        return (
+            self._path.joinpath('METADATA').exists()
+            or self._path.joinpath('PKG-INFO').exists()
+            or bool(self.read_text(''))
+        )
+
     def locate_file(self, path: str | os.PathLike[str]) -> SimplePath:
         return self._path.parent / path
 
@@ -1148,6 +1162,26 @@ def version(distribution_name: str) -> str:
     return distribution(distribution_name).version
 
 
+def _has_metadata(dist: IDistribution) -> bool:
+    """
+    Whether ``dist`` supplies metadata.
+
+    A ``PathDistribution`` detects the metadata without reading it. For
+    any other distribution, including a provider's own subclass passed
+    through unadapted (#486), the interface offers nothing cheaper than
+    ``read_text``; ``locate_file`` resolves against the package root and
+    not the metadata, and every other member loads the metadata or
+    parses it. Reading it is, notably, still cheaper than asking for
+    ``metadata``, whose ``MetadataNotFound`` is a different class when
+    raised by a distribution deriving from ``importlib.metadata``.
+    """
+    with suppress(AttributeError):
+        return dist._has_metadata  # type: ignore[attr-defined]
+    return bool(
+        dist.read_text('METADATA') or dist.read_text('PKG-INFO') or dist.read_text('')
+    )
+
+
 _unique = functools.partial(
     unique_everseen,
     key=operator.attrgetter('_normalized_name'),

newsfragments/+foreign-metadata-not-found.bugfix.rst

@@ -0,0 +1,5 @@
+The preference for valid distributions no longer propagates the
+``MetadataNotFound`` of a distribution that a provider derived from
+``importlib.metadata``, whose exception is a different class from this
+package's and so escaped the preference rather than marking the distribution
+invalid.

newsfragments/+has-metadata.feature.rst

@@ -0,0 +1,4 @@
+Detecting whether a distribution supplies metadata no longer reads or parses
+that metadata where the metadata directory can be inspected instead, so
+retrieving a distribution by name, which prefers the valid candidates, is
+substantially faster.

tests/compat/test_localize.py

@@ -119,6 +119,24 @@ def test_conforming_provider_is_not_warned_about(self):
             assert distribution('distinfo-pkg').version == '1.0.0'
         assert not [str(warning.message) for warning in caught]
 
+    def test_dist_without_metadata_is_deferred(self):
+        """
+        A provider's own distribution supplies no detection of its own,
+        so the metadata is sought through ``read_text``. Asking for
+        ``metadata`` instead would raise, as the ``MetadataNotFound``
+        of a distribution deriving from ``importlib.metadata`` is a
+        different class.
+        """
+
+        class Empty(stdlib.Distribution):
+            def read_text(self, filename):
+                return None
+
+            def locate_file(self, path):
+                return None
+
+        assert not importlib_metadata._has_metadata(Empty())
+
 
 class ConformanceCheckTests(unittest.TestCase):
     @unittest.skipIf(