python · jaraco · Apr 27, 2025 · Jun 27, 2024 · Apr 27, 2025 · Apr 27, 2025
diff --git a/importlib_metadata/__init__.py b/importlib_metadata/__init__.py
@@ -27,7 +27,7 @@
 from importlib import import_module
 from importlib.abc import MetaPathFinder
 from itertools import starmap
-from typing import Any, cast
+from typing import Any
 
 from . import _meta
 from ._collections import FreezableDefaultDict, Pair
@@ -38,6 +38,7 @@
 from ._functools import method_cache, pass_none
 from ._itertools import always_iterable, bucket, unique_everseen
 from ._meta import PackageMetadata, SimplePath
+from ._typing import md_none
 from .compat import py39, py311
 
 __all__ = [
@@ -511,7 +512,7 @@ def _discover_resolvers():
         return filter(None, declared)
 
     @property
-    def metadata(self) -> _meta.PackageMetadata:
+    def metadata(self) -> _meta.PackageMetadata | None:
         """Return the parsed metadata for this Distribution.
 
         The returned object will have keys that name the various bits of
@@ -521,24 +522,29 @@ def metadata(self) -> _meta.PackageMetadata:
         Custom providers may provide the METADATA file or override this
         property.
         """
-        # deferred for performance (python/cpython#109829)
-        from . import _adapters
 
-        opt_text = (
+        text = (
             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('')
         )
-        text = cast(str, opt_text)
+        return self._assemble_message(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))
 
     @property
     def name(self) -> str:
         """Return the 'Name' metadata for the distribution package."""
-        return self.metadata['Name']
+        return md_none(self.metadata)['Name']
 
     @property
     def _normalized_name(self):
@@ -548,7 +554,7 @@ def _normalized_name(self):
     @property
     def version(self) -> str:
         """Return the 'Version' metadata for the distribution package."""
-        return self.metadata['Version']
+        return md_none(self.metadata)['Version']
 
     @property
     def entry_points(self) -> EntryPoints:
@@ -1045,7 +1051,7 @@ def distributions(**kwargs) -> Iterable[Distribution]:
     return Distribution.discover(**kwargs)
 
 
-def metadata(distribution_name: str) -> _meta.PackageMetadata:
+def metadata(distribution_name: str) -> _meta.PackageMetadata | None:
     """Get the metadata for the named package.
 
     :param distribution_name: The name of the distribution package to query.
@@ -1120,7 +1126,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(dist.metadata['Name'])
+            pkg_to_dist[pkg].append(md_none(dist.metadata)['Name'])
     return dict(pkg_to_dist)
 
 

diff --git a/importlib_metadata/_typing.py b/importlib_metadata/_typing.py
@@ -0,0 +1,15 @@
+import functools
+import typing
+
+from ._meta import PackageMetadata
+
+md_none = functools.partial(typing.cast, PackageMetadata)
+"""
+Suppress type errors for optional metadata.
+
+Although Distribution.metadata can return None when metadata is corrupt
+and thus None, allow callers to assume it's not None and crash if
+that's the case.
+
+# python/importlib_metadata#493
+"""
diff --git a/importlib_metadata/compat/py39.py b/importlib_metadata/compat/py39.py
@@ -12,6 +12,8 @@
 else:
     Distribution = EntryPoint = Any
 
+from .._typing import md_none
+
 
 def normalized_name(dist: Distribution) -> str | None:
     """
@@ -22,7 +24,9 @@ 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 dist.metadata['Name'])
+        return Prepared.normalize(
+            getattr(dist, "name", None) or md_none(dist.metadata)['Name']
+        )
 
 
 def ep_matches(ep: EntryPoint, **params) -> bool:

diff --git a/newsfragments/493.feature.rst b/newsfragments/493.feature.rst
@@ -0,0 +1 @@
+``.metadata()`` (and ``Distribution.metadata``) can now return ``None`` if the metadata directory exists but not metadata file is present.
diff --git a/tests/test_main.py b/tests/test_main.py
@@ -155,6 +155,16 @@ def test_valid_dists_preferred(self):
         dist = Distribution.from_name('foo')
         assert dist.version == "1.0"
 
+    def test_missing_metadata(self):
+        """
+        Dists with a missing metadata file should return None.
+
+        Ref python/importlib_metadata#493.
+        """
+        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
+
 
 class NonASCIITests(fixtures.OnSysPath, fixtures.SiteDir, unittest.TestCase):
     @staticmethod
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		``.metadata()`` (and ``Distribution.metadata``) can now return ``None`` if the metadata directory exists but not metadata file is present.