importlib_metadata: define protocol for Distribution.metadata

Signed-off-by: Filipe Laíns <lains@riseup.net>

importlib_metadata/__init__.py

@@ -17,13 +17,15 @@
     NullFinder,
     PyPy_repr,
     install,
+    Protocol,
 )
 
 from configparser import ConfigParser
 from contextlib import suppress
 from importlib import import_module
 from importlib.abc import MetaPathFinder
 from itertools import starmap
+from typing import Any, List, TypeVar, Union
 
 
 __all__ = [
@@ -166,6 +168,25 @@ def __repr__(self):
         return '<FileHash mode: {} value: {}>'.format(self.mode, self.value)
 
 
+_T = TypeVar("_T")
+
+
+class PackageMetadata(Protocol):
+    def __len__(self) -> int:
+        ...  # pragma: no cover
+
+    def __contains__(self, item: str) -> bool:
+        ...  # pragma: no cover
+
+    def __getitem__(self, key: str) -> str:
+        ...  # pragma: no cover
+
+    def get_all(self, name: str, failobj: _T = ...) -> Union[List[Any], _T]:
+        """
+        Return all values associated with a possibly multi-valued key.
+        """
+
+
 class Distribution:
     """A Python distribution package."""
 
@@ -250,7 +271,7 @@ def _local(cls, root='.'):
         return PathDistribution(zipp.Path(meta.build_as_zip(builder)))
 
     @property
-    def metadata(self):
+    def metadata(self) -> PackageMetadata:
         """Return the parsed metadata for this Distribution.
 
         The returned object will have keys that name the various bits of

importlib_metadata/_compat.py

@@ -1,7 +1,18 @@
 import sys
 
 
-__all__ = ['install', 'NullFinder', 'PyPy_repr']
+__all__ = ['install', 'NullFinder', 'PyPy_repr', 'Protocol']
+
+
+try:
+    from typing import Protocol
+except ImportError:  # pragma: no cover
+    """
+    pytest-mypy complains here because:
+    error: Incompatible import of "Protocol" (imported name has type
+    "typing_extensions._SpecialForm", local name has type "typing._SpecialForm")
+    """
+    from typing_extensions import Protocol  # type: ignore
 
 
 def install(cls):

setup.cfg

@@ -19,6 +19,7 @@ include_package_data = true
 python_requires = >=3.6
 install_requires =
     zipp>=0.5
+    typing-extensions>=3.6.4; python_version < "3.8"
 setup_requires = setuptools_scm[toml] >= 3.4.1
 
 [options.packages.find]