Add UnsupportedOperation exception (#474)

* upath: provide UnsupportedOperation exception class

* tests: add backport tests

* upath: more typing and signature fixes

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

Author: ap--

upath/__init__.py

@@ -10,9 +10,10 @@
     __version__ = "not-installed"
 
 if TYPE_CHECKING:
+    from upath.core import UnsupportedOperation
     from upath.core import UPath
 
-__all__ = ["UPath"]
+__all__ = ["UPath", "UnsupportedOperation"]
 
 
 def __getattr__(name):
@@ -21,5 +22,10 @@ def __getattr__(name):
 
         globals()["UPath"] = UPath
         return UPath
+    elif name == "UnsupportedOperation":
+        from upath.core import UnsupportedOperation
+
+        globals()["UnsupportedOperation"] = UnsupportedOperation
+        return UnsupportedOperation
     else:
         raise AttributeError(f"module {__name__} has no attribute {name}")

upath/core.py

@@ -49,6 +49,12 @@
 from upath.types import WritablePath
 from upath.types import WritablePathLike
 
+if sys.version_info >= (3, 13):
+    from pathlib import UnsupportedOperation
+else:
+    UnsupportedOperation = NotImplementedError
+    """Raised when an unsupported operation is called on a path object."""
+
 if TYPE_CHECKING:
     import upath.implementations as _uimpl
 
@@ -63,7 +69,10 @@
     _MT = TypeVar("_MT")
     _WT = TypeVar("_WT", bound="WritablePath")
 
-__all__ = ["UPath"]
+__all__ = [
+    "UPath",
+    "UnsupportedOperation",
+]
 
 _FSSPEC_HAS_WORKING_GLOB = None
 
@@ -103,7 +112,7 @@ def _buffering2blocksize(mode: str, buffering: int) -> int | None:
 
 
 def _raise_unsupported(cls_name: str, method: str) -> NoReturn:
-    raise NotImplementedError(f"{cls_name}.{method}() is unsupported")
+    raise UnsupportedOperation(f"{cls_name}.{method}() is unsupported")
 
 
 class _UPathMeta(ABCMeta):
@@ -311,7 +320,7 @@ def path(self) -> str:
                 # For relative paths, we need to resolve to absolute path
                 current_dir = self.cwd()  # type: ignore[attr-defined]
             except NotImplementedError:
-                raise NotImplementedError(
+                raise UnsupportedOperation(
                     f"fsspec paths can not be relative and"
                     f" {type(self).__name__}.cwd() is unsupported"
                 ) from None
@@ -1513,20 +1522,20 @@ def glob(
         self,
         pattern: str,
         *,
-        case_sensitive: bool = UNSET_DEFAULT,
-        recurse_symlinks: bool = UNSET_DEFAULT,
+        case_sensitive: bool | None = None,
+        recurse_symlinks: bool = False,
     ) -> Iterator[Self]:
         """Iterate over this subtree and yield all existing files (of any
         kind, including directories) matching the given relative pattern."""
-        if case_sensitive is not UNSET_DEFAULT:
+        if case_sensitive is not None:
             warnings.warn(
                 "UPath.glob(): case_sensitive is currently ignored.",
                 UserWarning,
                 stacklevel=2,
             )
-        if recurse_symlinks is not UNSET_DEFAULT:
+        if recurse_symlinks:
             warnings.warn(
-                "UPath.glob(): recurse_symlinks is currently ignored.",
+                "UPath.glob(): recurse_symlinks=True is currently ignored.",
                 UserWarning,
                 stacklevel=2,
             )
@@ -1543,22 +1552,22 @@ def rglob(
         self,
         pattern: str,
         *,
-        case_sensitive: bool = UNSET_DEFAULT,
-        recurse_symlinks: bool = UNSET_DEFAULT,
+        case_sensitive: bool | None = None,
+        recurse_symlinks: bool = False,
     ) -> Iterator[Self]:
         """Recursively yield all existing files (of any kind, including
         directories) matching the given relative pattern, anywhere in
         this subtree.
         """
-        if case_sensitive is not UNSET_DEFAULT:
+        if case_sensitive is not None:
             warnings.warn(
                 "UPath.glob(): case_sensitive is currently ignored.",
                 UserWarning,
                 stacklevel=2,
             )
-        if recurse_symlinks is not UNSET_DEFAULT:
+        if recurse_symlinks:
             warnings.warn(
-                "UPath.glob(): recurse_symlinks is currently ignored.",
+                "UPath.glob(): recurse_symlinks=True is currently ignored.",
                 UserWarning,
                 stacklevel=2,
             )
@@ -1971,13 +1980,39 @@ def is_relative_to(
         return self == other or other in self.parents
 
     def hardlink_to(self, target: ReadablePathLike) -> None:
-        raise NotImplementedError
+        _raise_unsupported(type(self).__name__, "hardlink_to")
+
+    def full_match(
+        self,
+        pattern: str | SupportsPathLike,
+        *,
+        case_sensitive: bool | None = None,
+    ) -> bool:
+        """Match this path against the provided glob-style pattern.
+        Return True if matching is successful, False otherwise.
+        """
+        if case_sensitive is not None:
+            warnings.warn(
+                f"{type(self).__name__}.full_match(): case_sensitive"
+                " is currently ignored.",
+                UserWarning,
+                stacklevel=2,
+            )
+        return super().full_match(str(pattern))
 
-    def match(self, pattern: str) -> bool:
-        # fixme: hacky emulation of match. needs tests...
-        if not pattern:
+    def match(
+        self,
+        path_pattern: str | SupportsPathLike,
+        *,
+        case_sensitive: bool | None = None,
+    ) -> bool:
+        """Match this path against the provided non-recursive glob-style pattern.
+        Return True if matching is successful, False otherwise.
+        """
+        path_pattern = str(path_pattern)
+        if not path_pattern:
             raise ValueError("pattern cannot be empty")
-        return self.full_match(pattern.replace("**", "*"))
+        return self.full_match(path_pattern.replace("**", "*"))
 
     @classmethod
     def __get_pydantic_core_schema__(

upath/extensions.py

@@ -19,12 +19,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 SupportsPathLike
 from upath.types import UPathParser
 from upath.types import WritablePathLike
 
@@ -249,8 +251,8 @@ def glob(
         self,
         pattern: str,
         *,
-        case_sensitive: bool = UNSET_DEFAULT,
-        recurse_symlinks: bool = UNSET_DEFAULT,
+        case_sensitive: bool | None = None,
+        recurse_symlinks: bool = False,
     ) -> Iterator[Self]:
         for p in self.__wrapped__.glob(
             pattern, case_sensitive=case_sensitive, recurse_symlinks=recurse_symlinks
@@ -261,8 +263,8 @@ def rglob(
         self,
         pattern: str,
         *,
-        case_sensitive: bool = UNSET_DEFAULT,
-        recurse_symlinks: bool = UNSET_DEFAULT,
+        case_sensitive: bool | None = None,
+        recurse_symlinks: bool = False,
     ) -> Iterator[Self]:
         for p in self.__wrapped__.rglob(
             pattern, case_sensitive=case_sensitive, recurse_symlinks=recurse_symlinks
@@ -357,11 +359,11 @@ def samefile(self, other_path) -> bool:
 
     @classmethod
     def cwd(cls) -> Self:
-        raise NotImplementedError
+        raise UnsupportedOperation(".cwd() not supported")
 
     @classmethod
     def home(cls) -> Self:
-        raise NotImplementedError
+        raise UnsupportedOperation(".home() not supported")
 
     def relative_to(  # type: ignore[override]
         self,
@@ -382,7 +384,7 @@ def is_relative_to(self, other, /, *_deprecated) -> bool:  # type: ignore[overri
     def hardlink_to(self, target: ReadablePathLike) -> None:
         return self.__wrapped__.hardlink_to(target)
 
-    def match(self, pattern: str) -> bool:
+    def match(self, pattern: str, *, case_sensitive: bool | None = None) -> bool:
         return self.__wrapped__.match(pattern)
 
     @property
@@ -510,8 +512,13 @@ def parent(self) -> Self:
     def parents(self) -> Sequence[Self]:
         return tuple(self._from_upath(p) for p in self.__wrapped__.parents)
 
-    def full_match(self, pattern: str) -> bool:
-        return self.__wrapped__.full_match(pattern)
+    def full_match(
+        self,
+        pattern: str | SupportsPathLike,
+        *,
+        case_sensitive: bool | None = None,
+    ) -> bool:
+        return self.__wrapped__.full_match(pattern, case_sensitive=case_sensitive)
 
 
 UPath.register(ProxyUPath)

upath/implementations/data.py

@@ -4,6 +4,7 @@
 from collections.abc import Sequence
 from typing import TYPE_CHECKING
 
+from upath.core import UnsupportedOperation
 from upath.core import UPath
 from upath.types import JoinablePathLike
 
@@ -44,24 +45,24 @@ def __str__(self) -> str:
         return self.parser.join(*self._raw_urlpaths)
 
     def with_segments(self, *pathsegments: JoinablePathLike) -> Self:
-        raise NotImplementedError("path operation not supported by DataPath")
+        raise UnsupportedOperation("path operation not supported by DataPath")
 
     def with_suffix(self, suffix: str) -> Self:
-        raise NotImplementedError("path operation not supported by DataPath")
+        raise UnsupportedOperation("path operation not supported by DataPath")
 
     def mkdir(
         self, mode: int = 0o777, parents: bool = False, exist_ok: bool = False
     ) -> None:
         raise FileExistsError(str(self))
 
     def write_bytes(self, data: bytes) -> int:
-        raise NotImplementedError("DataPath does not support writing")
+        raise UnsupportedOperation("DataPath does not support writing")
 
     def write_text(
         self,
         data: str,
-        encoding: str | None = ...,
-        errors: str | None = ...,
-        newline: str | None = ...,
+        encoding: str | None = None,
+        errors: str | None = None,
+        newline: str | None = None,
     ) -> int:
-        raise NotImplementedError("DataPath does not support writing")
+        raise UnsupportedOperation("DataPath does not support writing")

upath/implementations/http.py

@@ -64,7 +64,14 @@ def path(self) -> str:
         sr = urlsplit(super().path)
         return sr._replace(path=sr.path or "/").geturl()
 
-    def is_file(self) -> bool:
+    def is_file(self, *, follow_symlinks: bool = True) -> bool:
+        if not follow_symlinks:
+            warnings.warn(
+                f"{type(self).__name__}.is_file(follow_symlinks=False):"
+                " is currently ignored.",
+                UserWarning,
+                stacklevel=2,
+            )
         try:
             next(super().iterdir())
         except (StopIteration, NotADirectoryError):
@@ -74,7 +81,14 @@ def is_file(self) -> bool:
         else:
             return False
 
-    def is_dir(self) -> bool:
+    def is_dir(self, *, follow_symlinks: bool = True) -> bool:
+        if not follow_symlinks:
+            warnings.warn(
+                f"{type(self).__name__}.is_dir(follow_symlinks=False):"
+                " is currently ignored.",
+                UserWarning,
+                stacklevel=2,
+            )
         try:
             next(super().iterdir())
         except (StopIteration, NotADirectoryError):

upath/implementations/local.py

@@ -20,6 +20,7 @@
 from upath._chain import ChainSegment
 from upath._chain import FSSpecChainParser
 from upath._protocol import compatible_protocol
+from upath.core import UnsupportedOperation
 from upath.core import UPath
 from upath.core import _UPathMixin
 from upath.types import UNSET_DEFAULT
@@ -393,10 +394,17 @@ def info(self) -> PathInfo:
 
     if sys.version_info < (3, 13):
 
-        def full_match(self, pattern: str) -> bool:
+        def full_match(
+            self,
+            pattern: str | os.PathLike[str],
+            *,
+            case_sensitive: bool | None = None,
+        ) -> bool:
             # hacky workaround for missing pathlib.Path.full_match in python < 3.13
             # todo: revisit
-            return self.match(pattern)
+            return self.match(
+                pattern,  # type: ignore[arg-type]
+            )
 
         @classmethod
         def from_uri(cls, uri: str, **storage_options: Any) -> Self:
@@ -422,7 +430,7 @@ def hardlink_to(self, target: ReadablePathLike) -> None:
             try:
                 os.link(target, self)  # type: ignore[arg-type]
             except AttributeError:
-                raise NotImplementedError
+                raise UnsupportedOperation("hardlink operation not supported")
 
     if not hasattr(pathlib.Path, "_copy_from"):
 
@@ -464,7 +472,7 @@ def __new__(
                 chain_parser: FSSpecChainParser = DEFAULT_CHAIN_PARSER,
                 **storage_options: Any,
             ) -> WindowsUPath:
-                raise NotImplementedError(
+                raise UnsupportedOperation(
                     f"cannot instantiate {cls.__name__} on your system"
                 )
 
@@ -480,7 +488,7 @@ def __new__(
                 chain_parser: FSSpecChainParser = DEFAULT_CHAIN_PARSER,
                 **storage_options: Any,
             ) -> PosixUPath:
-                raise NotImplementedError(
+                raise UnsupportedOperation(
                     f"cannot instantiate {cls.__name__} on your system"
                 )
 

upath/tests/test_pathlib_backport.py

@@ -0,0 +1,31 @@
+import os
+from pathlib import PosixPath
+from pathlib import WindowsPath
+
+import pytest
+
+from upath import UnsupportedOperation
+from upath.implementations.local import PosixUPath
+from upath.implementations.local import WindowsUPath
+
+
+def test_provides_unsupportedoperation():
+    assert issubclass(UnsupportedOperation, NotImplementedError)
+
+
+_win_only = pytest.mark.skipif(os.name != "nt", reason="windows only")
+_posix_only = pytest.mark.skipif(os.name == "nt", reason="posix only")
+
+
+@pytest.mark.parametrize(
+    "wrong_cls",
+    [
+        pytest.param(PosixPath, marks=_win_only),
+        pytest.param(PosixUPath, marks=_win_only),
+        pytest.param(WindowsPath, marks=_posix_only),
+        pytest.param(WindowsUPath, marks=_posix_only),
+    ],
+)
+def test_unsupportedoperation_catches_pathlib_errors(wrong_cls):
+    with pytest.raises(UnsupportedOperation):
+        wrong_cls(".")