Raise MetadataNotFound when no metadata file was found.

Ref python/cpython#143387

Author: jaraco

NEWS.rst

@@ -1,3 +1,14 @@
+v8.8.0
+======
+
+Features
+--------
+
+- Added ``MetadataNotFound`` (subclass of ``FileNotFoundError``) and updated
+  ``Distribution.metadata``/``metadata()`` to raise it when the metadata files
+  are missing instead of returning ``None`` (python/cpython#143387).
+
+
 v8.7.1
 ======
 

importlib_metadata/__init__.py

@@ -38,14 +38,14 @@
 from ._functools import method_cache, noop, pass_none, passthrough
 from ._itertools import always_iterable, bucket, unique_everseen
 from ._meta import PackageMetadata, SimplePath
-from ._typing import md_none
 from .compat import py39, py311
 
 __all__ = [
     'Distribution',
     'DistributionFinder',
     'PackageMetadata',
     'PackageNotFoundError',
+    'MetadataNotFound',
     'SimplePath',
     'distribution',
     'distributions',
@@ -70,6 +70,10 @@ def name(self) -> str:  # type: ignore[override] # make readonly
         return name
 
 
+class MetadataNotFound(FileNotFoundError):
+    """No metadata file is present in the distribution."""
+
+
 class Sectioned:
     """
     A simple entry point config parser for performance
@@ -491,7 +495,14 @@ def _prefer_valid(dists: Iterable[Distribution]) -> Iterable[Distribution]:
 
         Ref python/importlib_resources#489.
         """
-        buckets = bucket(dists, lambda dist: bool(dist.metadata))
+
+        def has_metadata(dist: Distribution) -> bool:
+            with suppress(MetadataNotFound):
+                dist.metadata
+                return True
+            return False
+
+        buckets = bucket(dists, has_metadata)
         return itertools.chain(buckets[True], buckets[False])
 
     @staticmethod
@@ -512,7 +523,7 @@ def _discover_resolvers():
         return filter(None, declared)
 
     @property
-    def metadata(self) -> _meta.PackageMetadata | None:
+    def metadata(self) -> _meta.PackageMetadata:
         """Return the parsed metadata for this Distribution.
 
         The returned object will have keys that name the various bits of
@@ -521,6 +532,8 @@ def metadata(self) -> _meta.PackageMetadata | None:
 
         Custom providers may provide the METADATA file or override this
         property.
+
+        :raises MetadataNotFound: If no metadata file is present.
         """
 
         text = (
@@ -531,20 +544,25 @@ def metadata(self) -> _meta.PackageMetadata | None:
             # (which points to the egg-info file) attribute unchanged.
             or self.read_text('')
         )
-        return self._assemble_message(text)
+        return self._assemble_message(self._ensure_metadata_present(text))
 
     @staticmethod
-    @pass_none
     def _assemble_message(text: str) -> _meta.PackageMetadata:
         # deferred for performance (python/cpython#109829)
         from . import _adapters
 
         return _adapters.Message(email.message_from_string(text))
 
+    def _ensure_metadata_present(self, text: str | None) -> str:
+        if text is not None:
+            return text
+
+        raise MetadataNotFound('No package metadata was found.')
+
     @property
     def name(self) -> str:
         """Return the 'Name' metadata for the distribution package."""
-        return md_none(self.metadata)['Name']
+        return self.metadata['Name']
 
     @property
     def _normalized_name(self):
@@ -554,7 +572,7 @@ def _normalized_name(self):
     @property
     def version(self) -> str:
         """Return the 'Version' metadata for the distribution package."""
-        return md_none(self.metadata)['Version']
+        return self.metadata['Version']
 
     @property
     def entry_points(self) -> EntryPoints:
@@ -1067,11 +1085,12 @@ def distributions(**kwargs) -> Iterable[Distribution]:
     return Distribution.discover(**kwargs)
 
 
-def metadata(distribution_name: str) -> _meta.PackageMetadata | None:
+def metadata(distribution_name: str) -> _meta.PackageMetadata:
     """Get the metadata for the named package.
 
     :param distribution_name: The name of the distribution package to query.
     :return: A PackageMetadata containing the parsed metadata.
+    :raises MetadataNotFound: If no metadata file is present in the distribution.
     """
     return Distribution.from_name(distribution_name).metadata
 
@@ -1142,7 +1161,7 @@ def packages_distributions() -> Mapping[str, list[str]]:
     pkg_to_dist = collections.defaultdict(list)
     for dist in distributions():
         for pkg in _top_level_declared(dist) or _top_level_inferred(dist):
-            pkg_to_dist[pkg].append(md_none(dist.metadata)['Name'])
+            pkg_to_dist[pkg].append(dist.metadata['Name'])
     return dict(pkg_to_dist)
 
 

importlib_metadata/_typing.py

@@ -12,8 +12,6 @@
 else:
     Distribution = EntryPoint = Any
 
-from .._typing import md_none
-
 
 def normalized_name(dist: Distribution) -> str | None:
     """
@@ -24,9 +22,7 @@ def normalized_name(dist: Distribution) -> str | None:
     except AttributeError:
         from .. import Prepared  # -> delay to prevent circular imports.
 
-        return Prepared.normalize(
-            getattr(dist, "name", None) or md_none(dist.metadata)['Name']
-        )
+        return Prepared.normalize(getattr(dist, "name", None) or dist.metadata['Name'])
 
 
 def ep_matches(ep: EntryPoint, **params) -> bool:

importlib_metadata/compat/py39.py

@@ -0,0 +1 @@
+- Removed the internal ``md_none`` typing helper since ``Distribution.metadata`` now always returns ``PackageMetadata`` and raises ``MetadataNotFound`` when absent (python/cpython#143387).

newsfragments/+.removal.rst

@@ -9,6 +9,7 @@
 from importlib_metadata import (
     Distribution,
     EntryPoint,
+    MetadataNotFound,
     PackageNotFoundError,
     _unique,
     distributions,
@@ -157,13 +158,15 @@ def test_valid_dists_preferred(self):
 
     def test_missing_metadata(self):
         """
-        Dists with a missing metadata file should return None.
+        Dists with a missing metadata file should raise ``MetadataNotFound``.
 
-        Ref python/importlib_metadata#493.
+        Ref python/importlib_metadata#493 and python/cpython#143387.
         """
         fixtures.build_files(self.make_pkg('foo-4.3', files={}), self.site_dir)
-        assert Distribution.from_name('foo').metadata is None
-        assert metadata('foo') is None
+        with self.assertRaises(MetadataNotFound):
+            Distribution.from_name('foo').metadata
+        with self.assertRaises(MetadataNotFound):
+            metadata('foo')
 
 
 class NonASCIITests(fixtures.OnSysPath, fixtures.SiteDir, unittest.TestCase):