Mark PackageMetadata.__getitem__ as deprecated for missing values

CHANGES.rst

@@ -1,3 +1,10 @@
+v5.2.0
+======
+
+* #371: Deprecated expectation that ``PackageMetadata.__getitem__``
+  will return ``None`` for missing keys. In the future, it will raise a
+  ``KeyError``.
+
 v5.1.0
 ======
 

importlib_metadata/_adapters.py

@@ -1,8 +1,20 @@
+import functools
+import warnings
 import re
 import textwrap
 import email.message
 
 from ._text import FoldedCase
+from ._compat import pypy_partial
+
+
+# Do not remove prior to 2024-01-01 or Python 3.14
+_warn = functools.partial(
+    warnings.warn,
+    "Implicit None on return values is deprecated and will raise KeyErrors.",
+    DeprecationWarning,
+    stacklevel=pypy_partial(2),
+)
 
 
 class Message(email.message.Message):
@@ -39,6 +51,16 @@ def __init__(self, *args, **kwargs):
     def __iter__(self):
         return super().__iter__()
 
+    def __getitem__(self, item):
+        """
+        Warn users that a ``KeyError`` can be expected when a
+        mising key is supplied. Ref python/importlib_metadata#371.
+        """
+        res = super().__getitem__(item)
+        if res is None:
+            _warn()
+        return res
+
     def _repair_headers(self):
         def redent(value):
             "Correct for RFC822 indentation"

tests/test_api.py

@@ -141,6 +141,14 @@ def test_importlib_metadata_version(self):
         resolved = version('importlib-metadata')
         assert re.match(self.version_pattern, resolved)
 
+    def test_missing_key_legacy(self):
+        """
+        Requesting a missing key will still return None, but warn.
+        """
+        md = metadata('distinfo-pkg')
+        with suppress_known_deprecation():
+            assert md['does-not-exist'] is None
+
     @staticmethod
     def _test_files(files):
         root = files[0].root