pyadata-cli 0.7.0__tar.gz → 0.7.1__tar.gz

{pyadata_cli-0.7.0 → pyadata_cli-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyadata-cli
-Version: 0.7.0
+Version: 0.7.1
 Summary: Streaming CLI for exploring and editing large AnnData .h5ad and .zarr stores
 Keywords: anndata,h5ad,zarr,bioinformatics,single-cell,cli
 Author: Aljes Binkevich

{pyadata_cli-0.7.0 → pyadata_cli-0.7.1}/pyproject.toml

@@ -3,7 +3,7 @@
 # so the distribution is published as `pyadata-cli`. The import package
 # and the command are both still `adata`.
 name = "pyadata-cli"
-version = "0.7.0"
+version = "0.7.1"
 description = "Streaming CLI for exploring and editing large AnnData .h5ad and .zarr stores"
 readme = "README.md"
 requires-python = ">=3.12"

{pyadata_cli-0.7.0 → pyadata_cli-0.7.1}/src/adata/cli.py

@@ -347,6 +347,10 @@ def subset(
         adata subset data.h5ad -o out.h5ad -q "n_counts > 1000 and cluster in A,B"
         adata subset data.h5ad -o out.h5ad --var-query "highly_variable == True"
     """
+    if zarr_format is not None and zarr_format not in (2, 3):
+        console.print("[bold red]Error:[/] --zarr-format must be 2 or 3.")
+        raise typer.Exit(code=1)
+
     if obs is None and var is None and obs_query is None and var_query is None:
         console.print(
             "[bold red]Error:[/] Provide at least one of --obs, --var, "
@@ -433,7 +437,9 @@ def concat(
         1024, "--chunk", "-C", help="Row chunk size while streaming"
     ),
     zarr_format: Optional[int] = typer.Option(
-        None, "--zarr-format", help="Zarr spec version to write (2 or 3)"
+        None,
+        "--zarr-format",
+        help="Zarr spec version to write (defaults to the inputs' when they agree)",
     ),
 ) -> None:
     """
@@ -447,6 +453,10 @@ def concat(
         adata concat *.h5ad -o merged.h5ad --join outer --label sample
         adata concat a.h5ad b.h5ad -o m.h5ad --keys a,b --index-unique - --uns-merge same
     """
+    if zarr_format is not None and zarr_format not in (2, 3):
+        console.print("[bold red]Error:[/] --zarr-format must be 2 or 3.")
+        raise typer.Exit(code=1)
+
     for name, value in (("--merge", merge), ("--uns-merge", uns_merge)):
         if value is not None and value not in MERGE_CHOICES:
             console.print(
@@ -1129,9 +1139,9 @@ def export_sparse(
     Export a sparse matrix (CSR/CSC) to Matrix Market (.mtx) format.
 
     Examples:
-        h5ad export sparse data.h5ad X matrix.mtx
-        h5ad export sparse data.h5ad layers/counts counts.mtx
-        h5ad export sparse data.h5ad X --head 100
+        adata export sparse data.h5ad X -o matrix.mtx
+        adata export sparse data.h5ad layers/counts -o counts.mtx
+        adata export sparse data.h5ad X --head 100
     """
 
     try:
@@ -1179,8 +1189,8 @@ def export_dict(
     Export a dict/group or scalar to JSON format.
 
     Examples:
-        h5ad export dict data.h5ad uns metadata.json
-        h5ad export dict data.h5ad uns/colors colors.json
+        adata export dict data.h5ad uns metadata.json
+        adata export dict data.h5ad uns/colors colors.json
     """
 
     try:
@@ -1219,7 +1229,7 @@ def export_image(
     The array should be 2D (H,W) or 3D (H,W,C) with C in {1,3,4}.
 
     Examples:
-        h5ad export image data.h5ad uns/spatial/image tissue.png
+        adata export image data.h5ad uns/spatial/image -o tissue.png
     """
 
     try:
@@ -1363,8 +1373,8 @@ def import_array(
     Dimensions are validated against existing obs/var.
 
     Examples:
-        h5ad import array data.h5ad obsm/X_pca pca.npy -o output.h5ad
-        h5ad import array data.h5ad X matrix.npy --inplace
+        adata import array data.h5ad obsm/X_pca pca.npy -o output.h5ad
+        adata import array data.h5ad X matrix.npy --inplace
     """
     from adata.commands.import_data import _import_npy
 
@@ -1419,8 +1429,8 @@ def import_sparse(
     Dimensions are validated against existing obs/var.
 
     Examples:
-        h5ad import sparse data.h5ad X matrix.mtx -o output.h5ad
-        h5ad import sparse data.h5ad layers/counts counts.mtx --inplace
+        adata import sparse data.h5ad X matrix.mtx -o output.h5ad
+        adata import sparse data.h5ad layers/counts counts.mtx --inplace
     """
     from adata.commands.import_data import _import_mtx
 
@@ -1473,8 +1483,8 @@ def import_dict(
     Import a JSON file into uns or other dict-like groups.
 
     Examples:
-        h5ad import dict data.h5ad uns/metadata config.json -o output.h5ad
-        h5ad import dict data.h5ad uns settings.json --inplace
+        adata import dict data.h5ad uns/metadata config.json -o output.h5ad
+        adata import dict data.h5ad uns settings.json --inplace
     """
     from adata.commands.import_data import _import_json
 

{pyadata_cli-0.7.0 → pyadata_cli-0.7.1}/src/adata/commands/convert.py

@@ -20,16 +20,10 @@ from adata.conversion import (
     detect_format,
     output_format,
 )
+from adata.util.path import same_path
 from adata.util.staging import staged_outputs
 
 
-def _same_path(left: Path, right: Path) -> bool:
-    try:
-        return left.resolve() == right.resolve()
-    except OSError:
-        return False
-
-
 def convert_store(
     file: Path,
     output: Path,
@@ -56,7 +50,7 @@ def convert_store(
 
     plan = converter.plan(file, output, src_format, dst_format, options)
     for out in plan.outputs:
-        if _same_path(file, out):
+        if same_path(file, out):
             # Writing a Zarr store over its own source empties it before a
             # single element has been read.
             raise ValueError(f"Output path is the input: {out}")

{pyadata_cli-0.7.0 → pyadata_cli-0.7.1}/src/adata/commands/recast.py

@@ -2,13 +2,14 @@
 
 Writes a whole new store rather than editing one in place, for the same
 reason `subset` does: a conversion that fails half way leaves the original
-untouched, and `--inplace` becomes an atomic swap of a finished file rather
-than a partial edit of a live one.
+untouched. The new store is written beside its destination and renamed into
+place only once complete (see `adata.util.staging`), so `--inplace` replaces a
+finished file rather than editing a live one, and the original is deleted only
+after its successor is in place.
 """
 
 from __future__ import annotations
 
-import shutil
 from pathlib import Path
 from typing import Any, List, Optional
 
@@ -25,15 +26,16 @@ from adata.core.recast import (
 from adata.elements import spec
 from adata.elements.write import ensure_anndata_skeleton
 from adata.storage import copy_tree, detect_backend, is_group, open_store
-
-#: What `--all` means. The matrices an AnnData object is built from, not
-#: every 2-D array in the file: obsm/varm hold embeddings, whose dtype is
-#: rarely what anyone is trying to shrink. Those still convert by path.
-ALL_PREFIXES = ("X", "layers", "raw/X")
-
+from adata.util.path import same_path
+from adata.util.staging import staged_outputs
 
 def discover_matrices(root: Any) -> List[str]:
-    """Entry paths `--all` resolves to, in a stable order."""
+    """Entry paths `--all` resolves to, in a stable order.
+
+    The matrices an AnnData object is built from, not every 2-D array in the
+    file: obsm/varm hold embeddings, whose dtype is rarely what anyone is
+    trying to shrink. Those still convert by path.
+    """
     found: List[str] = []
     if "X" in root:
         found.append("X")
@@ -44,14 +46,6 @@ def discover_matrices(root: Any) -> List[str]:
     return found
 
 
-def _same_path(left: Path, right: Path) -> bool:
-    """Do these name the same store, through symlinks and `..` alike?"""
-    try:
-        return left.resolve() == right.resolve()
-    except OSError:  # pragma: no cover - unresolvable path
-        return left.absolute() == right.absolute()
-
-
 def _resolve(root: Any, path: str) -> Any:
     obj = root
     for part in path.split("/"):
@@ -96,7 +90,7 @@ def recast_store(
         else None
     )
 
-    if output is not None and not inplace and _same_path(file, output):
+    if output is not None and not inplace and same_path(file, output):
         # Opening the destination "w" clears it while the source is still
         # being read from it. HDF5 refuses; Zarr does not, and quietly
         # produced an empty store where the data used to be.
@@ -105,69 +99,54 @@ def recast_store(
             "it, which writes to a temporary file first."
         )
 
-    if inplace:
-        backend = detect_backend(file)
-        if backend == "zarr":
-            base = file.stem if file.suffix else file.name
-            dst_path = file.with_name(f"{base}.recast-tmp.zarr")
-        else:
-            dst_path = file.with_name(f"{file.name}.recast-tmp")
-        if dst_path.exists():
-            raise FileExistsError(f"Temporary path already exists: {dst_path}")
-    else:
-        dst_path = output
+    dst_path = file if inplace else Path(output)
 
     if zarr_format is None and detect_backend(file) == "zarr":
         with open_store(file, "r") as probe:
             zarr_format = probe.zarr_format
 
-    with open_store(file, "r") as src_store:
-        src = src_store.root
-        targets = discover_matrices(src) if convert_all else list(entries or [])
-        if not targets:
-            raise ValueError(
-                "No matrices selected. Name one (e.g. `X`) or pass --all."
-            )
-        # Every check first, before the destination exists. A refusal must
-        # not leave behind a store holding a copy of obs and var and nothing
-        # else -- the caller cannot tell that from a finished conversion.
-        plans = {
-            path: plan_conversion(
-                _resolve(src, path),
-                path,
-                dtype=data_dtype,
-                index_dtype=index_dtype,
-                layout=layout,
-                chunk=chunk,
-                force=force,
-                console=console,
+    # The source is opened inside the staging block, so it is closed before
+    # `--inplace` renames it aside.
+    with staged_outputs([dst_path]) as (temp,):
+        with open_store(file, "r") as src_store:
+            src = src_store.root
+            targets = discover_matrices(src) if convert_all else list(entries or [])
+            if not targets:
+                raise ValueError(
+                    "No matrices selected. Name one (e.g. `X`) or pass --all."
+                )
+            # Every check first, before the destination exists. A refusal must
+            # not leave behind a store holding a copy of obs and var and nothing
+            # else -- the caller cannot tell that from a finished conversion.
+            plans = {
+                path: plan_conversion(
+                    _resolve(src, path),
+                    path,
+                    dtype=data_dtype,
+                    index_dtype=index_dtype,
+                    layout=layout,
+                    chunk=chunk,
+                    force=force,
+                    console=console,
+                )
+                for path in targets
+            }
+
+            console.print(
+                f"[cyan]Converting {len(targets)} matrix/matrices:[/] "
+                + ", ".join(targets)
             )
-            for path in targets
-        }
-
-        console.print(
-            f"[cyan]Converting {len(targets)} matrix/matrices:[/] "
-            + ", ".join(targets)
-        )
 
-        with open_store(dst_path, "w", zarr_format=zarr_format) as dst_store:
-            dst = dst_store.root
-            _write(
-                src, dst, plans,
-                chunk=chunk, chunk_rows=chunk_rows, in_memory=in_memory,
-                console=console,
-            )
-            ensure_anndata_skeleton(dst)
+            with open_store(temp, "w", zarr_format=zarr_format) as dst_store:
+                dst = dst_store.root
+                _write(
+                    src, dst, plans,
+                    chunk=chunk, chunk_rows=chunk_rows, in_memory=in_memory,
+                    console=console,
+                )
+                ensure_anndata_skeleton(dst)
 
     if inplace:
-        if file.is_dir():
-            shutil.rmtree(file)
-        elif file.exists():
-            file.unlink()
-        if dst_path.is_dir():
-            shutil.move(str(dst_path), str(file))
-        else:
-            dst_path.replace(file)
         console.print(f"[green]Converted[/] {file}")
     else:
         console.print(f"[green]Wrote[/] {dst_path}")

{pyadata_cli-0.7.0 → pyadata_cli-0.7.1}/src/adata/commands/split.py

@@ -4,6 +4,11 @@ Requested in issue #2, modelled on cellgeni/scraft's `split_h5ad` but
 streaming: the source is never loaded into memory, only the column being split
 on is read, and each output is produced by the same subset machinery used by
 `adata subset`, fanned out so every matrix is read once for all groups.
+
+Every output is written beside its destination and renamed into place only
+once all of them are complete, so a split that fails leaves no partial stores
+(and existing outputs as they were). The manifest is written last, so it
+exists only when everything it lists does.
 """
 
 from __future__ import annotations
@@ -19,6 +24,8 @@ from adata.core.select import group_indices
 from adata.core.subset import split_h5ad
 from adata.storage import detect_backend, open_store
 from adata.util.names import unique_names
+from adata.util.path import same_path
+from adata.util.staging import staged_outputs
 
 
 def split_store(
@@ -78,6 +85,13 @@ def split_store(
     for label, out_path, count in planned:
         console.print(f"  {label!r} -> {out_path} ({count} {axis})")
 
+    for _, out_path, _ in planned:
+        if same_path(file, out_path):
+            raise ValueError(
+                f"Output path is the input: {out_path}. Choose another "
+                "--output-dir."
+            )
+
     if dry_run:
         console.print("[yellow]Dry run: nothing written.[/]")
         return planned
@@ -86,20 +100,21 @@ def split_store(
 
     # One call for every group, so each matrix is read once rather than once
     # per group.
-    split_h5ad(
-        file,
-        [
-            (
-                out_path,
-                np.sort(groups[label]) if axis == "obs" else None,
-                np.sort(groups[label]) if axis == "var" else None,
-            )
-            for label, out_path, _ in planned
-        ],
-        chunk_rows=chunk_rows,
-        console=console,
-        zarr_format=zarr_format,
-    )
+    with staged_outputs([out_path for _, out_path, _ in planned]) as temps:
+        split_h5ad(
+            file,
+            [
+                (
+                    temp,
+                    np.sort(groups[label]) if axis == "obs" else None,
+                    np.sort(groups[label]) if axis == "var" else None,
+                )
+                for (label, _, _), temp in zip(planned, temps)
+            ],
+            chunk_rows=chunk_rows,
+            console=console,
+            zarr_format=zarr_format,
+        )
 
     if manifest:
         _write_manifest(file, output_dir, column, planned, console)

{pyadata_cli-0.7.0 → pyadata_cli-0.7.1}/src/adata/core/concat.py

@@ -43,9 +43,11 @@ from adata.storage import (
     copy_tree,
     create_dataset,
     is_dataset,
+    Store,
     is_group,
     open_store,
 )
+from adata.util.staging import staged_outputs
 
 MERGE_STRATEGIES = ("same", "unique", "first", "only")
 #: What the CLI accepts. "drop" is the default and maps to no merge at all.
@@ -827,6 +829,17 @@ def _hashable(value: Any) -> Any:
     return value
 
 
+def _inputs_zarr_format(stores: Sequence[Store]) -> Optional[int]:
+    """The Zarr version the inputs agree on, or None to take the default.
+
+    A Zarr output follows its inputs, as every other command's follows its
+    source, so v2 inputs are not silently upgraded. h5ad inputs have no
+    version and do not count; Zarr inputs of both versions get the default.
+    """
+    versions = {s.zarr_format for s in stores} - {None}
+    return versions.pop() if len(versions) == 1 else None
+
+
 def concat_on_disk(
     files: Sequence[Path],
     output: Path,
@@ -906,7 +919,14 @@ def concat_on_disk(
         # half-written store behind.
         check_matrix_encodings(roots, console)
 
-        with open_store(output, "w", zarr_format=zarr_format) as dst_store:
+        if zarr_format is None:
+            zarr_format = _inputs_zarr_format(stores)
+
+        # Written beside the output and renamed into place once complete, so
+        # a failure part way leaves nothing that reads as a finished store.
+        with staged_outputs([output]) as (temp,), open_store(
+            temp, "w", zarr_format=zarr_format
+        ) as dst_store:
             dst = dst_store.root
             _write_obs(
                 dst, roots, target_obs, obs_counts, join, label, input_keys, console

{pyadata_cli-0.7.0 → pyadata_cli-0.7.1}/src/adata/core/subset.py

@@ -5,7 +5,6 @@ from __future__ import annotations
 from contextlib import ExitStack
 from dataclasses import dataclass
 from pathlib import Path
-import shutil
 from typing import Optional, Set, Tuple, List, Dict, Any
 
 import numpy as np
@@ -43,6 +42,8 @@ from adata.storage import (
     with_compression,
     zarr_format_of,
 )
+from adata.util.path import same_path
+from adata.util.staging import staged_outputs
 
 
 def _target_backend(dst_group: Any) -> str:
@@ -952,18 +953,15 @@ def subset_h5ad(
     if not inplace and output is None:
         raise ValueError("Output file is required unless --inplace is specified.")
 
-    if inplace:
-        src_backend = detect_backend(file)
-        if src_backend == "zarr":
-            base_name = file.stem if file.suffix else file.name
-            tmp_path = file.with_name(f"{base_name}.subset-tmp.zarr")
-        else:
-            tmp_path = file.with_name(f"{file.name}.subset-tmp")
-        if tmp_path.exists():
-            raise FileExistsError(f"Temporary path already exists: {tmp_path}")
-        dst_path = tmp_path
-    else:
-        dst_path = output
+    if not inplace and same_path(file, output):
+        # Opening the output "w" would empty a Zarr source before a single
+        # element had been read from it.
+        raise ValueError(
+            f"Output path is the input: {output}. Use --inplace to replace "
+            "it, which writes to a temporary file first."
+        )
+
+    dst_path = file if inplace else Path(output)
 
     if zarr_format is None and detect_backend(file) == "zarr":
         with open_store(file, "r") as probe:
@@ -975,12 +973,17 @@ def subset_h5ad(
     status = console.status("[magenta]Opening files...[/]")
     status.start()
     try:
-        with open_store(file, "r") as src_store, open_store(
-            dst_path, "w", zarr_format=zarr_format
-        ) as dst_store:
+        # The output is written beside its destination and renamed into place
+        # only once complete, so a failure leaves any existing output (or,
+        # with --inplace, the source) as it was. The source is opened inside
+        # the staging block, so it is closed before it is renamed aside.
+        with staged_outputs([dst_path]) as (temp,), open_store(
+            file, "r"
+        ) as src_store:
             src = src_store.root
-            dst = dst_store.root
 
+            # The selection is resolved before the output exists: a query
+            # that fails must not leave an empty store behind.
             obs_idx = (
                 obs_indices
                 if obs_indices is not None
@@ -1000,26 +1003,16 @@ def subset_h5ad(
 
             status.stop()
 
-            _write_targets(
-                src,
-                [Target(dst, obs_idx, var_idx, var_keep)],
-                chunk_rows=chunk_rows,
-                console=console,
-            )
+            with open_store(temp, "w", zarr_format=zarr_format) as dst_store:
+                _write_targets(
+                    src,
+                    [Target(dst_store.root, obs_idx, var_idx, var_keep)],
+                    chunk_rows=chunk_rows,
+                    console=console,
+                )
     finally:
         status.stop()
 
-    if inplace:
-        if file.exists():
-            if file.is_dir():
-                shutil.rmtree(file)
-            else:
-                file.unlink()
-        if dst_path.is_dir():
-            shutil.move(str(dst_path), str(file))
-        else:
-            dst_path.replace(file)
-
 
 def _open_output_limit() -> int:
     """How many output stores `split_h5ad` may hold open at once.

pyadata_cli-0.7.1/src/adata/util/path.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def norm_path(path: str) -> str:
+    """Normalize object paths used inside h5ad/zarr stores."""
+    value = path.strip()
+    if not value:
+        raise ValueError("Object path must be non-empty.")
+    return value.lstrip("/")
+
+
+def same_path(left: Path, right: Path) -> bool:
+    """Do these name the same store, through symlinks and `..` alike?"""
+    try:
+        return Path(left).resolve() == Path(right).resolve()
+    except OSError:  # pragma: no cover - unresolvable path
+        return Path(left).absolute() == Path(right).absolute()

pyadata_cli-0.7.1/src/adata/util/staging.py

@@ -0,0 +1,99 @@
+"""Write outputs beside their destination, and move them into place at the end.
+
+A command that fails half way must not leave a half-written store where the
+output should be: the next command to open it would read whatever got written
+as if it were the whole thing. Writing to a temporary sibling and renaming it
+only on success means the output either appears whole or not at all.
+
+An existing output is renamed aside (`out.adata-old.zarr`) before its
+successor is renamed in, and deleted only once every output is in place. If a
+rename fails part way, the outputs already swapped are put back. A run killed
+between the two renames leaves the old data under the `adata-old` name, never
+nowhere, and the next run refuses to start until that has been dealt with.
+"""
+
+from __future__ import annotations
+
+import shutil
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterator, List, Sequence, Tuple
+
+
+def _sibling(path: Path, tag: str) -> Path:
+    """`out.zarr` -> `out.<tag>.zarr`, keeping the suffix that picks the backend."""
+    return path.with_name(f"{path.stem}.{tag}{path.suffix}")
+
+
+def _temp_for(path: Path) -> Path:
+    temp = _sibling(path, "adata-tmp")
+    if path.is_dir() and path.suffix != ".zarr":
+        # A Zarr store named without the suffix. A temporary named the same
+        # way would not exist yet, and so be opened as HDF5.
+        temp = temp.with_name(f"{temp.name}.zarr")
+    return temp
+
+
+def _remove(path: Path) -> None:
+    if path.is_dir() and not path.is_symlink():
+        shutil.rmtree(path)
+    elif path.exists() or path.is_symlink():
+        path.unlink()
+
+
+def _exists(path: Path) -> bool:
+    return path.exists() or path.is_symlink()
+
+
+@contextmanager
+def staged_outputs(outputs: Sequence[Path]) -> Iterator[List[Path]]:
+    """Yield temporary paths to write `outputs` to; move them into place after.
+
+    On success each output is swapped in: an existing one is set aside first
+    and deleted only once every new output is in place. On failure the
+    temporary paths are deleted and the outputs are left as they were.
+    """
+    outputs = [Path(p) for p in outputs]
+    temps = [_temp_for(p) for p in outputs]
+    backups = [_sibling(p, "adata-old") for p in outputs]
+    for leftover in temps + backups:
+        if _exists(leftover):
+            raise FileExistsError(
+                f"'{leftover}' already exists, probably left by an interrupted "
+                "run. Check what it holds, remove it, and try again."
+            )
+
+    try:
+        yield temps
+    except BaseException:
+        for temp in temps:
+            _remove(temp)
+        raise
+
+    swapped: List[Tuple[Path, Path, bool]] = []
+    try:
+        for output, temp, backup in zip(outputs, temps, backups):
+            had_output = _exists(output)
+            if had_output:
+                output.rename(backup)
+            try:
+                temp.rename(output)
+            except BaseException:
+                if had_output:
+                    backup.rename(output)
+                raise
+            swapped.append((output, backup, had_output))
+    except BaseException:
+        # Put back what was already swapped, newest first, and drop the
+        # temporaries that never made it.
+        for output, backup, had_output in reversed(swapped):
+            _remove(output)
+            if had_output:
+                backup.rename(output)
+        for temp in temps:
+            _remove(temp)
+        raise
+
+    for _, backup, had_output in swapped:
+        if had_output:
+            _remove(backup)

pyadata_cli-0.7.0/src/adata/util/path.py

@@ -1,9 +0,0 @@
-from __future__ import annotations
-
-
-def norm_path(path: str) -> str:
-    """Normalize object paths used inside h5ad/zarr stores."""
-    value = path.strip()
-    if not value:
-        raise ValueError("Object path must be non-empty.")
-    return value.lstrip("/")

pyadata_cli-0.7.0/src/adata/util/staging.py

@@ -1,63 +0,0 @@
-"""Write outputs beside their destination, and move them into place at the end.
-
-A conversion that fails half way must not leave a half-written store where
-the output should be: the next command to open it would read whatever got
-written as if it were the whole thing. Writing to a temporary sibling and
-renaming it only on success means the output either appears whole or not at
-all, and an existing output is replaced only once its successor is complete.
-"""
-
-from __future__ import annotations
-
-import shutil
-from contextlib import contextmanager
-from pathlib import Path
-from typing import Iterator, List, Sequence
-
-
-def _sibling(path: Path, tag: str) -> Path:
-    """`out.zarr` -> `out.<tag>.zarr`, keeping the suffix that picks the backend."""
-    return path.with_name(f"{path.stem}.{tag}{path.suffix}")
-
-
-def _remove(path: Path) -> None:
-    if path.is_dir() and not path.is_symlink():
-        shutil.rmtree(path)
-    elif path.exists() or path.is_symlink():
-        path.unlink()
-
-
-@contextmanager
-def staged_outputs(outputs: Sequence[Path]) -> Iterator[List[Path]]:
-    """Yield temporary paths to write `outputs` to; move them into place after.
-
-    On success each output is swapped in: an existing one is set aside first
-    and deleted only once every new output is in place. On failure the
-    temporary paths are deleted and the outputs are left as they were.
-    """
-    outputs = [Path(p) for p in outputs]
-    temps = [_sibling(p, "adata-tmp") for p in outputs]
-    for temp in temps:
-        if temp.exists():
-            raise FileExistsError(
-                f"'{temp}' already exists, probably left by an interrupted run. "
-                "Remove it and try again."
-            )
-
-    try:
-        yield temps
-    except BaseException:
-        for temp in temps:
-            _remove(temp)
-        raise
-
-    backups = []
-    for output, temp in zip(outputs, temps):
-        if output.exists():
-            backup = _sibling(output, "adata-old")
-            _remove(backup)
-            output.rename(backup)
-            backups.append(backup)
-        temp.rename(output)
-    for backup in backups:
-        _remove(backup)