xtr-storage 3.0.0__py3-none-any.whl

xtr_storage/.agents/skills/xtr-storage/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: xtr-storage
+description: How to read, write, list, copy and move files with xtr-storage behind one async interface, on local disk, in memory, in Amazon S3, in Google Cloud Storage or on any fsspec backend. Use when code stores uploads, reports, exports or other files, must work against a disk in development and a bucket in production, needs public or signed urls, file visibility, checksums, streaming of large files, several named storages or a read-only or path-prefixed view; also when adding StorageBundle and named storages to an application on xtr-dependency-injection, or testing code that writes files.
+---
+
+# xtr-storage
+
+Where the bytes live is a constructor argument. A `Storage` wraps one adapter and turns paths into
+reads, writes, listings, copies and moves; swapping the adapter moves the files without touching
+the code that stores them. Every call that reaches the backend is awaited.
+
+## Quick reference
+
+- Depend on `StorageOperatorInterface` (or `StorageReaderInterface` / `StorageWriterInterface`),
+  never on an adapter or on `Storage` itself.
+- Build one: `Storage(LocalAdapter("var/storage"))`, `Storage(InMemoryAdapter())`,
+  `Storage(S3Adapter("bucket", prefix="avatars"))`.
+- Write and read: `await storage.write("a/b.txt", b"...")`, `await storage.read("a/b.txt")`.
+- Large files: `storage.read_stream(path)` and `await storage.write_stream(path, chunks)`.
+- Per-call options lay over the storage's own: `await storage.write(path, data, {"visibility": "public"})`.
+- Close what you build: `async with Storage(adapter) as storage:`, or `await storage.close()`.
+- Several storages behind one: `MountManager({"uploads": ..., "reports": ...})`, paths `uploads://a.png`.
+- In an application: activate `StorageBundle`, inject `StorageOperatorInterface`.
+
+## Read and write
+
+```python
+from xtr_storage import InMemoryAdapter, Storage, Visibility
+
+
+async with Storage(InMemoryAdapter()) as storage:
+    await storage.write("notes/todo.txt", b"buy milk", {"visibility": Visibility.PUBLIC})
+    data = await storage.read("notes/todo.txt")  # b"buy milk"
+    await storage.file_exists("notes/todo.txt")  # True
+    await storage.mime_type("notes/todo.txt")  # "text/plain"
+    await storage.file_size("notes/todo.txt")  # 8
+    await storage.copy("notes/todo.txt", "notes/copy.txt")
+    await storage.move("notes/copy.txt", "archive/copy.txt")
+    names = sorted([entry.path async for entry in storage.list_contents("notes", deep=True)])
+    await storage.delete("notes/todo.txt")
+```
+
+| Call | Does |
+| --- | --- |
+| `read(path)`, `read_stream(path)` | The whole file, or its chunks as an async iterator |
+| `write(path, data, config=None)`, `write_stream(path, stream, config=None)` | Creates or replaces; the stream may be async, a plain iterable, or a binary file object |
+| `file_exists`, `directory_exists`, `has` | Existence; `has` is either |
+| `list_contents(path="", deep=False)` | A lazy listing of `FileAttributes` / `DirectoryAttributes`; nothing is read until iterated |
+| `file_size`, `last_modified`, `mime_type`, `visibility` | Metadata |
+| `copy`, `move`, `delete`, `delete_directory`, `create_directory` | Changes |
+| `set_visibility(path, visibility)` | `Visibility.PUBLIC` or `Visibility.PRIVATE`; each member is its string |
+| `checksum(path, config=None)` | The backend's digest when it keeps one, else hashed here |
+| `public_url(path)`, `temporary_url(path, expires_at)` | Lasting and expiring addresses |
+
+Paths are normalized before an adapter sees them: backslashes become `/`, `.` and empty segments
+drop. A control or zero-width character raises `CorruptedPathDetectedError`; `..` climbing past
+the root raises `PathTraversalDetectedError` when `allow_relative_path_traversal` is `False`.
+
+## Pick an adapter
+
+| Adapter | Where | Extra | Visibility | Urls |
+| --- | --- | --- | --- | --- |
+| `LocalAdapter(root)` | A directory on this machine | — | permission bits | only through a configured generator |
+| `InMemoryAdapter()` | A dictionary in this process | — | remembered per file | only through a configured generator |
+| `S3Adapter(bucket, prefix=..., region=...)` | An S3 bucket | `s3` | access list | public and signed |
+| `GcsAdapter(bucket, prefix=...)` | A Google Cloud Storage bucket | `gcs` | refused | public and signed |
+| `GenericFsspecAdapter(filesystem, root=...)` | Any fsspec filesystem | — | refused | only through a configured generator |
+| `ReadOnlyAdapter(adapter)` | Any of the above, writes refused | — | as wrapped | as wrapped |
+| `PathPrefixedAdapter(adapter, prefix)` | Any of the above, under a prefix | — | as wrapped | as wrapped |
+
+An adapter whose extra is missing raises `MissingBackendError` naming it. A capability a backend
+lacks raises `FeatureNotSupportedError` instead of guessing. No adapter opens anything when built;
+`LocalAdapter` creates its root on the first write.
+
+## Several storages
+
+```python
+from xtr_storage import InMemoryAdapter, MountManager, Storage
+
+async with MountManager(
+    {"uploads": Storage(InMemoryAdapter()), "reports": Storage(InMemoryAdapter())}
+) as files:
+    await files.write("uploads://a.txt", b"hi")
+    await files.copy("uploads://a.txt", "reports://a.txt")  # streamed across storages
+```
+
+There is no default mount: an unknown name, a missing `://` or an empty name raises
+`UnableToResolveMountError`.
+
+## Testing
+
+The package ships no test helpers; `InMemoryAdapter` is the one a test needs.
+
+- Hand the code under test `Storage(InMemoryAdapter())`. Two in-memory adapters share nothing, so
+  a test that writes has nothing to undo.
+- Assert what was stored by reading it back through the same storage.
+- In an application test, replace the service:
+  `boot_for_test(kernel, overrides={StorageOperatorInterface: Storage(InMemoryAdapter())})`.
+
+```python
+from xtr_storage import InMemoryAdapter, Storage
+
+
+async def test_the_report_is_stored() -> None:
+    storage = Storage(InMemoryAdapter())
+
+    await write_report(storage)
+
+    assert await storage.read("reports/2026.txt") == b"hello"
+```
+
+## Use in an application
+
+`uv run xtr-recipes recipes:sync` applies the recipe shipped with this package: it lists
+`StorageBundle` and ignores `/var/storage/`. That is the steps below a recipe can do; the others it
+prints for you to make.
+
+1. **Install** — `uv add "xtr-storage[di]"`; add `s3` or `gcs` for the object stores you reach.
+2. **Activate** — `StorageBundle: {"all": True}` in `BUNDLES` in `<app>/bundles.py`, imported from
+   `xtr_storage.bundle`.
+3. **Brings along** — nothing; the bundle requires no other.
+4. **Configure** — optional; with no configuration there is one `default` storage on local files
+   under `var/storage`, and nothing is opened until it is first used:
+
+   ```python
+   # <app>/config/storage.py
+   from xtr_dependency_injection import configure, env
+   from xtr_storage.bundle import LocalAdapterConfig, S3AdapterConfig, StorageConfig, StorageDefinition
+
+
+   @configure
+   def storage() -> StorageConfig:
+       return StorageConfig(
+           storages={
+               "default": LocalAdapterConfig(),
+               "uploads": StorageDefinition(
+                   adapter=S3AdapterConfig(bucket=env("UPLOADS_BUCKET"), region=env("AWS_REGION")),
+                   prefix="avatars",
+                   visibility="public",
+               ),
+           },
+       )
+   ```
+
+   An adapter entry is `LocalAdapterConfig`, `MemoryAdapterConfig`, `S3AdapterConfig`,
+   `GcsAdapterConfig`, `FsspecAdapterConfig`, or a `Reference` to an adapter the container
+   provides. A `StorageDefinition` adds `visibility`, `directory_visibility`,
+   `retain_visibility`, `public_url`, `read_only` and `prefix`.
+5. **Environment** — nothing required; credentials and directories given as `env(...)` must be set
+   when the application boots, because booting checks every storage.
+6. **Ignore** — `/var/storage/` in `.gitignore`.
+7. **Use** — inject `StorageOperatorInterface` for the `default` storage, or qualify by name. A
+   `MountManager` over every storage is provided too.
+
+   ```python
+   from typing import Annotated
+
+   from xtr_dependency_injection import Target, as_service
+   from xtr_storage import StorageOperatorInterface
+
+
+   @as_service
+   class Avatars:
+       def __init__(
+           self,
+           storage: StorageOperatorInterface,  # the default storage
+           uploads: Annotated[StorageOperatorInterface, Target("uploads")],
+       ) -> None: ...
+   ```
+
+8. **Check** — `debug:bundles` shows `storage` as `listed` and `active`.
+9. **Remove** — drop the `BUNDLES` entry, delete `<app>/config/storage.py`, then
+   `uv remove xtr-storage`.
+
+## Errors
+
+Everything derives from `StorageError`; a failure of an operation the backend refused derives from
+`StorageOperationFailedError` and names the operation. No message repeats a credential.
+
+| Error | Raised when |
+| --- | --- |
+| `UnableToReadFileError`, `UnableToWriteFileError` | A read or write fails, or the file is missing |
+| `UnableToDeleteFileError`, `UnableToDeleteDirectoryError`, `UnableToCreateDirectoryError` | A delete or a directory creation fails |
+| `UnableToCopyFileError`, `UnableToMoveFileError` | A copy or move fails, or the paths are the same under a `fail` policy |
+| `UnableToRetrieveMetadataError`, `UnableToSetVisibilityError` | Metadata cannot be read, or a visibility set |
+| `UnableToListContentsError` | A listing fails while it is iterated |
+| `UnableToProvideChecksumError`, `ChecksumAlgorithmNotSupportedError` | No checksum can be produced |
+| `UnableToGeneratePublicUrlError`, `UnableToGenerateTemporaryUrlError` | No url can be produced |
+| `UnableToResolveMountError` | A mount location names no storage, or is malformed |
+| `PathTraversalDetectedError`, `CorruptedPathDetectedError` | A path climbs past the root, or carries a control character |
+| `FeatureNotSupportedError` | The backend lacks the capability (also a `NotImplementedError`) |
+| `MissingBackendError` | The adapter's extra is not installed (also an `ImportError`) |
+| `InvalidVisibilityError`, `InvalidArgumentError` | A bad visibility string or option (also a `ValueError`) |
+| `InvalidStreamError` | A write stream of a type the storage cannot read (also a `TypeError`) |
+
+## Do not
+
+- Do not depend on an adapter or on `Storage` in application code; depend on
+  `StorageOperatorInterface` and let the container pick the backend.
+- Do not build paths with `os.path` or `pathlib`; pass `/`-separated strings, as every backend
+  sees them.
+- Do not read a large file whole with `read`; stream it with `read_stream` and `write_stream`.
+- Do not expect a backend to fake a capability: GCS and generic fsspec backends refuse visibility,
+  and a local or in-memory storage gives urls only through a configured generator.
+- Do not leave a storage you built open; use `async with` or `close()`. The container closes the
+  ones it built.
+- Do not put credentials in code; read them with `env(...)` in `config/storage.py`.

xtr_storage/__init__.py

@@ -0,0 +1,158 @@
+"""Files on local disk, in memory or in object stores, behind one async interface.
+
+A ``Storage`` wraps one adapter and turns paths into reads, writes, listings,
+copies and moves. The adapter decides where the bytes live — a directory on this
+machine, a dictionary in this process, a bucket on an object store — so code that
+stores files is written once and moved between them by its constructor.
+
+Every call that touches a backend is awaited.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from xtr_storage.adapter import (
+    FsspecAdapter,
+    GcsAdapter,
+    GenericFsspecAdapter,
+    InMemoryAdapter,
+    LocalAdapter,
+    PathPrefixedAdapter,
+    PortableVisibilityConverter,
+    ReadOnlyAdapter,
+    S3Adapter,
+    StorageAdapterInterface,
+    VisibilityConverterInterface,
+)
+from xtr_storage.checksum_provider_interface import ChecksumProviderInterface
+from xtr_storage.config import Config
+from xtr_storage.directory_attributes import DirectoryAttributes
+from xtr_storage.directory_listing import DirectoryListing
+from xtr_storage.exception import (
+    ChecksumAlgorithmNotSupportedError,
+    CorruptedPathDetectedError,
+    FeatureNotSupportedError,
+    InvalidArgumentError,
+    InvalidStreamError,
+    InvalidVisibilityError,
+    MissingBackendError,
+    PathTraversalDetectedError,
+    StorageError,
+    StorageOperationFailedError,
+    SymbolicLinkEncounteredError,
+    UnableToCheckDirectoryExistenceError,
+    UnableToCheckExistenceError,
+    UnableToCheckFileExistenceError,
+    UnableToCopyFileError,
+    UnableToCreateDirectoryError,
+    UnableToDeleteDirectoryError,
+    UnableToDeleteFileError,
+    UnableToGeneratePublicUrlError,
+    UnableToGenerateTemporaryUrlError,
+    UnableToListContentsError,
+    UnableToMoveFileError,
+    UnableToProvideChecksumError,
+    UnableToReadFileError,
+    UnableToResolveMountError,
+    UnableToRetrieveMetadataError,
+    UnableToSetVisibilityError,
+    UnableToWriteFileError,
+)
+from xtr_storage.feature import Feature
+from xtr_storage.file_attributes import FileAttributes
+from xtr_storage.identical_path_policy import IdenticalPathPolicy
+from xtr_storage.link_handling import LinkHandling
+from xtr_storage.mime_type import ExtensionMimeTypeDetector, MimeTypeDetectorInterface
+from xtr_storage.mount_manager import MountManager
+from xtr_storage.operation import Operation
+from xtr_storage.path import PathNormalizerInterface, PathPrefixer, WhitespacePathNormalizer
+from xtr_storage.storage import Storage
+from xtr_storage.storage_attributes import StorageAttributes
+from xtr_storage.storage_operator_interface import StorageOperatorInterface
+from xtr_storage.storage_reader_interface import StorageReaderInterface
+from xtr_storage.storage_writer_interface import StorageWriterInterface
+from xtr_storage.url_generation import (
+    ChainedPublicUrlGenerator,
+    PrefixPublicUrlGenerator,
+    PublicUrlGeneratorInterface,
+    ShardedPrefixPublicUrlGenerator,
+    TemporaryUrlGeneratorInterface,
+)
+from xtr_storage.visibility import Visibility
+
+try:
+    __version__ = version("xtr-storage")
+except PackageNotFoundError:  # pragma: no cover
+    # Running from a source tree or a vendored copy, with no installed
+    # metadata to read. Having no version is better than refusing to import.
+    __version__ = "0+unknown"
+
+__all__ = [
+    "ChainedPublicUrlGenerator",
+    "ChecksumAlgorithmNotSupportedError",
+    "ChecksumProviderInterface",
+    "Config",
+    "CorruptedPathDetectedError",
+    "DirectoryAttributes",
+    "DirectoryListing",
+    "ExtensionMimeTypeDetector",
+    "Feature",
+    "FeatureNotSupportedError",
+    "FileAttributes",
+    "FsspecAdapter",
+    "GcsAdapter",
+    "GenericFsspecAdapter",
+    "IdenticalPathPolicy",
+    "InMemoryAdapter",
+    "InvalidArgumentError",
+    "InvalidStreamError",
+    "InvalidVisibilityError",
+    "LinkHandling",
+    "LocalAdapter",
+    "MimeTypeDetectorInterface",
+    "MissingBackendError",
+    "MountManager",
+    "Operation",
+    "PathNormalizerInterface",
+    "PathPrefixedAdapter",
+    "PathPrefixer",
+    "PathTraversalDetectedError",
+    "PortableVisibilityConverter",
+    "PrefixPublicUrlGenerator",
+    "PublicUrlGeneratorInterface",
+    "ReadOnlyAdapter",
+    "S3Adapter",
+    "ShardedPrefixPublicUrlGenerator",
+    "Storage",
+    "StorageAdapterInterface",
+    "StorageAttributes",
+    "StorageError",
+    "StorageOperationFailedError",
+    "StorageOperatorInterface",
+    "StorageReaderInterface",
+    "StorageWriterInterface",
+    "SymbolicLinkEncounteredError",
+    "TemporaryUrlGeneratorInterface",
+    "UnableToCheckDirectoryExistenceError",
+    "UnableToCheckExistenceError",
+    "UnableToCheckFileExistenceError",
+    "UnableToCopyFileError",
+    "UnableToCreateDirectoryError",
+    "UnableToDeleteDirectoryError",
+    "UnableToDeleteFileError",
+    "UnableToGeneratePublicUrlError",
+    "UnableToGenerateTemporaryUrlError",
+    "UnableToListContentsError",
+    "UnableToMoveFileError",
+    "UnableToProvideChecksumError",
+    "UnableToReadFileError",
+    "UnableToResolveMountError",
+    "UnableToRetrieveMetadataError",
+    "UnableToSetVisibilityError",
+    "UnableToWriteFileError",
+    "Visibility",
+    "VisibilityConverterInterface",
+    "WhitespacePathNormalizer",
+    "__version__",
+]

xtr_storage/adapter/__init__.py

@@ -0,0 +1,29 @@
+"""Where the bytes actually live: one adapter per kind of backend."""
+
+from __future__ import annotations
+
+from .fsspec_adapter import FsspecAdapter
+from .gcs_adapter import GcsAdapter
+from .generic_fsspec_adapter import GenericFsspecAdapter
+from .in_memory_adapter import InMemoryAdapter
+from .local_adapter import LocalAdapter
+from .path_prefixed_adapter import PathPrefixedAdapter
+from .portable_visibility_converter import PortableVisibilityConverter
+from .read_only_adapter import ReadOnlyAdapter
+from .s3_adapter import S3Adapter
+from .storage_adapter_interface import StorageAdapterInterface
+from .visibility_converter_interface import VisibilityConverterInterface
+
+__all__ = [
+    "FsspecAdapter",
+    "GcsAdapter",
+    "GenericFsspecAdapter",
+    "InMemoryAdapter",
+    "LocalAdapter",
+    "PathPrefixedAdapter",
+    "PortableVisibilityConverter",
+    "ReadOnlyAdapter",
+    "S3Adapter",
+    "StorageAdapterInterface",
+    "VisibilityConverterInterface",
+]

xtr_storage/adapter/_fsspec_bridge.py

@@ -0,0 +1,212 @@
+# pyright: reportMissingTypeStubs=false, reportUnknownMemberType=false, reportUnknownVariableType=false, reportUnknownArgumentType=false, reportAttributeAccessIssue=false, reportAny=false, reportExplicitAny=false
+# fsspec ships no type information, so every attribute reached on the wrapped
+# filesystem is untyped to the checker; the directives above are confined to
+# this one module, and every value is copied into a typed shape at the boundary.
+"""The one place a filesystem is spoken to, turned into typed coroutines.
+
+Every backend this package builds on is an fsspec filesystem, and fsspec speaks
+two dialects: a synchronous one whose blocking calls must be pushed off the
+event loop, and an asynchronous one whose real work hides behind ``_``-prefixed
+coroutines that need a session opened first. This bridge is the seam that hides
+that split: an adapter awaits :class:`FsspecBridge` methods and never learns
+which dialect answered, and the untyped surface of fsspec is fenced to this file
+so the rest of the package stays fully typed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any, final
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from fsspec import AbstractFileSystem
+
+__all__ = ["FsspecBridge"]
+
+
+@final
+class FsspecBridge:
+    """A typed async front to one fsspec filesystem, sync or asynchronous.
+
+    The bridge owns nothing the filesystem does not already own except the
+    session it opens on demand. It creates no filesystem — an adapter hands it
+    one — and it does no I/O until a method is awaited, so constructing it is
+    free. On an asynchronous filesystem the first awaited method opens the
+    session once, under a lock, and ``close`` hands that session back to a
+    per-backend closer; on a synchronous one every call is pushed to a worker
+    thread and there is nothing to close.
+    """
+
+    __slots__ = (
+        "_closed",
+        "_closer",
+        "_fs",
+        "_session_created",
+        "_session_lock",
+        "_session_ready",
+    )
+
+    def __init__(
+        self,
+        filesystem: AbstractFileSystem,
+        *,
+        closer: Callable[[AbstractFileSystem], Awaitable[None]] | None = None,
+    ) -> None:
+        """Wrap a filesystem, remembering how to close any session it opens.
+
+        Args:
+            filesystem: The fsspec filesystem to speak to; kept as given, its
+                dialect read from ``async_impl`` and ``asynchronous`` on each
+                call so a caller may flip ``asynchronous`` before first use.
+            closer: What to run once, on ``close``, when a session was opened —
+                the S3 and object-store adapters pass the coroutine that shuts
+                their client down. ``None`` means there is nothing to close.
+        """
+        self._fs = filesystem
+        self._closer = closer
+        self._session_lock = asyncio.Lock()
+        self._session_ready = False
+        self._session_created = False
+        self._closed = False
+
+    @property
+    def _is_async(self) -> bool:
+        """Whether calls must go through the ``_``-prefixed coroutines."""
+        return bool(self._fs.async_impl and self._fs.asynchronous)  # ty: ignore[unresolved-attribute] -- fsspec ships no type information; asynchronous is set on the async filesystem
+
+    async def _ensure_session(self) -> None:
+        """Open the filesystem's session once, the first async call to need it.
+
+        A filesystem without ``set_session`` (a plain asynchronous one) needs no
+        session; one with it (s3fs, gcsfs) gets exactly one call however many
+        coroutines race here, because the lock and the flag together let only
+        the first through.
+        """
+        if self._session_ready:
+            return
+        async with self._session_lock:
+            if self._session_ready:
+                return
+            set_session = getattr(self._fs, "set_session", None)
+            if set_session is not None:
+                _ = await set_session()
+                self._session_created = True
+            self._session_ready = True
+
+    async def _dispatch(self, name: str, *args: object, **kwargs: object) -> Any:  # noqa: ANN401
+        """Run one filesystem method the way its dialect requires.
+
+        Args:
+            name: The synchronous method name; the asynchronous dialect is
+                reached at ``_`` + ``name``.
+            *args: Positional arguments passed through unchanged.
+            **kwargs: Keyword arguments passed through unchanged.
+
+        Returns:
+            Whatever the filesystem returned, untyped — fsspec ships no types, so
+            this one seam is ``Any`` and every caller copies it into a typed
+            shape at the boundary before it escapes the module.
+        """
+        if self._is_async:
+            await self._ensure_session()
+            return await getattr(self._fs, "_" + name)(*args, **kwargs)
+        return await asyncio.to_thread(getattr(self._fs, name), *args, **kwargs)
+
+    async def info(self, path: str) -> dict[str, object]:
+        """Return what the filesystem knows about one path, copied out."""
+        result = await self._dispatch("info", path)
+        return dict(result)
+
+    async def ls(self, path: str, *, detail: bool = True) -> list[dict[str, object]]:
+        """List one directory in detail, each entry copied out."""
+        result = await self._dispatch("ls", path, detail=detail)
+        return [dict(entry) for entry in result]
+
+    async def find(self, path: str, *, withdirs: bool) -> dict[str, dict[str, object]]:
+        """Walk a tree, returning every path mapped to its detail, copied out."""
+        result = await self._dispatch("find", path, withdirs=withdirs, detail=True)
+        return {key: dict(value) for key, value in result.items()}
+
+    async def cat_file(self, path: str, start: int | None = None, end: int | None = None) -> bytes:
+        """Read a file, or the byte range ``[start, end)`` of it."""
+        result = await self._dispatch("cat_file", path, start=start, end=end)
+        return bytes(result)
+
+    async def pipe_file(self, path: str, data: bytes, **kwargs: object) -> None:
+        """Write ``data`` to ``path`` in one call."""
+        _ = await self._dispatch("pipe_file", path, data, **kwargs)
+
+    async def put_file(self, local_path: str, remote_path: str, **kwargs: object) -> None:
+        """Upload a local file to ``remote_path``."""
+        _ = await self._dispatch("put_file", local_path, remote_path, **kwargs)
+
+    async def rm_file(self, path: str) -> None:
+        """Remove one file."""
+        _ = await self._dispatch("rm_file", path)
+
+    async def rm(self, path: str, *, recursive: bool = True) -> None:
+        """Remove a path, its whole tree by default."""
+        _ = await self._dispatch("rm", path, recursive=recursive)
+
+    async def mkdir(self, path: str, *, create_parents: bool = True) -> None:
+        """Make a directory, its parents too by default."""
+        _ = await self._dispatch("mkdir", path, create_parents=create_parents)
+
+    async def cp_file(self, src: str, dst: str, **kwargs: object) -> None:
+        """Copy one file within the filesystem."""
+        _ = await self._dispatch("cp_file", src, dst, **kwargs)
+
+    async def mv(self, src: str, dst: str) -> None:
+        """Move one file, falling back to copy-then-delete where ``_mv`` is absent.
+
+        The synchronous dialect has ``mv``; the asynchronous base does not
+        expose ``_mv``, so there the move is a copy followed by a delete —
+        exactly what an object store does anyway.
+        """
+        if self._is_async:
+            await self._ensure_session()
+            mv_method = getattr(self._fs, "_mv", None)
+            if mv_method is not None:
+                _ = await mv_method(src, dst)
+                return
+            await self.cp_file(src, dst)
+            await self.rm_file(src)
+            return
+        _ = await asyncio.to_thread(self._fs.mv, src, dst)
+
+    async def sign(self, path: str, expiration: int) -> str:
+        """Return a signed URL for ``path``, valid ``expiration`` seconds.
+
+        The asynchronous dialect signs through ``_url`` when a backend provides
+        it (s3fs, gcsfs); otherwise, and for the synchronous dialect, the
+        blocking ``sign`` is pushed to a worker thread.
+        """
+        if self._is_async:
+            await self._ensure_session()
+            url_method = getattr(self._fs, "_url", None)
+            if url_method is not None:
+                return str(await url_method(path, expires=expiration))
+        return str(await asyncio.to_thread(self._fs.sign, path, expiration))
+
+    async def exists(self, path: str) -> bool:
+        """Whether the path exists."""
+        return bool(await self._dispatch("exists", path))
+
+    async def call(self, name: str, *args: object, **kwargs: object) -> object:
+        """Run a backend-specific method by name, dispatched like the rest.
+
+        The escape hatch for what only one backend does — an ACL read, a chmod —
+        so those adapters need no second seam. The return is untyped; the caller
+        parses it.
+        """
+        return await self._dispatch(name, *args, **kwargs)
+
+    async def close(self) -> None:
+        """Close the session, once, if one was opened; safe to call again."""
+        if self._closed:
+            return
+        self._closed = True
+        if self._closer is not None and self._session_created:
+            await self._closer(self._fs)