sqlspec 0.25.0__py3-none-any.whl → 0.27.0__py3-none-any.whl

sqlspec/storage/backends/obstore.py

@@ -5,18 +5,22 @@ and local file storage.
 """
 
 import fnmatch
+import io
 import logging
 from collections.abc import AsyncIterator, Iterator
-from typing import TYPE_CHECKING, Any, Final, Optional, Union, cast
+from typing import TYPE_CHECKING, Any, Final, cast
 from urllib.parse import urlparse
 
+from sqlspec.utils.sync_tools import async_
+
 if TYPE_CHECKING:
     from pathlib import Path
 
 from mypy_extensions import mypyc_attr
 
 from sqlspec.exceptions import MissingDependencyError, StorageOperationFailedError
-from sqlspec.typing import OBSTORE_INSTALLED, PYARROW_INSTALLED, ArrowRecordBatch, ArrowTable
+from sqlspec.storage._utils import ensure_pyarrow, resolve_storage_path
+from sqlspec.typing import OBSTORE_INSTALLED, ArrowRecordBatch, ArrowTable
 
 __all__ = ("ObStoreBackend",)
 
@@ -24,37 +28,64 @@ logger = logging.getLogger(__name__)
 
 
 class _AsyncArrowIterator:
-    """Helper class to work around mypyc's lack of async generator support."""
+    """Helper class to work around mypyc's lack of async generator support.
+
+    Uses hybrid async/sync pattern:
+    - Native async I/O for network operations (S3, GCS, Azure)
+    - Thread pool for CPU-bound PyArrow parsing
+    """
+
+    __slots__ = ("_current_file_iterator", "_files_iterator", "backend", "kwargs", "pattern")
 
     def __init__(self, backend: "ObStoreBackend", pattern: str, **kwargs: Any) -> None:
         self.backend = backend
         self.pattern = pattern
         self.kwargs = kwargs
-        self._files_iterator: Optional[Iterator[str]] = None
-        self._current_file_iterator: Optional[Iterator[ArrowRecordBatch]] = None
+        self._files_iterator: Iterator[str] | None = None
+        self._current_file_iterator: Iterator[ArrowRecordBatch] | None = None
 
     def __aiter__(self) -> "_AsyncArrowIterator":
         return self
 
     async def __anext__(self) -> ArrowRecordBatch:
+        import pyarrow.parquet as pq
+
         if self._files_iterator is None:
             files = self.backend.glob(self.pattern, **self.kwargs)
             self._files_iterator = iter(files)
 
         while True:
             if self._current_file_iterator is not None:
+
+                def _safe_next_batch() -> ArrowRecordBatch:
+                    try:
+                        return next(self._current_file_iterator)  # type: ignore[arg-type]
+                    except StopIteration as e:
+                        raise StopAsyncIteration from e
+
                 try:
-                    return next(self._current_file_iterator)
-                except StopIteration:
+                    return await async_(_safe_next_batch)()
+                except StopAsyncIteration:
                     self._current_file_iterator = None
+                    continue
 
             try:
                 next_file = next(self._files_iterator)
-                # Stream from this file
-                file_batches = self.backend.stream_arrow(next_file)
-                self._current_file_iterator = iter(file_batches)
-            except StopIteration:
-                raise StopAsyncIteration
+            except StopIteration as e:
+                raise StopAsyncIteration from e
+
+            data = await self.backend.read_bytes_async(next_file)
+            parquet_file = pq.ParquetFile(io.BytesIO(data))
+            self._current_file_iterator = parquet_file.iter_batches()
+
+    async def aclose(self) -> None:
+        """Close underlying file iterator."""
+        if self._current_file_iterator is not None:
+            try:
+                close_method = self._current_file_iterator.close  # type: ignore[attr-defined]
+                await async_(close_method)()  # pyright: ignore
+            except AttributeError:
+                pass
 
 
 DEFAULT_OPTIONS: Final[dict[str, Any]] = {"connect_timeout": "30s", "request_timeout": "60s"}
@@ -69,17 +100,17 @@ class ObStoreBackend:
     local filesystem, and HTTP endpoints.
     """
 
-    __slots__ = ("_path_cache", "backend_type", "base_path", "protocol", "store", "store_options", "store_uri")
-
-    def _ensure_obstore(self) -> None:
-        """Ensure obstore is available for operations."""
-        if not OBSTORE_INSTALLED:
-            raise MissingDependencyError(package="obstore", install_package="obstore")
-
-    def _ensure_pyarrow(self) -> None:
-        """Ensure PyArrow is available for Arrow operations."""
-        if not PYARROW_INSTALLED:
-            raise MissingDependencyError(package="pyarrow", install_package="pyarrow")
+    __slots__ = (
+        "_is_local_store",
+        "_local_store_root",
+        "_path_cache",
+        "backend_type",
+        "base_path",
+        "protocol",
+        "store",
+        "store_options",
+        "store_uri",
+    )
 
     def __init__(self, uri: str, **kwargs: Any) -> None:
         """Initialize obstore backend.
@@ -87,9 +118,12 @@ class ObStoreBackend:
         Args:
             uri: Storage URI (e.g., 's3://bucket', 'file:///path', 'gs://bucket')
             **kwargs: Additional options including base_path and obstore configuration
-        """
 
-        self._ensure_obstore()
+        Raises:
+            MissingDependencyError: If obstore is not installed.
+        """
+        if not OBSTORE_INSTALLED:
+            raise MissingDependencyError(package="obstore", install_package="obstore")
 
         try:
             # Extract base_path from kwargs
@@ -100,6 +134,8 @@ class ObStoreBackend:
             self.store_options = kwargs
             self.store: Any
             self._path_cache: dict[str, str] = {}
+            self._is_local_store = False
+            self._local_store_root = ""
             self.protocol = uri.split("://", 1)[0] if "://" in uri else "file"
             self.backend_type = "obstore"
 
@@ -112,11 +148,26 @@ class ObStoreBackend:
 
                 from obstore.store import LocalStore
 
+                # Parse URI to extract path
+                # Note: urlparse splits on '#', so we need to reconstruct the full path
                 parsed = urlparse(uri)
-                path = parsed.path or "/"
-                # Create directory if it doesn't exist (ObStore LocalStore requires it)
-                PathlibPath(path).mkdir(parents=True, exist_ok=True)
-                self.store = LocalStore(path)
+                path_str = parsed.path or "/"
+                # Append fragment if present (handles paths with '#' character)
+                if parsed.fragment:
+                    path_str = f"{path_str}#{parsed.fragment}"
+                path_obj = PathlibPath(path_str)
+
+                # If path points to a file, use its parent as the base directory
+                if path_obj.is_file():
+                    path_str = str(path_obj.parent)
+
+                # If base_path provided via kwargs, use it as LocalStore root
+                # Otherwise use the URI path
+                local_store_root = self.base_path or path_str
+
+                self._is_local_store = True
+                self._local_store_root = local_store_root
+                self.store = LocalStore(local_store_root, mkdir=True)
             else:
                 from obstore.store import from_url
 
@@ -141,64 +192,91 @@ class ObStoreBackend:
 
         return cls(uri=store_uri, **kwargs)
 
-    def _resolve_path(self, path: "Union[str, Path]") -> str:
-        """Resolve path relative to base_path."""
-        path_str = str(path)
-        if path_str.startswith("file://"):
-            path_str = path_str.removeprefix("file://")
-        if self.store_uri.startswith("file://") and path_str.startswith("/"):
-            return path_str.lstrip("/")
-        if self.base_path:
-            clean_base = self.base_path.rstrip("/")
-            clean_path = path_str.lstrip("/")
-            return f"{clean_base}/{clean_path}"
-        return path_str
-
-    def read_bytes(self, path: "Union[str, Path]", **kwargs: Any) -> bytes:  # pyright: ignore[reportUnusedParameter]
+    def _resolve_path_for_local_store(self, path: "str | Path") -> str:
+        """Resolve path for LocalStore which expects relative paths from its root."""
+        from pathlib import Path as PathlibPath
+
+        path_obj = PathlibPath(str(path))
+
+        # If absolute path, try to make it relative to LocalStore root
+        if path_obj.is_absolute() and self._local_store_root:
+            try:
+                return str(path_obj.relative_to(self._local_store_root))
+            except ValueError:
+                # Path is outside LocalStore root - strip leading / as fallback
+                return str(path).lstrip("/")
+
+        # Relative path - return as-is (already relative to LocalStore root)
+        return str(path)
+
+    def read_bytes(self, path: "str | Path", **kwargs: Any) -> bytes:  # pyright: ignore[reportUnusedParameter]
         """Read bytes using obstore."""
-        result = self.store.get(self._resolve_path(path))
+        # For LocalStore, use special path resolution (relative to LocalStore root)
+        if self._is_local_store:
+            resolved_path = self._resolve_path_for_local_store(path)
+        else:
+            # For cloud storage, use standard resolution
+            resolved_path = resolve_storage_path(path, self.base_path, self.protocol, strip_file_scheme=True)
+
+        result = self.store.get(resolved_path)
         return cast("bytes", result.bytes().to_bytes())
 
-    def write_bytes(self, path: "Union[str, Path]", data: bytes, **kwargs: Any) -> None:  # pyright: ignore[reportUnusedParameter]
+    def write_bytes(self, path: "str | Path", data: bytes, **kwargs: Any) -> None:  # pyright: ignore[reportUnusedParameter]
         """Write bytes using obstore."""
-        self.store.put(self._resolve_path(path), data)
+        # For LocalStore, use special path resolution (relative to LocalStore root)
+        if self._is_local_store:
+            resolved_path = self._resolve_path_for_local_store(path)
+        else:
+            resolved_path = resolve_storage_path(path, self.base_path, self.protocol, strip_file_scheme=True)
 
-    def read_text(self, path: "Union[str, Path]", encoding: str = "utf-8", **kwargs: Any) -> str:
+        self.store.put(resolved_path, data)
+
+    def read_text(self, path: "str | Path", encoding: str = "utf-8", **kwargs: Any) -> str:
         """Read text using obstore."""
         return self.read_bytes(path, **kwargs).decode(encoding)
 
-    def write_text(self, path: "Union[str, Path]", data: str, encoding: str = "utf-8", **kwargs: Any) -> None:
+    def write_text(self, path: "str | Path", data: str, encoding: str = "utf-8", **kwargs: Any) -> None:
         """Write text using obstore."""
         self.write_bytes(path, data.encode(encoding), **kwargs)
 
     def list_objects(self, prefix: str = "", recursive: bool = True, **kwargs: Any) -> list[str]:  # pyright: ignore[reportUnusedParameter]
         """List objects using obstore."""
-        resolved_prefix = self._resolve_path(prefix) if prefix else self.base_path or ""
+        resolved_prefix = (
+            resolve_storage_path(prefix, self.base_path, self.protocol, strip_file_scheme=True)
+            if prefix
+            else self.base_path or ""
+        )
         items = self.store.list_with_delimiter(resolved_prefix) if not recursive else self.store.list(resolved_prefix)
         paths: list[str] = []
         for batch in items:
             paths.extend(item["path"] for item in batch)
         return sorted(paths)
 
-    def exists(self, path: "Union[str, Path]", **kwargs: Any) -> bool:  # pyright: ignore[reportUnusedParameter]
+    def exists(self, path: "str | Path", **kwargs: Any) -> bool:  # pyright: ignore[reportUnusedParameter]
         """Check if object exists using obstore."""
         try:
-            self.store.head(self._resolve_path(path))
+            resolved_path = resolve_storage_path(path, self.base_path, self.protocol, strip_file_scheme=True)
+            self.store.head(resolved_path)
         except Exception:
             return False
         return True
 
-    def delete(self, path: "Union[str, Path]", **kwargs: Any) -> None:  # pyright: ignore[reportUnusedParameter]
+    def delete(self, path: "str | Path", **kwargs: Any) -> None:  # pyright: ignore[reportUnusedParameter]
         """Delete object using obstore."""
-        self.store.delete(self._resolve_path(path))
+        resolved_path = resolve_storage_path(path, self.base_path, self.protocol, strip_file_scheme=True)
+        self.store.delete(resolved_path)
 
-    def copy(self, source: "Union[str, Path]", destination: "Union[str, Path]", **kwargs: Any) -> None:  # pyright: ignore[reportUnusedParameter]
+    def copy(self, source: "str | Path", destination: "str | Path", **kwargs: Any) -> None:  # pyright: ignore[reportUnusedParameter]
         """Copy object using obstore."""
-        self.store.copy(self._resolve_path(source), self._resolve_path(destination))
+        source_path = resolve_storage_path(source, self.base_path, self.protocol, strip_file_scheme=True)
+        dest_path = resolve_storage_path(destination, self.base_path, self.protocol, strip_file_scheme=True)
+        self.store.copy(source_path, dest_path)
 
-    def move(self, source: "Union[str, Path]", destination: "Union[str, Path]", **kwargs: Any) -> None:  # pyright: ignore[reportUnusedParameter]
+    def move(self, source: "str | Path", destination: "str | Path", **kwargs: Any) -> None:  # pyright: ignore[reportUnusedParameter]
         """Move object using obstore."""
-        self.store.rename(self._resolve_path(source), self._resolve_path(destination))
+        source_path = resolve_storage_path(source, self.base_path, self.protocol, strip_file_scheme=True)
+        dest_path = resolve_storage_path(destination, self.base_path, self.protocol, strip_file_scheme=True)
+        self.store.rename(source_path, dest_path)
 
     def glob(self, pattern: str, **kwargs: Any) -> list[str]:
         """Find objects matching pattern.
@@ -207,7 +285,7 @@ class ObStoreBackend:
         """
         from pathlib import PurePosixPath
 
-        resolved_pattern = self._resolve_path(pattern)
+        resolved_pattern = resolve_storage_path(pattern, self.base_path, self.protocol, strip_file_scheme=True)
         all_objects = self.list_objects(recursive=True, **kwargs)
 
         if "**" in pattern:
@@ -229,38 +307,50 @@ class ObStoreBackend:
             return matching_objects
         return [obj for obj in all_objects if fnmatch.fnmatch(obj, resolved_pattern)]
 
-    def get_metadata(self, path: "Union[str, Path]", **kwargs: Any) -> dict[str, Any]:  # pyright: ignore[reportUnusedParameter]
+    def get_metadata(self, path: "str | Path", **kwargs: Any) -> dict[str, Any]:  # pyright: ignore[reportUnusedParameter]
         """Get object metadata using obstore."""
-        resolved_path = self._resolve_path(path)
-        result: dict[str, Any] = {}
+        resolved_path = resolve_storage_path(path, self.base_path, self.protocol, strip_file_scheme=True)
+
         try:
             metadata = self.store.head(resolved_path)
-            result.update(
-                {
+        except Exception:
+            return {"path": resolved_path, "exists": False}
+        else:
+            if isinstance(metadata, dict):
+                result = {
                     "path": resolved_path,
                     "exists": True,
-                    "size": getattr(metadata, "size", None),
-                    "last_modified": getattr(metadata, "last_modified", None),
-                    "e_tag": getattr(metadata, "e_tag", None),
-                    "version": getattr(metadata, "version", None),
+                    "size": metadata.get("size"),
+                    "last_modified": metadata.get("last_modified"),
+                    "e_tag": metadata.get("e_tag"),
+                    "version": metadata.get("version"),
                 }
-            )
-            if hasattr(metadata, "metadata") and metadata.metadata:
+                if metadata.get("metadata"):
+                    result["custom_metadata"] = metadata["metadata"]
+                return result
+
+            result = {
+                "path": resolved_path,
+                "exists": True,
+                "size": metadata.size,
+                "last_modified": metadata.last_modified,
+                "e_tag": metadata.e_tag,
+                "version": metadata.version,
+            }
+
+            if metadata.metadata:
                 result["custom_metadata"] = metadata.metadata
 
-        except Exception:
-            return {"path": resolved_path, "exists": False}
-        else:
             return result
 
-    def is_object(self, path: "Union[str, Path]") -> bool:
+    def is_object(self, path: "str | Path") -> bool:
         """Check if path is an object using obstore."""
-        resolved_path = self._resolve_path(path)
+        resolved_path = resolve_storage_path(path, self.base_path, self.protocol, strip_file_scheme=True)
         return self.exists(path) and not resolved_path.endswith("/")
 
-    def is_path(self, path: "Union[str, Path]") -> bool:
+    def is_path(self, path: "str | Path") -> bool:
         """Check if path is a prefix/directory using obstore."""
-        resolved_path = self._resolve_path(path)
+        resolved_path = resolve_storage_path(path, self.base_path, self.protocol, strip_file_scheme=True)
 
         if resolved_path.endswith("/"):
             return True
@@ -271,53 +361,48 @@ class ObStoreBackend:
         except Exception:
             return False
 
-    def read_arrow(self, path: "Union[str, Path]", **kwargs: Any) -> ArrowTable:
+    def read_arrow(self, path: "str | Path", **kwargs: Any) -> ArrowTable:
         """Read Arrow table using obstore."""
-        resolved_path = self._resolve_path(path)
-        if hasattr(self.store, "read_arrow"):
-            return self.store.read_arrow(resolved_path, **kwargs)  # type: ignore[no-any-return]  # pyright: ignore[reportAttributeAccessIssue]
-
-        self._ensure_pyarrow()
+        ensure_pyarrow()
         import io
 
         import pyarrow.parquet as pq
 
-        return pq.read_table(io.BytesIO(self.read_bytes(resolved_path)), **kwargs)
+        resolved_path = resolve_storage_path(path, self.base_path, self.protocol, strip_file_scheme=True)
+        data = self.read_bytes(resolved_path)
+        return pq.read_table(io.BytesIO(data), **kwargs)
 
-    def write_arrow(self, path: "Union[str, Path]", table: ArrowTable, **kwargs: Any) -> None:
+    def write_arrow(self, path: "str | Path", table: ArrowTable, **kwargs: Any) -> None:
         """Write Arrow table using obstore."""
-        resolved_path = self._resolve_path(path)
-        if hasattr(self.store, "write_arrow"):
-            self.store.write_arrow(resolved_path, table, **kwargs)  # pyright: ignore[reportAttributeAccessIssue]
-        else:
-            self._ensure_pyarrow()
-            import io
-
-            import pyarrow as pa
-            import pyarrow.parquet as pq
-
-            buffer = io.BytesIO()
-
-            schema = table.schema
-            if any(str(f.type).startswith("decimal64") for f in schema):
-                new_fields = []
-                for field in schema:
-                    if str(field.type).startswith("decimal64"):
-                        import re
-
-                        match = re.match(r"decimal64\((\d+),\s*(\d+)\)", str(field.type))
-                        if match:
-                            precision, scale = int(match.group(1)), int(match.group(2))
-                            new_fields.append(pa.field(field.name, pa.decimal128(precision, scale)))
-                        else:
-                            new_fields.append(field)  # pragma: no cover
+        ensure_pyarrow()
+        import io
+
+        import pyarrow as pa
+        import pyarrow.parquet as pq
+
+        resolved_path = resolve_storage_path(path, self.base_path, self.protocol, strip_file_scheme=True)
+
+        schema = table.schema
+        if any(str(f.type).startswith("decimal64") for f in schema):
+            new_fields = []
+            for field in schema:
+                if str(field.type).startswith("decimal64"):
+                    import re
+
+                    match = re.match(r"decimal64\((\d+),\s*(\d+)\)", str(field.type))
+                    if match:
+                        precision, scale = int(match.group(1)), int(match.group(2))
+                        new_fields.append(pa.field(field.name, pa.decimal128(precision, scale)))
                     else:
                         new_fields.append(field)
-                table = table.cast(pa.schema(new_fields))
+                else:
+                    new_fields.append(field)
+            table = table.cast(pa.schema(new_fields))
 
-            pq.write_table(table, buffer, **kwargs)
-            buffer.seek(0)
-            self.write_bytes(resolved_path, buffer.read())
+        buffer = io.BytesIO()
+        pq.write_table(table, buffer, **kwargs)
+        buffer.seek(0)
+        self.write_bytes(resolved_path, buffer.read())
 
     def stream_arrow(self, pattern: str, **kwargs: Any) -> Iterator[ArrowRecordBatch]:
         """Stream Arrow record batches.
@@ -325,13 +410,14 @@ class ObStoreBackend:
         Yields:
             Iterator of Arrow record batches from matching objects.
         """
-        self._ensure_pyarrow()
+        ensure_pyarrow()
         from io import BytesIO
 
         import pyarrow.parquet as pq
 
         for obj_path in self.glob(pattern, **kwargs):
-            result = self.store.get(self._resolve_path(obj_path))
+            resolved_path = resolve_storage_path(obj_path, self.base_path, self.protocol, strip_file_scheme=True)
+            result = self.store.get(resolved_path)
             bytes_obj = result.bytes()
             data = bytes_obj.to_bytes()
             buffer = BytesIO(data)
@@ -340,26 +426,38 @@ class ObStoreBackend:
 
     def sign(self, path: str, expires_in: int = 3600, for_upload: bool = False) -> str:
         """Generate a signed URL for the object."""
-        resolved_path = self._resolve_path(path)
-        if hasattr(self.store, "sign_url") and callable(self.store.sign_url):
-            return self.store.sign_url(resolved_path, expires_in=expires_in)  # type: ignore[no-any-return]
+        resolved_path = resolve_storage_path(path, self.base_path, self.protocol, strip_file_scheme=True)
         return f"{self.store_uri}/{resolved_path}"
 
-    async def read_bytes_async(self, path: "Union[str, Path]", **kwargs: Any) -> bytes:  # pyright: ignore[reportUnusedParameter]
+    async def read_bytes_async(self, path: "str | Path", **kwargs: Any) -> bytes:  # pyright: ignore[reportUnusedParameter]
         """Read bytes from storage asynchronously."""
-        resolved_path = self._resolve_path(path)
+        # For LocalStore (file protocol with base_path), use special resolution
+        if self._is_local_store:
+            resolved_path = self._resolve_path_for_local_store(path)
+        else:
+            resolved_path = resolve_storage_path(path, self.base_path, self.protocol, strip_file_scheme=True)
+
         result = await self.store.get_async(resolved_path)
         bytes_obj = await result.bytes_async()
         return bytes_obj.to_bytes()  # type: ignore[no-any-return]  # pyright: ignore[reportAttributeAccessIssue]
 
-    async def write_bytes_async(self, path: "Union[str, Path]", data: bytes, **kwargs: Any) -> None:  # pyright: ignore[reportUnusedParameter]
+    async def write_bytes_async(self, path: "str | Path", data: bytes, **kwargs: Any) -> None:  # pyright: ignore[reportUnusedParameter]
         """Write bytes to storage asynchronously."""
-        resolved_path = self._resolve_path(path)
+        # For LocalStore (file protocol with base_path), use special resolution
+        if self._is_local_store:
+            resolved_path = self._resolve_path_for_local_store(path)
+        else:
+            resolved_path = resolve_storage_path(path, self.base_path, self.protocol, strip_file_scheme=True)
+
         await self.store.put_async(resolved_path, data)
 
     async def list_objects_async(self, prefix: str = "", recursive: bool = True, **kwargs: Any) -> list[str]:  # pyright: ignore[reportUnusedParameter]
         """List objects in storage asynchronously."""
-        resolved_prefix = self._resolve_path(prefix) if prefix else self.base_path or ""
+        resolved_prefix = (
+            resolve_storage_path(prefix, self.base_path, self.protocol, strip_file_scheme=True)
+            if prefix
+            else self.base_path or ""
+        )
 
         objects: list[str] = []
         async for batch in self.store.list_async(resolved_prefix):  # pyright: ignore[reportAttributeAccessIssue]
@@ -371,47 +469,72 @@ class ObStoreBackend:
 
         return sorted(objects)
 
-    async def read_text_async(self, path: "Union[str, Path]", encoding: str = "utf-8", **kwargs: Any) -> str:
+    async def read_text_async(self, path: "str | Path", encoding: str = "utf-8", **kwargs: Any) -> str:
         """Read text from storage asynchronously."""
         data = await self.read_bytes_async(path, **kwargs)
         return data.decode(encoding)
 
-    async def write_text_async(
-        self, path: "Union[str, Path]", data: str, encoding: str = "utf-8", **kwargs: Any
-    ) -> None:  # pyright: ignore[reportUnusedParameter]
+    async def write_text_async(self, path: "str | Path", data: str, encoding: str = "utf-8", **kwargs: Any) -> None:  # pyright: ignore[reportUnusedParameter]
         """Write text to storage asynchronously."""
         encoded_data = data.encode(encoding)
         await self.write_bytes_async(path, encoded_data, **kwargs)
 
-    async def exists_async(self, path: "Union[str, Path]", **kwargs: Any) -> bool:  # pyright: ignore[reportUnusedParameter]
+    async def exists_async(self, path: "str | Path", **kwargs: Any) -> bool:  # pyright: ignore[reportUnusedParameter]
         """Check if object exists in storage asynchronously."""
-        resolved_path = self._resolve_path(path)
+        # For LocalStore (file protocol with base_path), use special resolution
+        if self._is_local_store:
+            resolved_path = self._resolve_path_for_local_store(path)
+        else:
+            resolved_path = resolve_storage_path(path, self.base_path, self.protocol, strip_file_scheme=True)
+
         try:
             await self.store.head_async(resolved_path)
         except Exception:
             return False
         return True
 
-    async def delete_async(self, path: "Union[str, Path]", **kwargs: Any) -> None:  # pyright: ignore[reportUnusedParameter]
+    async def delete_async(self, path: "str | Path", **kwargs: Any) -> None:  # pyright: ignore[reportUnusedParameter]
         """Delete object from storage asynchronously."""
-        resolved_path = self._resolve_path(path)
+        # For LocalStore (file protocol with base_path), use special resolution
+        if self._is_local_store:
+            resolved_path = self._resolve_path_for_local_store(path)
+        else:
+            resolved_path = resolve_storage_path(path, self.base_path, self.protocol, strip_file_scheme=True)
+
         await self.store.delete_async(resolved_path)
 
-    async def copy_async(self, source: "Union[str, Path]", destination: "Union[str, Path]", **kwargs: Any) -> None:  # pyright: ignore[reportUnusedParameter]
+    async def copy_async(self, source: "str | Path", destination: "str | Path", **kwargs: Any) -> None:  # pyright: ignore[reportUnusedParameter]
         """Copy object in storage asynchronously."""
-        source_path = self._resolve_path(source)
-        dest_path = self._resolve_path(destination)
+        # For LocalStore (file protocol with base_path), use special resolution
+        if self._is_local_store:
+            source_path = self._resolve_path_for_local_store(source)
+            dest_path = self._resolve_path_for_local_store(destination)
+        else:
+            source_path = resolve_storage_path(source, self.base_path, self.protocol, strip_file_scheme=True)
+            dest_path = resolve_storage_path(destination, self.base_path, self.protocol, strip_file_scheme=True)
+
         await self.store.copy_async(source_path, dest_path)
 
-    async def move_async(self, source: "Union[str, Path]", destination: "Union[str, Path]", **kwargs: Any) -> None:  # pyright: ignore[reportUnusedParameter]
+    async def move_async(self, source: "str | Path", destination: "str | Path", **kwargs: Any) -> None:  # pyright: ignore[reportUnusedParameter]
         """Move object in storage asynchronously."""
-        source_path = self._resolve_path(source)
-        dest_path = self._resolve_path(destination)
+        # For LocalStore (file protocol with base_path), use special resolution
+        if self._is_local_store:
+            source_path = self._resolve_path_for_local_store(source)
+            dest_path = self._resolve_path_for_local_store(destination)
+        else:
+            source_path = resolve_storage_path(source, self.base_path, self.protocol, strip_file_scheme=True)
+            dest_path = resolve_storage_path(destination, self.base_path, self.protocol, strip_file_scheme=True)
+
         await self.store.rename_async(source_path, dest_path)
 
-    async def get_metadata_async(self, path: "Union[str, Path]", **kwargs: Any) -> dict[str, Any]:  # pyright: ignore[reportUnusedParameter]
+    async def get_metadata_async(self, path: "str | Path", **kwargs: Any) -> dict[str, Any]:  # pyright: ignore[reportUnusedParameter]
         """Get object metadata from storage asynchronously."""
-        resolved_path = self._resolve_path(path)
+        # For LocalStore (file protocol with base_path), use special resolution
+        if self._is_local_store:
+            resolved_path = self._resolve_path_for_local_store(path)
+        else:
+            resolved_path = resolve_storage_path(path, self.base_path, self.protocol, strip_file_scheme=True)
+
         result: dict[str, Any] = {}
         try:
             metadata = await self.store.head_async(resolved_path)
@@ -433,42 +556,35 @@ class ObStoreBackend:
         else:
             return result
 
-    async def read_arrow_async(self, path: "Union[str, Path]", **kwargs: Any) -> ArrowTable:
+    async def read_arrow_async(self, path: "str | Path", **kwargs: Any) -> ArrowTable:
         """Read Arrow table from storage asynchronously."""
-        resolved_path = self._resolve_path(path)
-        if hasattr(self.store, "read_arrow_async"):
-            return await self.store.read_arrow_async(resolved_path, **kwargs)  # type: ignore[no-any-return]  # pyright: ignore[reportAttributeAccessIssue]
-
-        self._ensure_pyarrow()
+        ensure_pyarrow()
         import io
 
         import pyarrow.parquet as pq
 
-        return pq.read_table(io.BytesIO(await self.read_bytes_async(resolved_path)), **kwargs)
+        resolved_path = resolve_storage_path(path, self.base_path, self.protocol, strip_file_scheme=True)
+        data = await self.read_bytes_async(resolved_path)
+        return pq.read_table(io.BytesIO(data), **kwargs)
 
-    async def write_arrow_async(self, path: "Union[str, Path]", table: ArrowTable, **kwargs: Any) -> None:
+    async def write_arrow_async(self, path: "str | Path", table: ArrowTable, **kwargs: Any) -> None:
         """Write Arrow table to storage asynchronously."""
-        resolved_path = self._resolve_path(path)
-        if hasattr(self.store, "write_arrow_async"):
-            await self.store.write_arrow_async(resolved_path, table, **kwargs)  # pyright: ignore[reportAttributeAccessIssue]
-        else:
-            self._ensure_pyarrow()
-            import io
+        ensure_pyarrow()
+        import io
 
-            import pyarrow.parquet as pq
+        import pyarrow.parquet as pq
 
-            buffer = io.BytesIO()
-            pq.write_table(table, buffer, **kwargs)
-            buffer.seek(0)
-            await self.write_bytes_async(resolved_path, buffer.read())
+        resolved_path = resolve_storage_path(path, self.base_path, self.protocol, strip_file_scheme=True)
+        buffer = io.BytesIO()
+        pq.write_table(table, buffer, **kwargs)
+        buffer.seek(0)
+        await self.write_bytes_async(resolved_path, buffer.read())
 
     def stream_arrow_async(self, pattern: str, **kwargs: Any) -> AsyncIterator[ArrowRecordBatch]:
-        resolved_pattern = self._resolve_path(pattern)
+        resolved_pattern = resolve_storage_path(pattern, self.base_path, self.protocol, strip_file_scheme=True)
         return _AsyncArrowIterator(self, resolved_pattern, **kwargs)
 
     async def sign_async(self, path: str, expires_in: int = 3600, for_upload: bool = False) -> str:
         """Generate a signed URL asynchronously."""
-        resolved_path = self._resolve_path(path)
-        if hasattr(self.store, "sign_url_async") and callable(self.store.sign_url_async):
-            return await self.store.sign_url_async(resolved_path, expires_in=expires_in)  # type: ignore[no-any-return]
+        resolved_path = resolve_storage_path(path, self.base_path, self.protocol, strip_file_scheme=True)
         return f"{self.store_uri}/{resolved_path}"