Adopt "more sound" type annotations

docs/conf.py

@@ -69,4 +69,9 @@
     ('py:class', 'importlib_metadata._meta._T'),
     # Workaround for #435
     ('py:class', '_T'),
+    # importlib.metadata in stdlib does not have detailed API docs
+    # + `if TYPE_CHECKING` is not handled by sphinx:
+    ('py:class', 'stdlib._DistributionOrLegacy'),
+    ('py:class', 'stdlib._PackageMetadataOrLegacy'),
+    ('py:class', 'stdlib._List_PackagePathOrLegacy'),
 ]

importlib_metadata/__init__.py

@@ -18,7 +18,7 @@
 import collections
 
 from . import _meta
-from .compat import py39, py311
+from .compat import py39, py311, stdlib
 from ._collections import FreezableDefaultDict, Pair
 from ._compat import (
     NullFinder,
@@ -34,6 +34,7 @@
 from itertools import starmap
 from typing import Any, Iterable, List, Mapping, Match, Optional, Set, cast
 
+
 __all__ = [
     'Distribution',
     'DistributionFinder',
@@ -375,7 +376,7 @@ def locate_file(self, path: str | os.PathLike[str]) -> SimplePath:
         """
 
     @classmethod
-    def from_name(cls, name: str) -> Distribution:
+    def from_name(cls, name: str) -> stdlib._DistributionOrLegacy:
         """Return the Distribution for the given package name.
 
         :param name: The name of the distribution package to search for.
@@ -395,7 +396,7 @@ def from_name(cls, name: str) -> Distribution:
     @classmethod
     def discover(
         cls, *, context: Optional[DistributionFinder.Context] = None, **kwargs
-    ) -> Iterable[Distribution]:
+    ) -> Iterable[stdlib._DistributionOrLegacy]:
         """Return an iterable of Distribution objects for all packages.
 
         Pass a ``context`` or pass keyword arguments for constructing
@@ -941,7 +942,7 @@ def _name_from_stem(stem):
         return name
 
 
-def distribution(distribution_name: str) -> Distribution:
+def distribution(distribution_name: str) -> stdlib._DistributionOrLegacy:
     """Get the ``Distribution`` instance for the named package.
 
     :param distribution_name: The name of the distribution package as a string.
@@ -950,15 +951,15 @@ def distribution(distribution_name: str) -> Distribution:
     return Distribution.from_name(distribution_name)
 
 
-def distributions(**kwargs) -> Iterable[Distribution]:
+def distributions(**kwargs) -> Iterable[stdlib._DistributionOrLegacy]:
     """Get all ``Distribution`` instances in the current environment.
 
     :return: An iterable of ``Distribution`` instances.
     """
     return Distribution.discover(**kwargs)
 
 
-def metadata(distribution_name: str) -> _meta.PackageMetadata:
+def metadata(distribution_name: str) -> stdlib._PackageMetadataOrLegacy:
     """Get the metadata for the named package.
 
     :param distribution_name: The name of the distribution package to query.
@@ -1001,7 +1002,9 @@ def entry_points(**params) -> EntryPoints:
     return EntryPoints(eps).select(**params)
 
 
-def files(distribution_name: str) -> Optional[List[PackagePath]]:
+def files(
+    distribution_name: str,
+) -> Optional[stdlib._List_PackagePathOrLegacy]:
     """Return a list of files for the named package.
 
     :param distribution_name: The name of the distribution package to query.

importlib_metadata/compat/stdlib.py

@@ -0,0 +1,27 @@
+"""
+Compatibility layer with stdlib.
+Only needed when distributing via PyPI/3rd-party package.
+"""
+
+import sys
+from typing import TYPE_CHECKING, List, Union
+
+if TYPE_CHECKING:
+    # Avoid circular imports
+
+    from importlib import metadata as _legacy
+
+    from typing_extensions import TypeAlias
+
+    from .. import Distribution, PackagePath, _meta
+
+    if sys.version_info >= (3, 10):
+        from importlib.metadata import PackageMetadata as _legacy_Metadata
+    else:
+        from email.message import Message as _legacy_Metadata
+
+    _PackageMetadataOrLegacy: TypeAlias = Union[_legacy_Metadata, _meta.PackageMetadata]
+    _DistributionOrLegacy: TypeAlias = Union[_legacy.Distribution, Distribution]
+    _List_PackagePathOrLegacy: TypeAlias = Union[
+        List[_legacy.PackagePath], List[PackagePath]
+    ]