asanypath 2.0.0__py3-none-any.whl

asanypath/asanypath.pyi

@@ -0,0 +1,225 @@
+# Copyright (C) 2026 Axis Communications AB, Lund, Sweden
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable
+from os import PathLike, stat_result
+from pathlib import Path
+from typing import Any, Self, TypeAlias
+
+from anyio import AsyncFile
+from anyio import Path as AioPath
+
+class BackendOptions:
+    headers: dict[str, str]
+    query: dict[str, str]
+    provider: dict[str, Any]
+
+class AccessGrant:
+    principal: str
+    actions: frozenset[str]
+    def __init__(self, principal: str, actions: frozenset[str]) -> None: ...
+
+class AccessPolicy:
+    owner: str | None
+    group: str | None
+    grants: tuple[AccessGrant, ...]
+    provider: dict[str, Any]
+    def __init__(
+        self,
+        *,
+        owner: str | None = None,
+        group: str | None = None,
+        grants: tuple[AccessGrant, ...] = (),
+        provider: dict[str, Any] = {},
+    ) -> None: ...
+
+class AccessPolicyPatch:
+    owner: str | None
+    group: str | None
+    grants: tuple[AccessGrant, ...]
+    provider: dict[str, Any]
+    def __init__(
+        self,
+        *,
+        owner: str | None = None,
+        group: str | None = None,
+        grants: tuple[AccessGrant, ...] = (),
+        provider: dict[str, Any] = {},
+    ) -> None: ...
+
+PathPart: TypeAlias = str | Path | AioPath | PathLike[str] | PathLike[bytes] | AsAnyPurePath
+
+PROTOCOL_MAP: dict[str, type[AsAnyPurePath]]
+
+class AsAnyPurePath:
+    def __new__(cls, arg: PathPart = ".", *args: PathPart, **kwargs: Any) -> Self: ...
+    def __rtruediv__(self, other: str | PathLike[str]) -> Self: ...
+    def __truediv__(self, other: str | PathLike[str]) -> Self: ...
+    @property
+    def anchor(self) -> str: ...
+    def as_posix(self) -> str: ...
+    def as_uri(self) -> str: ...
+    @property
+    def drive(self) -> str: ...
+    def full_match(self, pattern: str, *, case_sensitive: bool | None = None) -> bool: ...
+    def is_absolute(self) -> bool: ...
+    def is_relative_to(self, other: str | PathLike[str]) -> bool: ...
+    def joinpath(self, *args: str | PathLike[str]) -> Self: ...
+    def match(self, pattern: str, *, case_sensitive: bool | None = None) -> bool: ...
+    @property
+    def name(self) -> str: ...
+    @property
+    def parent(self) -> Self: ...
+    @property
+    def parents(self) -> tuple[Self, ...]: ...
+    @property
+    def parts(self) -> tuple[str, ...]: ...
+    def relative_to(self, *other: str | PathLike[str], walk_up: bool = False) -> Self: ...
+    @property
+    def root(self) -> str: ...
+    @property
+    def stem(self) -> str: ...
+    @property
+    def suffix(self) -> str: ...
+    @property
+    def suffixes(self) -> list[str]: ...
+    def with_name(self, name: str) -> Self: ...
+    def with_parent(self, parent: str | PathLike[str] | Self) -> Self: ...
+    def with_segments(self, *pathsegments: str | PathLike[str] | Self) -> Self: ...
+    def with_stem(self, stem: str) -> Self: ...
+    def with_suffix(self, suffix: str) -> Self: ...
+
+class AsAnyPath(AsAnyPurePath):
+    def __new__(cls, arg: PathPart = ".", *args: PathPart, **kwargs: Any) -> Self: ...
+    def __bytes__(self) -> bytes: ...
+    def __fspath__(self) -> str: ...
+    def absolute(self) -> Self: ...
+    def chmod(self, mode: int, *, follow_symlinks: bool = True) -> None: ...
+    @classmethod
+    def cwd(cls) -> Self: ...
+    async def exists(self) -> bool: ...
+    def expanduser(self) -> Self: ...
+    async def get_access_policy(
+        self, *, backend_options: BackendOptions | None = None
+    ) -> AccessPolicy: ...
+    async def glob(
+        self, pattern: str, *, case_sensitive: bool | None = None
+    ) -> AsyncIterator[Self]: ...
+    def group(self) -> str: ...
+    def hardlink_to(self, target: str | bytes | PathLike[str] | PathLike[bytes]) -> None: ...
+    @classmethod
+    def home(cls) -> Self: ...
+    def is_block_device(self) -> bool: ...
+    def is_char_device(self) -> bool: ...
+    async def is_dir(self) -> bool: ...
+    def is_fifo(self) -> bool: ...
+    async def is_file(self) -> bool: ...
+    def is_junction(self) -> bool: ...
+    def is_mount(self) -> bool: ...
+    def is_socket(self) -> bool: ...
+    def is_symlink(self) -> bool: ...
+    async def iterdir(self) -> AsyncIterator[Self]: ...
+    def lchmod(self, mode: int) -> None: ...
+    def lstat(self) -> stat_result: ...
+    async def mkdir(
+        self, mode: int = 0o777, parents: bool = False, exist_ok: bool = False
+    ) -> None: ...
+    async def copy(
+        self,
+        dst: PathPart,
+        *,
+        recursive: bool = False,
+        remove_src: bool = False,
+        force: bool = False,
+        atomic: bool = False,
+        chunk_size: int | None = None,
+        destination_backend_options: BackendOptions | None = None,
+        on_progress: Callable[[int, int, Self, Self], None | Awaitable[None]] | None = None,
+        on_done: Callable[[Self, Self, int, bool, BaseException | None], None | Awaitable[None]]
+        | None = None,
+    ) -> Self: ...
+    async def move(
+        self,
+        target: PathPart,
+        *,
+        force: bool = False,
+        atomic: bool = False,
+        chunk_size: int | None = None,
+        destination_backend_options: BackendOptions | None = None,
+    ) -> Self: ...
+    def open(
+        self,
+        mode: str = "r",
+        buffering: int = -1,
+        encoding: str | None = None,
+        errors: str | None = None,
+        newline: str | None = None,
+        *,
+        backend_options: BackendOptions | None = None,
+    ) -> AsyncFile[Any]: ...
+    def owner(self) -> str: ...
+    async def read_bytes(self) -> bytes: ...
+    def iter_bytes(self, chunk_size: int | None = None) -> AsyncIterator[bytes]: ...
+    async def read_text(
+        self, encoding: str | None = None, errors: str | None = None, newline: str | None = None
+    ) -> str: ...
+    def readlink(self) -> Self: ...
+    async def rename(
+        self,
+        target: PathPart,
+        *,
+        force: bool = False,
+        atomic: bool = False,
+        chunk_size: int | None = None,
+        destination_backend_options: BackendOptions | None = None,
+    ) -> Self: ...
+    async def replace(
+        self, target: PathPart, *, destination_backend_options: BackendOptions | None = None
+    ) -> Self: ...
+    def resolve(self, strict: bool = False) -> Self: ...
+    async def rglob(
+        self, pattern: str, *, case_sensitive: bool | None = None
+    ) -> AsyncIterator[Self]: ...
+    async def rmdir(self) -> None: ...
+    def samefile(self, other_path: str | PathLike[str]) -> bool: ...
+    async def stat(self, *, follow_symlinks: bool = True) -> stat_result: ...
+    def symlink_to(
+        self,
+        target: str | bytes | PathLike[str] | PathLike[bytes] | Self,
+        target_is_directory: bool = False,
+    ) -> None: ...
+    async def touch(self, mode: int = 0o666, exist_ok: bool = True) -> None: ...
+    async def unlink(self, missing_ok: bool = False) -> None: ...
+    async def update_access_policy(
+        self,
+        policy_patch: AccessPolicyPatch,
+        *,
+        backend_options: BackendOptions | None = None,
+    ) -> None: ...
+    async def walk(
+        self,
+        top_down: bool = True,
+        on_error: Callable[[OSError], object] | None = None,
+        follow_symlinks: bool = False,
+    ) -> AsyncIterator[tuple[Self, list[str], list[str]]]: ...
+    async def write_bytes(
+        self, data: bytes, *, backend_options: BackendOptions | None = None
+    ) -> int: ...
+    async def write_text(
+        self,
+        data: str,
+        encoding: str | None = None,
+        errors: str | None = None,
+        newline: str | None = None,
+        *,
+        backend_options: BackendOptions | None = None,
+    ) -> int: ...
+    async def checksums(self) -> dict[str, str]: ...
+
+def register_protocol(protocol: str, path_class: type[AsAnyPurePath]) -> None: ...
+def list_protocols() -> list[str]: ...

asanypath/azure.py

@@ -0,0 +1,274 @@
+# Copyright (C) 2026 Axis Communications AB, Lund, Sweden
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+"""Azure Blob Storage path implementation (HTTP-style adapter).
+
+Uses the Azure Blob Storage REST API:
+https://learn.microsoft.com/en-us/rest/api/storageservices/blob-service-rest-api
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import datetime, timezone
+from os import getenv
+from types import SimpleNamespace
+
+import msgspec
+
+from asanypath.cloud import CloudPathMixin
+from asanypath.options import AccessGrant, AccessPolicy, AccessPolicyPatch, BackendOptions
+from asanypath_native import (
+    az_copy_batch,
+    az_delete_batch,
+    az_exists_batch,
+    az_get_batch,
+    az_get_container_acl,
+    az_head_batch,
+    az_is_dir,
+    az_is_dir_batch,
+    az_list_batch,
+    az_list_containers,
+    az_presign,
+    az_put_batch,
+    az_put_container_acl,
+)
+
+AZURE_API_VERSION = "2023-11-03"
+
+
+def _parse_connection_string(cs: str | None) -> dict[str, str]:
+    """Parse an Azure Storage connection string into asanypath config keys."""
+    if not cs:
+        return {}
+    parts: dict[str, str] = {}
+    for seg in cs.split(";"):
+        key, sep, val = seg.partition("=")
+        if sep and key.strip():
+            parts[key.strip().lower()] = val.strip()
+    out: dict[str, str] = {}
+    if name := parts.get("accountname"):
+        out["account_name"] = name
+    if key := parts.get("accountkey"):
+        out["account_key"] = key
+    if sas := parts.get("sharedaccesssignature"):
+        out["sas_token"] = sas
+    if endpoint := parts.get("blobendpoint"):
+        out["endpoint_url"] = endpoint
+    elif name := parts.get("accountname"):
+        proto = parts.get("defaultendpointsprotocol", "https")
+        suffix = parts.get("endpointsuffix", "core.windows.net")
+        out["endpoint_url"] = f"{proto}://{name}.blob.{suffix}"
+    return out
+
+
+class AzurePath(CloudPathMixin):
+    """Async path implementation for Azure Blob Storage.
+
+    Uses the Azure Blob Storage REST API via the shared-key or SAS authentication.
+    Supports: exists, is_file, is_dir, iterdir, read/write, unlink, touch, rename, stat.
+
+    Example:
+        ```python
+        path = AzurePath("az://container/blob/path.txt",
+                        account_name="myaccount",
+                        account_key="base64-encoded-key")
+        content = await path.read_bytes()
+        ```
+    """
+
+    protocol: str = "az"
+    _supports_range_read: bool = True
+    _is_dir_batch_fn = staticmethod(az_is_dir_batch)
+    _copy_batch_fn = staticmethod(az_copy_batch)
+
+    @staticmethod
+    def _batcher_key_fn(
+        endpoint: str,
+        container: str,
+        account_name: str = "",
+        account_key: str | None = None,
+        sas_token: str | None = None,
+    ) -> str:
+        return f"{endpoint}|{container}|{account_name}"
+
+    _batcher_ops = {
+        "get": {"batch_fn": az_get_batch, "items_key": "blob_paths", "wrap": bytes},
+        "exists": {"batch_fn": az_exists_batch, "items_key": "blob_paths"},
+        "head": {"batch_fn": az_head_batch, "items_key": "blob_paths"},
+        "delete": {"batch_fn": az_delete_batch, "items_key": "blob_paths"},
+        "put": {"batch_fn": az_put_batch},
+        "list": {"batch_fn": az_list_batch, "items_key": "prefixes"},
+    }
+
+    def __init__(
+        self,
+        *args,
+        endpoint_url: str | None = None,
+        account_name: str | None = None,
+        account_key: str | None = None,
+        sas_token: str | None = None,
+        **kwargs,
+    ):
+        super().__init__(*args, **kwargs)
+        cfg = self.env_config
+        self._account_name = account_name or cfg.account_name
+        self._account_key = account_key or cfg.account_key
+        self._sas_token = sas_token or cfg.sas_token
+        self._endpoint_url = (
+            endpoint_url
+            or cfg.endpoint_url
+            or (f"https://{self._account_name}.blob.core.windows.net")
+        )
+        # Promote explicit params into class cache so derived instances
+        # (parent, /, with_name, etc.) inherit them.
+        if account_name:
+            cfg.account_name = account_name
+        if account_key:
+            cfg.account_key = account_key
+        if sas_token:
+            cfg.sas_token = sas_token
+        if endpoint_url:
+            cfg.endpoint_url = endpoint_url
+
+        # URL format: az://container/blob/path
+        self._container = self._path.host or ""
+        self._blob_path = self._path.path.lstrip("/")
+
+    @classmethod
+    def _create_env_config(cls) -> SimpleNamespace:
+        """Build env config from Azure environment variables / connection string."""
+        conn = _parse_connection_string(getenv("AZURE_STORAGE_CONNECTION_STRING"))
+        account_name = getenv("AZURE_STORAGE_ACCOUNT") or conn.get("account_name")
+        return SimpleNamespace(
+            account_name=account_name,
+            account_key=getenv("AZURE_STORAGE_KEY") or conn.get("account_key"),
+            sas_token=getenv("AZURE_STORAGE_SAS_TOKEN") or conn.get("sas_token"),
+            endpoint_url=(
+                getenv("AZURE_STORAGE_ENDPOINT")
+                or conn.get("endpoint_url")
+                or (f"https://{account_name}.blob.core.windows.net" if account_name else None)
+            ),
+        )
+
+    # ------------------------------------------------------------------
+    # CloudPathMixin hooks
+    # ------------------------------------------------------------------
+
+    @property
+    def _item_path(self) -> str:
+        return self._blob_path
+
+    @property
+    def _native_kwargs(self) -> dict:
+        return {
+            "endpoint": self._endpoint_url,
+            "container": self._container,
+            "account_name": self._account_name or "",
+            "account_key": self._account_key,
+            "sas_token": self._sas_token,
+        }
+
+    # ------------------------------------------------------------------
+    # Backend-specific operations
+    # ------------------------------------------------------------------
+
+    async def is_dir(self) -> bool:
+        """Check if path is a directory prefix (has blobs with this prefix)."""
+        return await az_is_dir(prefix=self._blob_path, **self._native_kwargs)
+
+    async def _list_containers(self) -> list[str] | None:
+        """List containers when at the account root (``az://``); else None."""
+        if self._container:
+            return None
+        names = await az_list_containers(
+            endpoint=self._endpoint_url,
+            account_name=self._account_name or "",
+            account_key=self._account_key,
+            sas_token=self._sas_token,
+            use_h2=False,
+        )
+        return [f"az://{name}" for name in names]
+
+    async def stat(self, *, follow_symlinks: bool = True) -> object:
+        """Get blob metadata from HEAD response."""
+        from types import SimpleNamespace
+
+        headers = await self._get_batcher().head(
+            item=self._blob_path,
+            **self._native_kwargs,
+        )
+        size = int(headers.get("Content-Length", headers.get("content-length", 0)))
+        last_modified = headers.get("Last-Modified", headers.get("last-modified"))
+        mtime = None
+        if last_modified:
+            mtime = (
+                datetime.strptime(last_modified, "%a, %d %b %Y %H:%M:%S GMT")
+                .replace(tzinfo=timezone.utc)
+                .timestamp()
+            )
+        return SimpleNamespace(st_size=size, st_ctime=mtime, st_mtime=mtime)
+
+    async def checksums(self) -> dict[str, str]:
+        """Return Content-MD5 from blob properties."""
+        headers = await self._get_batcher().head(
+            item=self._blob_path,
+            **self._native_kwargs,
+        )
+        md5 = headers.get("Content-MD5", headers.get("content-md5", ""))
+        return {"md5": md5}
+
+    async def get_access_policy(
+        self, *, backend_options: BackendOptions | None = None
+    ) -> AccessPolicy:
+        """Return the containing container's public access and stored policies."""
+        data = await az_get_container_acl(**self._native_kwargs)
+        if isinstance(data, str):
+            data = msgspec.json.decode(data)
+        if not isinstance(data, Mapping):
+            raise TypeError("native Azure ACL response must be a mapping")
+        public_access = data.get("public_access")
+        grants = (
+            (AccessGrant("everyone", frozenset({"read"})),)
+            if public_access in {"blob", "container", "true"}
+            else ()
+        )
+        return AccessPolicy(grants=grants, provider={"azure_container_acl": data})
+
+    async def update_access_policy(
+        self, policy_patch: AccessPolicyPatch, *, backend_options: BackendOptions | None = None
+    ) -> None:
+        """Replace the container ACL using ``provider["azure_container_acl"]``."""
+        acl = policy_patch.provider.get("azure_container_acl")
+        if not isinstance(acl, Mapping):
+            raise ValueError("Azure ACL replacement requires provider['azure_container_acl']")
+        await az_put_container_acl(
+            acl_json=msgspec.json.encode(acl).decode(), **self._native_kwargs
+        )
+
+    async def presign(self, *, expires: int = 3600, method: str = "GET") -> str:
+        """Generate a presigned URL for this Azure blob using a Service SAS token.
+
+        Requires account_key to be set. If a SAS token is already configured,
+        returns the blob URL with the existing SAS token appended.
+
+        Args:
+            expires: URL validity in seconds (default 3600).
+            method: HTTP method (used to determine SAS permission: r, w, d, c).
+
+        Returns:
+            A presigned URL string.
+        """
+        return az_presign(
+            endpoint=self._endpoint_url,
+            container=self._container,
+            blob_path=self._blob_path,
+            account_name=self._account_name or "",
+            account_key=self._account_key,
+            sas_token=self._sas_token,
+            method=method,
+            expires=expires,
+        )

asanypath/batcher.py

@@ -0,0 +1,206 @@
+# Copyright (C) 2026 Axis Communications AB, Lund, Sweden
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+"""Generic micro-batcher for native Rust batch operations.
+
+Transparently collects concurrent calls arriving in the same event-loop
+tick and dispatches them as a single batch, amortizing the PyO3 bridge
+overhead across all concurrent operations.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+# Batch size threshold: use HTTP/2 multiplexing when batch is large enough
+# to benefit from stream multiplexing over fewer connections; use HTTP/1.1
+# (parallel TCP connections) for smaller batches where framing overhead hurts.
+H2_BATCH_THRESHOLD = 20
+
+
+class MicroBatcher:
+    """Collects calls arriving in the same event-loop tick into one batch.
+
+    Each operation is registered with :meth:`register`, which returns a
+    submit coroutine callers use to enqueue work.  At the end of the
+    current tick, all enqueued items are flushed together via the
+    backend-provided *flush_fn*.
+
+    Parameters
+    ----------
+    key_fn:
+        Callable that produces a hashable grouping key from the keyword
+        arguments passed to the submit function.  Calls with the same
+        key are batched together.
+    """
+
+    def __init__(self) -> None:
+        self._pending: dict[str, list] = {}
+        self._scheduled: set[str] = set()
+        self._ops: dict[str, _OpSpec] = {}
+
+    def __getattr__(self, name: str) -> Callable[..., Coroutine]:
+        raise AttributeError(name)
+
+    # -----------------------------------------------------------------
+    # Registration
+    # -----------------------------------------------------------------
+
+    def register(
+        self,
+        op: str,
+        *,
+        flush_fn: Callable[..., Coroutine],
+        key_fn: Callable[..., str],
+        item_key: str = "item",
+        unpack_put: bool = False,
+    ) -> Callable[..., Coroutine]:
+        """Register a batch operation and return a *submit* coroutine.
+
+        Parameters
+        ----------
+        op:
+            Unique name for this operation (e.g. ``"get"``, ``"put"``).
+        flush_fn:
+            ``async def flush_fn(items, futures, use_h2, **kwargs)``
+            Called with the collected items list and their futures.
+        key_fn:
+            ``def key_fn(**kwargs) -> str`` — returns a grouping key.
+        item_key:
+            Name of the keyword argument that carries the per-call item
+            (default ``"item"``).
+        unpack_put:
+            If *True*, the item is expected to be a tuple and will be
+            appended as-is (for put-style ops with ``(path, data)``).
+        """
+        spec = _OpSpec(
+            op=op, flush_fn=flush_fn, key_fn=key_fn, item_key=item_key, unpack_put=unpack_put
+        )
+        self._ops[op] = spec
+
+        async def submit(**kwargs: Any) -> Any:
+            return await self._submit(spec, kwargs)
+
+        # Also make it accessible via attribute: batcher.get(item=..., ...)
+        setattr(self, op, submit)
+        return submit
+
+    # -----------------------------------------------------------------
+    # Internal machinery
+    # -----------------------------------------------------------------
+
+    async def _submit(self, spec: _OpSpec, kwargs: dict) -> Any:
+        item = kwargs.pop(spec.item_key)
+        key = f"{spec.op}|{spec.key_fn(**kwargs)}"
+        fut: asyncio.Future = asyncio.get_running_loop().create_future()
+        pending = self._pending.setdefault(key, [])
+        pending.append((item, fut))
+        if key not in self._scheduled:
+            self._scheduled.add(key)
+            asyncio.get_running_loop().call_soon(self._flush, key, spec, kwargs)
+        return await fut
+
+    def _flush(self, key: str, spec: _OpSpec, kwargs: dict) -> None:
+        items = self._pending.pop(key, [])
+        self._scheduled.discard(key)
+        if not items:
+            return
+        collected = [i for i, _ in items]
+        futures = [f for _, f in items]
+        use_h2 = len(collected) >= H2_BATCH_THRESHOLD
+        asyncio.ensure_future(
+            spec.flush_fn(items=collected, futures=futures, use_h2=use_h2, **kwargs)
+        )
+
+
+class _OpSpec:
+    """Internal descriptor for a registered operation."""
+
+    __slots__ = ("op", "flush_fn", "key_fn", "item_key", "unpack_put")
+
+    def __init__(self, *, op: str, flush_fn, key_fn, item_key: str, unpack_put: bool):
+        self.op = op
+        self.flush_fn = flush_fn
+        self.key_fn = key_fn
+        self.item_key = item_key
+        self.unpack_put = unpack_put
+
+
+# ---------------------------------------------------------------------------
+# Generic flush factory + batcher builder
+# ---------------------------------------------------------------------------
+
+
+def _make_flush(
+    batch_fn: Callable[..., Coroutine],
+    *,
+    items_key: str = "items",
+    wrap: Callable | None = None,
+) -> Callable[..., Coroutine]:
+    """Create a flush function for a batch operation.
+
+    Parameters
+    ----------
+    batch_fn:
+        The native Rust batch function to call.
+    items_key:
+        Keyword argument name to pass the items list to *batch_fn*.
+    wrap:
+        Optional callable applied to each result value (e.g. ``bytes``).
+    """
+
+    async def _flush(items: list, futures: list, use_h2: bool, **kw: Any) -> None:
+        try:
+            kw[items_key] = items
+            results = await batch_fn(use_h2=use_h2, **kw) or [None] * len(futures)
+            for fut, val in zip(futures, results):
+                if not fut.done():
+                    fut.set_result(wrap(val) if wrap else val)
+        except Exception as exc:
+            for fut in futures:
+                if not fut.done():
+                    fut.set_exception(exc)
+
+    return _flush
+
+
+def make_batcher(
+    key_fn: Callable[..., str],
+    ops: dict[str, dict[str, Any]],
+) -> MicroBatcher:
+    """Build a :class:`MicroBatcher` from a declarative ops table.
+
+    Parameters
+    ----------
+    key_fn:
+        Callable producing a grouping key from operation kwargs.
+    ops:
+        Mapping of operation name to a dict with keys:
+
+        - ``batch_fn`` (required): the native Rust batch function.
+        - ``items_key`` (default ``"items"``): kwarg name for the items list.
+        - ``returns_results`` (default ``True``): whether the batch fn
+          returns per-item results.
+        - ``wrap`` (default ``None``): optional per-result transform.
+        - ``unpack_put`` (default ``False``): passed to
+          :meth:`MicroBatcher.register`.
+    """
+    b = MicroBatcher()
+    for name, spec in ops.items():
+        flush = _make_flush(
+            spec["batch_fn"],
+            items_key=spec.get("items_key", "items"),
+            wrap=spec.get("wrap"),
+        )
+        b.register(
+            name,
+            flush_fn=flush,
+            key_fn=key_fn,
+            unpack_put=spec.get("unpack_put", False),
+        )
+    return b