Implement interfaces for Distribution and PackagePath suitable for downstream consumers.

Author: jaraco

importlib_metadata/__init__.py

@@ -29,7 +29,6 @@
 from itertools import starmap
 from typing import Any
 
-from . import _meta
 from ._collections import FreezableDefaultDict, Pair
 from ._compat import (
     NullFinder,
@@ -38,16 +37,24 @@
 )
 from ._functools import apply, compose, method_cache, noop, pass_none, passthrough
 from ._itertools import always_iterable, bucket, unique_everseen
-from ._meta import PackageMetadata, SimplePath
+from ._meta import (
+    IDistribution,
+    IPackagePath,
+    PackageMetadata,
+    SimplePath,
+)
 from ._typing import md_none
 from .compat import py39, py311
 
 __all__ = [
     'Distribution',
     'DistributionFinder',
+    'IDistribution',
     'PackageMetadata',
     'PackageNotFoundError',
     'SimplePath',
+    'PackagePath',
+    'IPackagePath',
     'distribution',
     'distributions',
     'entry_points',
@@ -208,7 +215,7 @@ class EntryPoint:
     value: str
     group: str
 
-    dist: Distribution | None = None
+    dist: IDistribution | None = None
 
     def __init__(self, name: str, value: str, group: str) -> None:
         vars(self).update(name=name, value=value, group=group)
@@ -374,7 +381,7 @@ class PackagePath(pathlib.PurePosixPath):
 
     hash: FileHash | None
     size: int
-    dist: Distribution
+    dist: IDistribution
 
     def read_text(self, encoding: str = 'utf-8') -> str:
         return self.locate().read_text(encoding=encoding)
@@ -516,7 +523,7 @@ def _discover_resolvers():
 
     @property
     @apply(pass_none(localize.message))
-    def metadata(self) -> _meta.PackageMetadata | None:
+    def metadata(self) -> PackageMetadata | None:
         """Return the parsed metadata for this Distribution.
 
         The returned object will have keys that name the various bits of
@@ -539,7 +546,7 @@ def metadata(self) -> _meta.PackageMetadata | None:
 
     @staticmethod
     @pass_none
-    def _assemble_message(text: str) -> _meta.PackageMetadata:
+    def _assemble_message(text: str) -> PackageMetadata:
         # deferred for performance (python/cpython#109829)
         from . import _adapters
 
@@ -572,10 +579,10 @@ def entry_points(self) -> EntryPoints:
 
     @property
     @apply(pass_none(compose(list, functools.partial(map, localize.package_path))))
-    def files(self) -> list[PackagePath] | None:
+    def files(self) -> list[IPackagePath] | None:
         """Files in this distribution.
 
-        :return: List of PackagePath for this distribution or None
+        :return: List of PackagePath-like objects for this distribution or None
 
         Result is `None` if the metadata file that enumerates files
         (i.e. RECORD for dist-info, or installed-files.txt or
@@ -1055,7 +1062,7 @@ def _name_from_stem(stem):
         return name
 
 
-def distribution(distribution_name: str) -> Distribution:
+def distribution(distribution_name: str) -> IDistribution:
     """Get the ``Distribution`` instance for the named package.
 
     :param distribution_name: The name of the distribution package as a string.
@@ -1064,15 +1071,15 @@ def distribution(distribution_name: str) -> Distribution:
     return Distribution.from_name(distribution_name)
 
 
-def distributions(**kwargs) -> Iterable[Distribution]:
+def distributions(**kwargs) -> Iterable[IDistribution]:
     """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 | None:
+def metadata(distribution_name: str) -> PackageMetadata | None:
     """Get the metadata for the named package.
 
     :param distribution_name: The name of the distribution package to query.
@@ -1115,7 +1122,7 @@ def entry_points(**params) -> EntryPoints:
     return EntryPoints(eps).select(**params)
 
 
-def files(distribution_name: str) -> list[PackagePath] | None:
+def files(distribution_name: str) -> list[IPackagePath] | None:
     """Return a list of files for the named package.
 
     :param distribution_name: The name of the distribution package to query.
@@ -1155,15 +1162,15 @@ def _top_level_declared(dist):
     return (dist.read_text('top_level.txt') or '').split()
 
 
-def _topmost(name: PackagePath) -> str | None:
+def _topmost(name: IPackagePath) -> str | None:
     """
     Return the top-most parent as long as there is a parent.
     """
     top, *rest = name.parts
     return top if rest else None
 
 
-def _get_toplevel_name(name: PackagePath) -> str:
+def _get_toplevel_name(name: IPackagePath) -> str:
     """
     Infer a possibly importable module name from a name presumed on
     sys.path.

importlib_metadata/_meta.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import os
-from collections.abc import Iterator
+from collections.abc import Iterable, Iterator
 from typing import (
     Any,
     Protocol,
@@ -69,3 +69,62 @@ def read_text(self, encoding=None) -> str: ...  # pragma: no cover
     def read_bytes(self) -> bytes: ...  # pragma: no cover
 
     def exists(self) -> bool: ...  # pragma: no cover
+
+
+class IPackagePath(Protocol):
+    hash: Any | None
+    size: int | None
+    dist: IDistribution
+
+    def read_text(self, encoding: str = 'utf-8') -> str: ...  # pragma: no cover
+
+    def read_binary(self) -> bytes: ...  # pragma: no cover
+
+    def locate(self) -> SimplePath: ...  # pragma: no cover
+
+    @property
+    def parts(self) -> tuple[str, ...]: ...  # pragma: no cover
+
+    def __fspath__(self) -> str: ...  # pragma: no cover
+
+
+class IDistribution(Protocol):
+    def read_text(
+        self, filename: str | os.PathLike[str]
+    ) -> str | None: ...  # pragma: no cover
+
+    def locate_file(
+        self, path: str | os.PathLike[str]
+    ) -> SimplePath: ...  # pragma: no cover
+
+    @property
+    def metadata(self) -> PackageMetadata | None: ...  # pragma: no cover
+
+    @property
+    def name(self) -> str: ...  # pragma: no cover
+
+    @property
+    def version(self) -> str: ...  # pragma: no cover
+
+    @property
+    def entry_points(self) -> Any: ...  # pragma: no cover
+
+    @property
+    def files(self) -> list[IPackagePath] | None: ...  # pragma: no cover
+
+    @property
+    def requires(self) -> list[str] | None: ...  # pragma: no cover
+
+    @property
+    def origin(self) -> Any: ...  # pragma: no cover
+
+    @classmethod
+    def discover(
+        cls, *, context: Any | None = None, **kwargs: Any
+    ) -> Iterable[IDistribution]: ...  # pragma: no cover
+
+    @classmethod
+    def from_name(cls, name: str) -> IDistribution: ...  # pragma: no cover
+
+    @staticmethod
+    def at(path: str | os.PathLike[str]) -> IDistribution: ...  # pragma: no cover

newsfragments/486.feature.rst

@@ -0,0 +1 @@
+Added ``IDistribution`` and ``IPackagePath`` protocols so consumers can target a stable, shared interface across ``importlib.metadata`` and ``importlib_metadata``.