Use more realistic return types

Author: abravalheri

importlib_metadata/__init__.py

@@ -31,6 +31,7 @@
 
 from contextlib import suppress
 from importlib import import_module
+from importlib import metadata as _legacy
 from importlib.abc import MetaPathFinder
 from itertools import starmap
 from typing import Any, Iterable, List, Mapping, Match, Optional, Set, cast
@@ -396,7 +397,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) -> Distribution | _legacy.Distribution:
         """Return the Distribution for the given package name.
 
         :param name: The name of the distribution package to search for.
@@ -416,7 +417,7 @@ def from_name(cls, name: str) -> Distribution:
     @classmethod
     def discover(
         cls, *, context: Optional[DistributionFinder.Context] = None, **kwargs
-    ) -> Iterable[Distribution]:
+    ) -> Iterable[Distribution | _legacy.Distribution]:
         """Return an iterable of Distribution objects for all packages.
 
         Pass a ``context`` or pass keyword arguments for constructing
@@ -963,7 +964,7 @@ def _name_from_stem(stem):
         return name
 
 
-def distribution(distribution_name: str) -> Distribution:
+def distribution(distribution_name: str) -> Distribution | _legacy.Distribution:
     """Get the ``Distribution`` instance for the named package.
 
     :param distribution_name: The name of the distribution package as a string.
@@ -972,15 +973,15 @@ def distribution(distribution_name: str) -> Distribution:
     return Distribution.from_name(distribution_name)
 
 
-def distributions(**kwargs) -> Iterable[Distribution]:
+def distributions(**kwargs) -> Iterable[Distribution | _legacy.Distribution]:
     """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) -> _meta.PackageMetadata | email.message.Message:
     """Get the metadata for the named package.
 
     :param distribution_name: The name of the distribution package to query.
@@ -1023,7 +1024,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[List[PackagePath] | List[_legacy.PackagePath]]:
     """Return a list of files for the named package.
 
     :param distribution_name: The name of the distribution package to query.