Move code specific to backport to compat module

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,
@@ -30,16 +30,10 @@
 
 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
 
-if sys.version_info >= (3, 10):
-    from importlib.metadata import PackageMetadata as _legacy_Metadata
-else:
-    from email.message import Message as _legacy_Metadata
-
 
 __all__ = [
     'Distribution',
@@ -382,7 +376,7 @@ def locate_file(self, path: str | os.PathLike[str]) -> SimplePath:
         """
 
     @classmethod
-    def from_name(cls, name: str) -> Distribution | _legacy.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.
@@ -402,7 +396,7 @@ def from_name(cls, name: str) -> Distribution | _legacy.Distribution:
     @classmethod
     def discover(
         cls, *, context: Optional[DistributionFinder.Context] = None, **kwargs
-    ) -> Iterable[Distribution | _legacy.Distribution]:
+    ) -> Iterable[stdlib._DistributionOrLegacy]:
         """Return an iterable of Distribution objects for all packages.
 
         Pass a ``context`` or pass keyword arguments for constructing
@@ -948,7 +942,7 @@ def _name_from_stem(stem):
         return name
 
 
-def distribution(distribution_name: str) -> Distribution | _legacy.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.
@@ -957,15 +951,15 @@ def distribution(distribution_name: str) -> Distribution | _legacy.Distribution:
     return Distribution.from_name(distribution_name)
 
 
-def distributions(**kwargs) -> Iterable[Distribution | _legacy.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 | _legacy_Metadata:
+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.
@@ -1010,7 +1004,7 @@ def entry_points(**params) -> EntryPoints:
 
 def files(
     distribution_name: str,
-) -> Optional[List[PackagePath] | List[_legacy.PackagePath]]:
+) -> 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]
+    ]