Merge pull request #480 from python/bugfix/distribution-simplepath

Correct the interface for SimplePath

Author: jaraco

docs/api.rst

@@ -9,3 +9,8 @@ API Reference
    :members:
    :undoc-members:
    :show-inheritance:
+
+.. automodule:: importlib_metadata._meta
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/conf.py

@@ -71,4 +71,6 @@
     ('py:class', '_T'),
     # Other workarounds
     ('py:class', 'importlib_metadata.DeprecatedNonAbstract'),
+    # Workaround needed for #480
+    ('py:obj', 'importlib_metadata._meta._T'),
 ]

importlib_metadata/__init__.py

@@ -320,7 +320,7 @@ def read_text(self, encoding: str = 'utf-8') -> str:  # type: ignore[override]
     def read_binary(self) -> bytes:
         return self.locate().read_bytes()
 
-    def locate(self) -> pathlib.Path:
+    def locate(self) -> SimplePath:
         """Return a path-like object for this path"""
         return self.dist.locate_file(self)
 
@@ -387,9 +387,9 @@ def read_text(self, filename) -> Optional[str]:
         """
 
     @abc.abstractmethod
-    def locate_file(self, path: StrPath) -> pathlib.Path:
+    def locate_file(self, path: StrPath) -> SimplePath:
         """
-        Given a path to a file in this distribution, return a path
+        Given a path to a file in this distribution, return a SimplePath
         to it.
         """
 
@@ -854,7 +854,7 @@ def read_text(self, filename: StrPath) -> Optional[str]:
 
     read_text.__doc__ = Distribution.read_text.__doc__
 
-    def locate_file(self, path: StrPath) -> pathlib.Path:
+    def locate_file(self, path: StrPath) -> SimplePath:
         return self._path.parent / path
 
     @property

importlib_metadata/_meta.py

@@ -46,7 +46,7 @@ def json(self) -> Dict[str, Union[str, List[str]]]:
 
 class SimplePath(Protocol[_T]):
     """
-    A minimal subset of pathlib.Path required by PathDistribution.
+    A minimal subset of pathlib.Path required by Distribution.
     """
 
     def joinpath(self, other: Union[str, _T]) -> _T:
@@ -59,5 +59,11 @@ def __truediv__(self, other: Union[str, _T]) -> _T:
     def parent(self) -> _T:
         ...  # pragma: no cover
 
-    def read_text(self) -> str:
+    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

newsfragments/+b15724f6.bugfix.rst

@@ -0,0 +1 @@
+Corrected the interface for SimplePath to encompass the expectations of locate_file and PackagePath.