diff --git a/docs/conf.py b/docs/conf.py index 2cd8fb0c..a353eccf 100644 --- a/docs/conf.py +++ b/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'), ] diff --git a/importlib_metadata/__init__.py b/importlib_metadata/__init__.py index ed481355..9c2a7bf9 100644 --- a/importlib_metadata/__init__.py +++ b/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,7 +951,7 @@ 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. @@ -958,7 +959,7 @@ def distributions(**kwargs) -> Iterable[Distribution]: 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. diff --git a/importlib_metadata/compat/stdlib.py b/importlib_metadata/compat/stdlib.py new file mode 100644 index 00000000..2db335de --- /dev/null +++ b/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] + ]