Merge pull request #263 from FFY00/typed-metadata

importlib_metadata: define protocol for Distribution.metadata

Author: jaraco

.github/workflows/automerge.yml

@@ -0,0 +1,27 @@
+name: automerge
+on:
+  pull_request:
+    types:
+      - labeled
+      - unlabeled
+      - synchronize
+      - opened
+      - edited
+      - ready_for_review
+      - reopened
+      - unlocked
+  pull_request_review:
+    types:
+      - submitted
+  check_suite:
+    types:
+      - completed
+  status: {}
+jobs:
+  automerge:
+    runs-on: ubuntu-latest
+    steps:
+      - name: automerge
+        uses: "pascalgn/[email protected]"
+        env:
+          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

CHANGES.rst

@@ -1,3 +1,11 @@
+v3.2.0
+======
+
+* The object returned by ``metadata()`` now has a
+  formally-defined protocol called ``PackageMetadata``
+  with declared support for the ``.get_all()`` method.
+  Fixes #126.
+
 v3.1.1
 ======
 

docs/using.rst

@@ -108,8 +108,9 @@ Every distribution includes some metadata, which you can extract using the
 
     >>> wheel_metadata = metadata('wheel')
 
-The keys of the returned data structure [#f1]_ name the metadata keywords, and
-their values are returned unparsed from the distribution metadata::
+The keys of the returned data structure, a ``PackageMetadata``,
+name the metadata keywords, and
+the values are returned unparsed from the distribution metadata::
 
     >>> wheel_metadata['Requires-Python']
     '>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'

importlib_metadata/__init__.py

@@ -16,13 +16,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__ = [
@@ -161,6 +163,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."""
 
@@ -245,7 +266,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
@@ -576,11 +597,11 @@ def distributions(**kwargs):
     return Distribution.discover(**kwargs)
 
 
-def metadata(distribution_name):
+def metadata(distribution_name) -> PackageMetadata:
     """Get the metadata for the named package.
 
     :param distribution_name: The name of the distribution package to query.
-    :return: An email.Message containing the parsed metadata.
+    :return: A PackageMetadata containing the parsed metadata.
     """
     return Distribution.from_name(distribution_name).metadata
 

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]