Merge pull request #315 from FFY00/pathdistribution-type-hint

meta: add SimplePath protocol for PathDistribution

CHANGES.rst

@@ -3,6 +3,9 @@ v4.1.0
 
 * #312: Add support for metadata 2.2 (``Dynamic`` field).
 
+* #315: Add ``SimplePath`` protocol for interface clarity
+  in ``PathDistribution``.
+
 v4.0.1
 =======
 

importlib_metadata/__init__.py

@@ -23,7 +23,7 @@
 )
 from ._functools import method_cache
 from ._itertools import unique_everseen
-from ._meta import PackageMetadata
+from ._meta import PackageMetadata, SimplePath
 
 from contextlib import suppress
 from importlib import import_module
@@ -783,11 +783,10 @@ def invalidate_caches(cls):
 
 
 class PathDistribution(Distribution):
-    def __init__(self, path):
-        """Construct a distribution from a path to the metadata directory.
+    def __init__(self, path: SimplePath):
+        """Construct a distribution.
 
-        :param path: A pathlib.Path or similar object supporting
-                     .joinpath(), __div__, .parent, and .read_text().
+        :param path: SimplePath indicating the metadata directory.
         """
         self._path = path
 

importlib_metadata/_meta.py

@@ -28,3 +28,21 @@ def json(self) -> Dict[str, Union[str, List[str]]]:
         """
         A JSON-compatible form of the metadata.
         """
+
+
+class SimplePath(Protocol):
+    """
+    A minimal subset of pathlib.Path required by PathDistribution.
+    """
+
+    def joinpath(self) -> 'SimplePath':
+        ...  # pragma: no cover
+
+    def __div__(self) -> 'SimplePath':
+        ...  # pragma: no cover
+
+    def parent(self) -> 'SimplePath':
+        ...  # pragma: no cover
+
+    def read_text(self) -> str:
+        ...  # pragma: no cover