add .get() to the PackageMetadata protocol

CHANGES.rst

@@ -1,3 +1,10 @@
+v6.2.0
+======
+
+* #384: ``PackageMetadata`` now stipulates an additional ``get``
+  method allowing for easy querying of metadata keys that may not
+  be present.
+
 v6.1.0
 ======
 

importlib_metadata/_meta.py

@@ -18,6 +18,14 @@ def __getitem__(self, key: str) -> str:
     def __iter__(self) -> Iterator[str]:
         ...  # pragma: no cover
 
+    @overload
+    def get(self, name: str, failobj: None = None) -> Optional[str]:
+        ...  # pragma: no cover
+
+    @overload
+    def get(self, name: str, failobj: _T) -> Union[str, _T]:
+        ...  # pragma: no cover
+
     # overload per python/importlib_metadata#435
     @overload
     def get_all(self, name: str, failobj: None = None) -> Optional[List[Any]]:

tests/test_api.py

@@ -148,6 +148,20 @@ def test_missing_key_legacy(self):
         with suppress_known_deprecation():
             assert md['does-not-exist'] is None
 
+    def test_get_key(self):
+        """
+        Getting a key gets the key.
+        """
+        md = metadata('egginfo-pkg')
+        assert md.get('Name') == 'egginfo-pkg'
+
+    def test_get_missing_key(self):
+        """
+        Requesting a missing key will return None.
+        """
+        md = metadata('distinfo-pkg')
+        assert md.get('does-not-exist') is None
+
     @staticmethod
     def _test_files(files):
         root = files[0].root