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 `Distribution` a `_has_metadata` that reads no further than
the text, through a `_metadata_text` that `metadata` shares so neither names
the files twice, and override it in `PathDistribution` to detect the
metadata file without opening it at all. An old-style egg-info file, which
is itself the metadata, is detected with `is_file`; a metadata directory
exists whether or not it holds anything, so its own presence says nothing.

The predicate is `_safe_has_metadata`, since a provider's own `Distribution`
subclass derives from `importlib.metadata` and is passed through unadapted
(#486), so it supplies neither helper. Reading its metadata rather than
asking it for `metadata` also closes a gap: the `MetadataNotFound` such a
distribution raises is a different class from this package's, so it 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, _safe_has_metadata)
         return itertools.chain(buckets[True], buckets[False])
 
     @staticmethod
@@ -566,15 +564,37 @@ def metadata(self) -> PackageMetadata:
         :raises MetadataNotFound: If no metadata file is present.
         """
 
-        text = (
+        text = self._metadata_text()
+        return self._assemble_message(self._ensure_metadata_present(text))
+
+    def _metadata_text(self) -> str | None:
+        """
+        The metadata text, if any.
+
+        Separate from ``metadata`` so that ``_has_metadata`` can name
+        the same files without repeating them and without paying to
+        parse what it finds.
+        """
+        return (
             self.read_text('METADATA')
             or self.read_text('PKG-INFO')
             # This last clause is here to support old egg-info files.  Its
             # effect is to just end up using the PathDistribution's self._path
             # (which points to the egg-info file) attribute unchanged.
             or self.read_text('')
         )
-        return self._assemble_message(self._ensure_metadata_present(text))
+
+    def _has_metadata(self) -> bool:
+        """
+        Whether this distribution supplies metadata.
+
+        Reads the metadata, as the interface offers nothing cheaper:
+        ``locate_file`` resolves against the package root and not the
+        metadata, and every other member loads the metadata or parses
+        it. A subclass able to detect the metadata without reading it
+        should override this (python/importlib_metadata#534).
+        """
+        return bool(self._metadata_text())
 
     @staticmethod
     def _assemble_message(text: str) -> PackageMetadata:
@@ -1078,6 +1098,24 @@ def read_text(self, filename: str | os.PathLike[str]) -> str | None:
 
     read_text.__doc__ = Distribution.read_text.__doc__
 
+    def _has_metadata(self) -> bool:
+        """
+        Detect the metadata file without opening it
+        (python/importlib_metadata#534).
+
+        The last clause is for an old-style egg-info file, whose
+        metadata is the distribution's own path; a metadata directory
+        is not itself metadata. ``SimplePath`` doesn't name
+        ``is_file``, but only these legacy paths reach that clause and
+        they arrive as a ``pathlib.Path`` or a ``zipfile.Path``, both
+        of which supply it.
+        """
+        return (
+            self._path.joinpath('METADATA').exists()
+            or self._path.joinpath('PKG-INFO').exists()
+            or self._path.is_file()  # type: ignore[attr-defined]
+        )
+
     def locate_file(self, path: str | os.PathLike[str]) -> SimplePath:
         return self._path.parent / path
 
@@ -1148,6 +1186,25 @@ def version(distribution_name: str) -> str:
     return distribution(distribution_name).version
 
 
+def _safe_has_metadata(dist: IDistribution) -> bool:
+    """
+    ``dist._has_metadata()``, for a distribution that may not supply it.
+
+    A provider's own ``Distribution`` subclass derives from
+    ``importlib.metadata`` and is passed through unadapted (#486), so
+    it has none; read its metadata as the default would. It supplies
+    no ``_metadata_text`` either, hence the unbound call.
+
+    Such a distribution cannot be asked for ``metadata`` behind a trap
+    instead. The ``MetadataNotFound`` it raises is the one from
+    ``importlib.metadata``, a different class from this package's,
+    which no trap of ours would catch.
+    """
+    with suppress(AttributeError):
+        return dist._has_metadata()  # type: ignore[attr-defined]
+    return bool(Distribution._metadata_text(dist))  # type: ignore[arg-type]
+
+
 _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._safe_has_metadata(Empty())
+
 
 class ConformanceCheckTests(unittest.TestCase):
     @unittest.skipIf(

tests/test_main.py

@@ -56,6 +56,25 @@ def test_abc_enforced(self):
         with self.assertRaises(TypeError):
             type('DistributionSubclass', (Distribution,), {})()
 
+    @fixtures.parameterize(
+        dict(text='Name: foo\nVersion: 1.0\n', expected=True),
+        dict(text=None, expected=False),
+    )
+    def test_detects_metadata_by_reading(self, text, expected):
+        """
+        A distribution that isn't path-based takes the default
+        detection, which reads what it cannot otherwise detect.
+        """
+
+        class Provided(Distribution):
+            def read_text(self, filename):
+                return text if filename == 'METADATA' else None
+
+            def locate_file(self, path):
+                return None  # pragma: no cover
+
+        assert Provided()._has_metadata() is expected
+
     @fixtures.parameterize(
         dict(name=None),
         dict(name=''),