importlib.metadata: Improve and test SimplePath protocol (#11436)

Co-authored-by: layday <layday@protonmail.com>

stdlib/importlib/metadata/_meta.pyi

@@ -3,6 +3,7 @@ from collections.abc import Iterator
 from typing import Any, Protocol, TypeVar, overload
 
 _T = TypeVar("_T")
+_T_co = TypeVar("_T_co", covariant=True)
 
 class PackageMetadata(Protocol):
     def __len__(self) -> int: ...
@@ -22,19 +23,27 @@ class PackageMetadata(Protocol):
         def get(self, name: str, failobj: _T) -> _T | str: ...
 
 if sys.version_info >= (3, 12):
-    class SimplePath(Protocol[_T]):
-        def joinpath(self) -> _T: ...
+    class SimplePath(Protocol[_T_co]):
+        # At runtime this is defined as taking `str | _T`, but that causes trouble.
+        # See #11436.
+        def joinpath(self, other: str, /) -> _T_co: ...
         @property
-        def parent(self) -> _T: ...
+        def parent(self) -> _T_co: ...
         def read_text(self) -> str: ...
-        def __truediv__(self, other: _T | str) -> _T: ...
+        # As with joinpath(), this is annotated as taking `str | _T` at runtime.
+        def __truediv__(self, other: str, /) -> _T_co: ...
 
 else:
     class SimplePath(Protocol):
-        def joinpath(self) -> SimplePath: ...
-        def parent(self) -> SimplePath: ...
+        # Actually takes only self at runtime, but that's clearly wrong
+        def joinpath(self, other: Any, /) -> SimplePath: ...
+        # Not defined as a property at runtime, but it should be
+        @property
+        def parent(self) -> Any: ...
         def read_text(self) -> str: ...
         # There was a bug in `SimplePath` definition in cpython, see #8451
         #  Strictly speaking `__div__` was defined in 3.10, not __truediv__,
         # but it should have always been `__truediv__`.
-        def __truediv__(self) -> SimplePath: ...
+        # Also, the runtime defines this method as taking no arguments,
+        # which is obviously wrong.
+        def __truediv__(self, other: Any, /) -> SimplePath: ...

test_cases/stdlib/check_importlib_metadata.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import sys
+from _typeshed import StrPath
+from os import PathLike
+from pathlib import Path
+from typing import Any
+from zipfile import Path as ZipPath
+
+if sys.version_info >= (3, 10):
+    from importlib.metadata._meta import SimplePath
+
+    # Simplified version of zipfile.Path
+    class MyPath:
+        @property
+        def parent(self) -> PathLike[str]: ...  # undocumented
+
+        def read_text(self, encoding: str | None = ..., errors: str | None = ...) -> str: ...
+        def joinpath(self, *other: StrPath) -> MyPath: ...
+        def __truediv__(self, add: StrPath) -> MyPath: ...
+
+    if sys.version_info >= (3, 12):
+
+        def takes_simple_path(p: SimplePath[Any]) -> None: ...
+
+    else:
+
+        def takes_simple_path(p: SimplePath) -> None: ...
+
+    takes_simple_path(Path())
+    takes_simple_path(ZipPath(""))
+    takes_simple_path(MyPath())
+    takes_simple_path("some string")  # type: ignore

tests/regr_test.py

@@ -180,6 +180,8 @@ def run_testcases(
         # Avoid race conditions when reading the cache
         # (https://github.com/python/typeshed/issues/11220)
         "--no-incremental",
+        # Not useful for the test cases
+        "--disable-error-code=empty-body",
     ]
 
     if package.is_stdlib:

tests/stubtest_allowlists/py310.txt

@@ -13,7 +13,6 @@ gettext.install
 gettext.translation
 importlib._abc.Loader.exec_module  # See Lib/importlib/_abc.py. Might be defined for backwards compatibility
 importlib.abc.Finder.find_module
-importlib.metadata._meta.SimplePath.__truediv__  # See comments in the stub
 # platform.uname_result's processor field is now dynamically made to exist
 platform.uname_result.__match_args__
 platform.uname_result.__new__
@@ -26,6 +25,10 @@ typing._SpecialForm.__mro_entries__
 weakref.ProxyType.__reversed__  # Doesn't really exist
 builtins.ellipsis  # type is not exposed anywhere
 
+# Runtime definition of protocol is incorrect
+importlib.metadata._meta.SimplePath.__truediv__
+importlib.metadata._meta.SimplePath.joinpath
+
 # Modules that exist at runtime, but shouldn't be added to typeshed
 ctypes.test
 ctypes\.test\..+

tests/stubtest_allowlists/py311.txt

@@ -18,6 +18,10 @@ tkinter._VersionInfoType.__doc__
 typing.NewType.__mro_entries__
 builtins.ellipsis  # type is not exposed anywhere
 
+# Runtime definition of protocol is incorrect
+importlib.metadata._meta.SimplePath.__truediv__
+importlib.metadata._meta.SimplePath.joinpath
+
 # Modules that exist at runtime, but shouldn't be added to typeshed
 ctypes.test
 ctypes\.test\..+

tests/stubtest_allowlists/py312.txt

@@ -75,6 +75,7 @@ types.GenericAlias.__getattr__
 types.GenericAlias.__mro_entries__
 sys._monitoring  # Doesn't really exist. See comments in the stub.
 weakref.ProxyType.__reversed__  # Doesn't really exist
+importlib.metadata._meta.SimplePath.joinpath  # Incorrect runtime definition
 
 # sys attributes that are not always defined
 sys.last_exc