Pathlib backport signatures and adjust stat_result return type (#476)

* Revert "upath.implementatios.local: fix type error on <3.12"

This reverts commit d68e7ac.

* upath: stat() follow_symlinks and fix return type

* tests: add backport tests

* tests: adjust assumptions

* tests: correct backport tests

* upath: implement backport changes

* upath: switch to StatResultType as return type

* upath: more typing and signature fixes

* fix lint

* tests: fix backport tests for windows

* upath.implementations.local: fix that st_birthtime depends on os an may be missing

Author: ap--

typesafety/test_upath_interface.yml

@@ -273,7 +273,7 @@
   main: |
     from upath import UPath
 
-    reveal_type(UPath("abc").stat())  # N: Revealed type is "upath._stat.UPathStatResult"
+    reveal_type(UPath("abc").stat())  # N: Revealed type is "upath.types.StatResultType"
 
 - case: upath_chmod
   disable_cache: false
@@ -378,7 +378,7 @@
   main: |
     from upath import UPath
 
-    reveal_type(UPath("abc").lstat())  # N: Revealed type is "upath._stat.UPathStatResult"
+    reveal_type(UPath("abc").lstat())  # N: Revealed type is "upath.types.StatResultType"
 
 - case: upath_mkdir
   disable_cache: false

typesafety/test_upath_signatures.yml

@@ -615,7 +615,7 @@
     import os
 
     p = UPath("")
-    reveal_type(p.stat())  # N: Revealed type is "upath._stat.UPathStatResult"
+    reveal_type(p.stat())  # N: Revealed type is "upath.types.StatResultType"
 
 - case: upath_method_lstat
   disable_cache: false
@@ -624,7 +624,7 @@
     import os
 
     p = UPath("")
-    reveal_type(p.lstat())  # N: Revealed type is "upath._stat.UPathStatResult"
+    reveal_type(p.lstat())  # N: Revealed type is "upath.types.StatResultType"
 
 - case: upath_method_chmod
   disable_cache: false
@@ -1086,8 +1086,8 @@
     reveal_type(p.group())  # N: Revealed type is "builtins.str"
 
     # Stat methods
-    reveal_type(p.stat())  # NR: Revealed type is ".*(UPathStatResult|stat_result).*"
-    reveal_type(p.lstat())  # NR: Revealed type is ".*(UPathStatResult|stat_result).*"
+    reveal_type(p.stat())  # NR: Revealed type is ".*(StatResultType|stat_result).*"
+    reveal_type(p.lstat())  # NR: Revealed type is ".*(StatResultType|stat_result).*"
 
     # None methods
     reveal_type(p.symlink_to("target"))  # N: Revealed type is "None"

upath/core.py

@@ -44,6 +44,7 @@
 from upath.types import PathInfo
 from upath.types import ReadablePath
 from upath.types import ReadablePathLike
+from upath.types import StatResultType
 from upath.types import SupportsPathLike
 from upath.types import UPathParser
 from upath.types import WritablePath
@@ -1375,7 +1376,7 @@ def stat(
         self,
         *,
         follow_symlinks: bool = True,
-    ) -> UPathStatResult:
+    ) -> StatResultType:
         """
         Return the result of the stat() system call on this path, like
         os.stat() does.
@@ -1399,7 +1400,7 @@ def stat(
             )
         return UPathStatResult.from_info(self.fs.info(self.path))
 
-    def lstat(self) -> UPathStatResult:
+    def lstat(self) -> StatResultType:
         return self.stat(follow_symlinks=False)
 
     def chmod(self, mode: int, *, follow_symlinks: bool = True) -> None:
@@ -1413,18 +1414,39 @@ def exists(self, *, follow_symlinks: bool = True) -> bool:
         ----
         For fsspec filesystems follow_symlinks is currently ignored.
         """
+        if not follow_symlinks:
+            warnings.warn(
+                f"{type(self).__name__}.exists() follow_symlinks=False"
+                " is currently ignored.",
+                UserWarning,
+                stacklevel=2,
+            )
         return self.fs.exists(self.path)
 
-    def is_dir(self) -> bool:
+    def is_dir(self, *, follow_symlinks: bool = True) -> bool:
         """
         Whether this path is a directory.
         """
+        if not follow_symlinks:
+            warnings.warn(
+                f"{type(self).__name__}.is_dir() follow_symlinks=False"
+                " is currently ignored.",
+                UserWarning,
+                stacklevel=2,
+            )
         return self.fs.isdir(self.path)
 
-    def is_file(self) -> bool:
+    def is_file(self, *, follow_symlinks: bool = True) -> bool:
         """
         Whether this path is a regular file.
         """
+        if not follow_symlinks:
+            warnings.warn(
+                f"{type(self).__name__}.is_file() follow_symlinks=False"
+                " is currently ignored.",
+                UserWarning,
+                stacklevel=2,
+            )
         return self.fs.isfile(self.path)
 
     def is_mount(self) -> bool:
@@ -1597,10 +1619,10 @@ def rglob(
                         seen.add(name)
                         yield self.joinpath(name)
 
-    def owner(self) -> str:
+    def owner(self, *, follow_symlinks: bool = True) -> str:
         _raise_unsupported(type(self).__name__, "owner")
 
-    def group(self) -> str:
+    def group(self, *, follow_symlinks: bool = True) -> str:
         _raise_unsupported(type(self).__name__, "group")
 
     def absolute(self) -> Self:
@@ -2012,6 +2034,12 @@ def match(
         path_pattern = str(path_pattern)
         if not path_pattern:
             raise ValueError("pattern cannot be empty")
+        if case_sensitive is not None:
+            warnings.warn(
+                f"{type(self).__name__}.match(): case_sensitive is currently ignored.",
+                UserWarning,
+                stacklevel=2,
+            )
         return self.full_match(path_pattern.replace("**", "*"))
 
     @classmethod

upath/extensions.py

@@ -18,14 +18,14 @@
 
 from upath._chain import Chain
 from upath._chain import ChainSegment
-from upath._stat import UPathStatResult
 from upath.core import UnsupportedOperation
 from upath.core import UPath
 from upath.types import UNSET_DEFAULT
 from upath.types import JoinablePathLike
 from upath.types import PathInfo
 from upath.types import ReadablePath
 from upath.types import ReadablePathLike
+from upath.types import StatResultType
 from upath.types import SupportsPathLike
 from upath.types import UPathParser
 from upath.types import WritablePathLike
@@ -202,10 +202,10 @@ def stat(
         self,
         *,
         follow_symlinks=True,
-    ) -> UPathStatResult:
+    ) -> StatResultType:
         return self.__wrapped__.stat(follow_symlinks=follow_symlinks)
 
-    def lstat(self) -> UPathStatResult:
+    def lstat(self) -> StatResultType:
         return self.__wrapped__.stat(follow_symlinks=False)
 
     def chmod(self, mode: int, *, follow_symlinks: bool = True) -> None:

upath/implementations/http.py

@@ -13,6 +13,7 @@
 from upath._stat import UPathStatResult
 from upath.core import UPath
 from upath.types import JoinablePathLike
+from upath.types import StatResultType
 
 if TYPE_CHECKING:
     from typing import Literal
@@ -98,7 +99,7 @@ def is_dir(self, *, follow_symlinks: bool = True) -> bool:
         else:
             return True
 
-    def stat(self, follow_symlinks: bool = True) -> UPathStatResult:
+    def stat(self, follow_symlinks: bool = True) -> StatResultType:
         if not follow_symlinks:
             warnings.warn(
                 f"{type(self).__name__}.stat(follow_symlinks=False):"