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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyadata-cli
-Version: 0.6.1
+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
@@ -48,7 +48,7 @@ A command-line tool for exploring huge AnnData stores (`.h5ad` and `.zarr`) with
 - Auto-detects `.h5ad` files vs `.zarr` directories
 - Chunked processing for dense and sparse matrices (CSR/CSC)
 - Reads every AnnData on-disk layout, from 0.7.x through the current spec, and always writes the current one
-- Converts between HDF5 and Zarr (v2 and v3) in either direction
+- Converts between HDF5 and Zarr (v2 and v3) in either direction with `adata convert`, and to and from 10x Genomics HDF5 matrices
 - Rich terminal output with progress indicators, kept on stderr so results pipe cleanly
 
 **Documentation: [cellgeni.github.io/adata-cli](https://cellgeni.github.io/adata-cli/)**
@@ -96,7 +96,8 @@ Run help at any level (e.g. `adata --help`, `adata export --help`).
 - `subset` – stream and write a filtered copy, selected by obs/var name lists (`--obs`/`--var`) or by expression (`--obs-query`/`--var-query`).
 - `split` – write one store per distinct value of an annotation column, with a CSV manifest.
 - `concat` – concatenate stores along the obs axis, with `--join inner|outer` and merge strategies for var and uns.
-- `convert` – change a matrix's dtype, layout (CSR/CSC/dense) or density, streaming; refuses a lossy cast or a large size increase unless forced.
+- `convert` – change a store's format: h5ad ↔ Zarr v2/v3, and 10x Genomics HDF5 (Cell Ranger's `*_feature_bc_matrix.h5`) in and out, streaming, with the output written beside its destination and moved into place only once complete.
+- `recast` – change a matrix's dtype, layout (CSR/CSC/dense) or density, streaming; refuses a lossy cast or a large size increase unless forced. Called `convert` until 0.7.0.
 - `export` – extract data from a store; subcommands: `dataframe` (any dataframe group to CSV), `array` (dense to `.npy`), `sparse` (CSR/CSC to `.mtx`), `dict` (JSON), `image` (PNG). Results go to stdout when no `--output` is given.
 - `import` – write new data into a store at any path; subcommands: `dataframe` (CSV), `array` (`.npy`), `sparse` (`.mtx`), `dict` (JSON), `image` (PNG/JPEG/TIFF).
 
@@ -122,16 +123,25 @@ adata concat per_sample/*.h5ad -o merged.h5ad --join outer --label sample
 ### Shrinking a store, and making encodings agree
 
 ```bash
-adata convert data.h5ad X --inplace --dtype float32
-adata convert data.h5ad --all -o small.h5ad --dtype float32 --indices-dtype int32
-adata convert data.h5ad X -o csc.h5ad --layout csc
+adata recast data.h5ad X --inplace --dtype float32
+adata recast data.h5ad --all -o small.h5ad --dtype float32 --indices-dtype int32
+adata recast data.h5ad X -o csc.h5ad --layout csc
 ```
 
-Counts written as float64 halve with no loss — and `convert` proves that
+Counts written as float64 halve with no loss — and `recast` proves that
 before it writes, by casting every value and casting it back. `concat`
 refuses inputs whose matrices disagree about CSR versus CSC; `--layout` is
 how you make them agree.
 
+### Changing format
+
+```bash
+adata convert data.h5ad -o data.zarr
+adata convert data.zarr -o data.h5ad --compression gzip
+adata convert filtered_feature_bc_matrix.h5 -o counts.h5ad --feature-type "Gene Expression"
+adata convert counts.h5ad -o for_cellbender.h5 --layer counts
+```
+
 ## Documentation
 
 - [Get started](docs/GET_STARTED.md) — a short tutorial

{pyadata_cli-0.6.1 → pyadata_cli-0.7.1}/README.md

@@ -8,7 +8,7 @@ A command-line tool for exploring huge AnnData stores (`.h5ad` and `.zarr`) with
 - Auto-detects `.h5ad` files vs `.zarr` directories
 - Chunked processing for dense and sparse matrices (CSR/CSC)
 - Reads every AnnData on-disk layout, from 0.7.x through the current spec, and always writes the current one
-- Converts between HDF5 and Zarr (v2 and v3) in either direction
+- Converts between HDF5 and Zarr (v2 and v3) in either direction with `adata convert`, and to and from 10x Genomics HDF5 matrices
 - Rich terminal output with progress indicators, kept on stderr so results pipe cleanly
 
 **Documentation: [cellgeni.github.io/adata-cli](https://cellgeni.github.io/adata-cli/)**
@@ -56,7 +56,8 @@ Run help at any level (e.g. `adata --help`, `adata export --help`).
 - `subset` – stream and write a filtered copy, selected by obs/var name lists (`--obs`/`--var`) or by expression (`--obs-query`/`--var-query`).
 - `split` – write one store per distinct value of an annotation column, with a CSV manifest.
 - `concat` – concatenate stores along the obs axis, with `--join inner|outer` and merge strategies for var and uns.
-- `convert` – change a matrix's dtype, layout (CSR/CSC/dense) or density, streaming; refuses a lossy cast or a large size increase unless forced.
+- `convert` – change a store's format: h5ad ↔ Zarr v2/v3, and 10x Genomics HDF5 (Cell Ranger's `*_feature_bc_matrix.h5`) in and out, streaming, with the output written beside its destination and moved into place only once complete.
+- `recast` – change a matrix's dtype, layout (CSR/CSC/dense) or density, streaming; refuses a lossy cast or a large size increase unless forced. Called `convert` until 0.7.0.
 - `export` – extract data from a store; subcommands: `dataframe` (any dataframe group to CSV), `array` (dense to `.npy`), `sparse` (CSR/CSC to `.mtx`), `dict` (JSON), `image` (PNG). Results go to stdout when no `--output` is given.
 - `import` – write new data into a store at any path; subcommands: `dataframe` (CSV), `array` (`.npy`), `sparse` (`.mtx`), `dict` (JSON), `image` (PNG/JPEG/TIFF).
 
@@ -82,16 +83,25 @@ adata concat per_sample/*.h5ad -o merged.h5ad --join outer --label sample
 ### Shrinking a store, and making encodings agree
 
 ```bash
-adata convert data.h5ad X --inplace --dtype float32
-adata convert data.h5ad --all -o small.h5ad --dtype float32 --indices-dtype int32
-adata convert data.h5ad X -o csc.h5ad --layout csc
+adata recast data.h5ad X --inplace --dtype float32
+adata recast data.h5ad --all -o small.h5ad --dtype float32 --indices-dtype int32
+adata recast data.h5ad X -o csc.h5ad --layout csc
 ```
 
-Counts written as float64 halve with no loss — and `convert` proves that
+Counts written as float64 halve with no loss — and `recast` proves that
 before it writes, by casting every value and casting it back. `concat`
 refuses inputs whose matrices disagree about CSR versus CSC; `--layout` is
 how you make them agree.
 
+### Changing format
+
+```bash
+adata convert data.h5ad -o data.zarr
+adata convert data.zarr -o data.h5ad --compression gzip
+adata convert filtered_feature_bc_matrix.h5 -o counts.h5ad --feature-type "Gene Expression"
+adata convert counts.h5ad -o for_cellbender.h5 --layer counts
+```
+
 ## Documentation
 
 - [Get started](docs/GET_STARTED.md) — a short tutorial

{pyadata_cli-0.6.1 → 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.6.1"
+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.6.1 → pyadata_cli-0.7.1}/src/adata/cli.py

@@ -6,11 +6,13 @@ from typing import Optional, Sequence, List
 from rich.console import Console
 import typer
 
-from adata.core.convert import LAYOUTS
+from adata.conversion import FORMATS, Options
+from adata.core.recast import LAYOUTS
 from adata.commands import (
     MERGE_CHOICES,
     concat_stores,
     convert_store,
+    recast_store,
     create_store,
     split_store,
     list_store,
@@ -26,7 +28,7 @@ from adata.commands import export_image as export_image_cmd
 
 app = typer.Typer(
     help="Streaming CLI for huge AnnData .h5ad and .zarr stores "
-    "(view, ls, create, subset, split, concat, convert, export, import)."
+    "(view, ls, create, subset, split, concat, convert, recast, export, import)."
 )
 # Use stderr for status/progress to keep stdout clean for data output
 # force_terminal=True ensures Rich output is visible even in non-TTY environments
@@ -345,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, "
@@ -431,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:
     """
@@ -445,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(
@@ -481,8 +493,285 @@ def concat(
 # ============================================================================
 # CONVERT command
 # ============================================================================
-@app.command("convert")
+#: The flags `recast` has and format conversion does not. Until 1.0.0, any of
+#: them on `convert` means the old meaning of the command, and it forwards.
+_RECAST_FLAGS = {
+    "inplace": "--inplace",
+    "convert_all": "--all",
+    "dtype": "--dtype",
+    "indices_dtype": "--indices-dtype",
+    "layout": "--layout",
+}
+
+#: Flags that only shape a recast; given without one of the above they have
+#: nothing to act on.
+_RECAST_ONLY_FLAGS = {"in_memory": "--in-memory", "chunk_rows": "--chunk"}
+
+#: Format-conversion flags, by parameter name, as `Options.given` spells them.
+_CONVERT_FLAGS = {
+    "zarr_format": "--zarr-format",
+    "compression": "--compression",
+    "force": "--force",
+    "overwrite": "--overwrite",
+    "genome": "--genome",
+    "var_names": "--var-names",
+    "make_unique": "--make-unique",
+    "feature_type": "--feature-type",
+    "split_feature_types": "--split-feature-types",
+    "layer": "--layer",
+    "gene_ids_column": "--gene-ids-column",
+    "gene_names_column": "--gene-names-column",
+    "feature_types_column": "--feature-types-column",
+}
+
+#: Flags that only make sense for format conversion; with recast's flags,
+#: they mean two commands' worth of request at once.
+_FORMAT_ONLY_FLAGS = {
+    "from_format": "--from",
+    "to_format": "--to",
+    **{
+        name: flag
+        for name, flag in _CONVERT_FLAGS.items()
+        if flag not in ("--force", "--zarr-format")
+    },
+}
+
+
+def _given(ctx: typer.Context, flags: dict) -> List[str]:
+    """The flags among `flags` that were actually typed, not defaulted."""
+    from click.core import ParameterSource
+
+    return [
+        flag
+        for name, flag in flags.items()
+        if ctx.get_parameter_source(name) not in (None, ParameterSource.DEFAULT)
+    ]
+
+
+@app.command("convert", context_settings={"allow_extra_args": True})
 def convert(
+    ctx: typer.Context,
+    file: Path = typer.Argument(
+        ...,
+        help="Input file or store",
+        exists=True,
+        readable=True,
+        dir_okay=True,
+        file_okay=True,
+    ),
+    output: Optional[Path] = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Output path; its extension picks the format (.h5ad, .zarr, .h5)",
+        dir_okay=True,
+        file_okay=True,
+    ),
+    from_format: Optional[str] = typer.Option(
+        None,
+        "--from",
+        help=f"Input format, if it cannot be detected: {', '.join(FORMATS)}",
+    ),
+    to_format: Optional[str] = typer.Option(
+        None,
+        "--to",
+        help=f"Output format, if the extension does not say: {', '.join(FORMATS)}",
+    ),
+    zarr_format: Optional[int] = typer.Option(
+        None,
+        "--zarr-format",
+        help="Zarr spec version to write (defaults to the source store's, else 3)",
+    ),
+    compression: Optional[str] = typer.Option(
+        None,
+        "--compression",
+        help="none, gzip or lzf for h5ad; none, gzip, zstd or blosc for zarr "
+        "(defaults to the source's)",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Convert despite a lossy or inflating result",
+    ),
+    overwrite: bool = typer.Option(
+        False,
+        "--overwrite",
+        help="Replace an existing output",
+    ),
+    genome: Optional[str] = typer.Option(
+        None,
+        "--genome",
+        help="10x input: the genome to keep (picks the group in a Cell Ranger 2 file)",
+    ),
+    var_names: str = typer.Option(
+        "gene_symbols",
+        "--var-names",
+        help="10x input: name features by gene_symbols or gene_ids",
+    ),
+    make_unique: bool = typer.Option(
+        False,
+        "--make-unique",
+        help="10x input: suffix repeated var names, as var_names_make_unique does",
+    ),
+    feature_type: Optional[str] = typer.Option(
+        None,
+        "--feature-type",
+        help="10x input: keep only this feature type, e.g. 'Gene Expression'",
+    ),
+    split_feature_types: bool = typer.Option(
+        False,
+        "--split-feature-types",
+        help="10x input: write one output per feature type, OUT.<type>.h5ad",
+    ),
+    layer: Optional[str] = typer.Option(
+        None,
+        "--layer",
+        help="10x output: the matrix to write: X (default), raw/X, or a layer",
+    ),
+    gene_ids_column: Optional[str] = typer.Option(
+        None,
+        "--gene-ids-column",
+        help="10x output: var column holding gene ids (default gene_ids)",
+    ),
+    gene_names_column: Optional[str] = typer.Option(
+        None,
+        "--gene-names-column",
+        help="10x output: var column holding gene names (default: var_names)",
+    ),
+    feature_types_column: Optional[str] = typer.Option(
+        None,
+        "--feature-types-column",
+        help="10x output: var column holding feature types (default feature_types)",
+    ),
+    # Deprecated: recast's flags, so `convert` keeps working as it did until
+    # 1.0.0. Hidden from --help; the old matrix paths arrive in ctx.args.
+    inplace: bool = typer.Option(False, "--inplace", hidden=True),
+    convert_all: bool = typer.Option(False, "--all", hidden=True),
+    dtype: Optional[str] = typer.Option(None, "--dtype", hidden=True),
+    indices_dtype: Optional[str] = typer.Option(None, "--indices-dtype", hidden=True),
+    layout: Optional[str] = typer.Option(None, "--layout", hidden=True),
+    in_memory: bool = typer.Option(False, "--in-memory", hidden=True),
+    chunk_rows: int = typer.Option(1024, "--chunk", "-C", hidden=True),
+) -> None:
+    """
+    Convert a store to another format.
+
+    The output's extension picks the format: .h5ad, .zarr, or .h5 for a 10x
+    Genomics matrix (Cell Ranger's *_feature_bc_matrix.h5). Between h5ad and
+    zarr every element is copied, streamed, keeping the source's chunking and
+    compression where the target can express them. A 10x matrix is read as
+    scanpy.read_10x_h5(gex_only=False) reads it, keeping integer counts, and
+    written as Cell Ranger writes it.
+
+    Nothing is written until every check has passed, and the output is moved
+    into place only once complete: a failed conversion leaves nothing
+    behind. An existing output is refused unless --overwrite is given.
+
+    To change a matrix's dtype, layout or density, use `recast`. Until 1.0.0,
+    `convert` given recast's flags still forwards to it, with a warning.
+
+    Examples:
+        adata convert data.h5ad -o data.zarr
+        adata convert data.zarr -o data.h5ad --compression gzip
+        adata convert data.zarr -o v3.zarr --zarr-format 3
+        adata convert filtered_feature_bc_matrix.h5 -o counts.h5ad
+        adata convert raw_feature_bc_matrix.h5 -o rna.h5ad --feature-type "Gene Expression"
+        adata convert counts.h5ad -o for_cellbender.h5 --layer counts
+    """
+    entries = list(ctx.args)
+    recast_flags = _given(ctx, _RECAST_FLAGS)
+
+    try:
+        if recast_flags:
+            mixed = _given(ctx, _FORMAT_ONLY_FLAGS)
+            if mixed:
+                raise ValueError(
+                    f"{', '.join(mixed)} cannot be combined with "
+                    f"{', '.join(recast_flags)}: the first change a store's "
+                    "format, the second its matrices. Run `adata recast` for "
+                    "the matrices."
+                )
+            console.print(
+                "[yellow]Warning:[/] 'convert' with "
+                f"{', '.join(recast_flags)} is deprecated and will be removed "
+                "in 1.0.0; use 'recast' instead.",
+            )
+            if not inplace and output is None:
+                raise ValueError("Output file is required. Use --output/-o or --inplace.")
+            if layout is not None and layout not in LAYOUTS:
+                raise ValueError(f"--layout must be one of: {', '.join(LAYOUTS)}.")
+            if zarr_format is not None and zarr_format not in (2, 3):
+                raise ValueError("--zarr-format must be 2 or 3.")
+            recast_store(
+                file=file,
+                entries=entries or None,
+                output=output,
+                console=console,
+                dtype=dtype,
+                indices_dtype=indices_dtype,
+                layout=layout,
+                convert_all=convert_all,
+                inplace=inplace,
+                chunk_rows=chunk_rows,
+                in_memory=in_memory,
+                force=force,
+                zarr_format=zarr_format,
+            )
+            return
+
+        if entries:
+            hint = (
+                f" To write it, pass -o {entries[0]}."
+                if output is None and len(entries) == 1
+                else ""
+            )
+            raise ValueError(
+                f"Unexpected argument{'s' if len(entries) > 1 else ''}: "
+                f"{' '.join(entries)}. convert takes one input.{hint} To change "
+                "a matrix's dtype or layout, use `adata recast`."
+            )
+        stray = _given(ctx, _RECAST_ONLY_FLAGS)
+        if stray:
+            raise ValueError(
+                f"{', '.join(stray)} {'applies' if len(stray) == 1 else 'apply'} "
+                "to `adata recast`, not to format conversion."
+            )
+        if output is None:
+            raise ValueError("Output path is required: pass -o/--output.")
+
+        convert_store(
+            file,
+            output,
+            console,
+            src_format=from_format,
+            dst_format=to_format,
+            options=Options(
+                given=frozenset(_given(ctx, _CONVERT_FLAGS)),
+                zarr_format=zarr_format,
+                compression=compression,
+                force=force,
+                overwrite=overwrite,
+                genome=genome,
+                var_names=var_names,
+                make_unique=make_unique,
+                feature_type=feature_type,
+                split_feature_types=split_feature_types,
+                layer=layer,
+                gene_ids_column=gene_ids_column,
+                gene_names_column=gene_names_column,
+                feature_types_column=feature_types_column,
+            ),
+        )
+    except Exception as e:
+        console.print(f"[bold red]Error:[/] {e}")
+        raise typer.Exit(code=1)
+
+
+# ============================================================================
+# RECAST command
+# ============================================================================
+@app.command("recast")
+def recast(
     file: Path = typer.Argument(
         ...,
         help="Input .h5ad/.zarr",
@@ -493,7 +782,7 @@ def convert(
     ),
     entries: Optional[List[str]] = typer.Argument(
         None,
-        help="Matrix paths to convert, e.g. 'X', 'layers/counts', 'raw/X'",
+        help="Matrix paths to recast, e.g. 'X', 'layers/counts', 'raw/X'",
     ),
     output: Optional[Path] = typer.Option(
         None,
@@ -511,7 +800,7 @@ def convert(
     convert_all: bool = typer.Option(
         False,
         "--all",
-        help="Convert X, every layer, and raw/X",
+        help="Recast X, every layer, and raw/X",
     ),
     dtype: Optional[str] = typer.Option(
         None,
@@ -531,7 +820,7 @@ def convert(
     force: bool = typer.Option(
         False,
         "--force",
-        help="Convert despite a lossy cast or a large size increase",
+        help="Recast despite a lossy cast or a large size increase",
     ),
     in_memory: bool = typer.Option(
         False,
@@ -562,11 +851,13 @@ def convert(
     both. Transposing streams by default, so it works on matrices too large
     to load.
 
+    This was `convert` until 0.7.0; `convert` now changes a store's format.
+
     Examples:
-        adata convert data.h5ad X -o out.h5ad --dtype float32
-        adata convert data.h5ad X -o out.h5ad --layout csc
-        adata convert data.h5ad X --inplace --dtype float32 --indices-dtype int32
-        adata convert data.h5ad --all -o out.h5ad --dtype float32
+        adata recast data.h5ad X -o out.h5ad --dtype float32
+        adata recast data.h5ad X -o out.h5ad --layout csc
+        adata recast data.h5ad X --inplace --dtype float32 --indices-dtype int32
+        adata recast data.h5ad --all -o out.h5ad --dtype float32
     """
     if not inplace and output is None:
         console.print(
@@ -586,7 +877,7 @@ def convert(
         raise typer.Exit(code=1)
 
     try:
-        convert_store(
+        recast_store(
             file=file,
             entries=list(entries) if entries else None,
             output=output,
@@ -848,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:
@@ -898,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:
@@ -938,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:
@@ -1082,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
 
@@ -1138,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
 
@@ -1192,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.6.1 → pyadata_cli-0.7.1}/src/adata/commands/__init__.py

@@ -6,4 +6,5 @@ from adata.commands.ls import list_store
 from adata.commands.create import create_store
 from adata.commands.split import split_store
 from adata.commands.concat import MERGE_CHOICES, MERGE_STRATEGIES, concat_stores
+from adata.commands.recast import recast_store
 from adata.commands.convert import convert_store

pyadata_cli-0.7.1/src/adata/commands/convert.py

@@ -0,0 +1,71 @@
+"""The `convert` command: rewrite a store in another format.
+
+Every refusal happens while building the plan, before an output exists, and
+the outputs are written beside their destination and moved into place only
+once complete. A conversion that fails therefore leaves nothing behind, and
+never a half-written store that the next command would read as a whole one.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List, Optional
+
+from rich.console import Console
+
+from adata.conversion import (
+    Options,
+    check_options,
+    converter_for,
+    detect_format,
+    output_format,
+)
+from adata.util.path import same_path
+from adata.util.staging import staged_outputs
+
+
+def convert_store(
+    file: Path,
+    output: Path,
+    console: Console,
+    *,
+    src_format: Optional[str] = None,
+    dst_format: Optional[str] = None,
+    options: Options = Options(),
+) -> List[Path]:
+    """Convert `file` into `output`; return the paths written."""
+    file, output = Path(file), Path(output)
+    if str(output) == "-":
+        raise ValueError(
+            "convert writes a store, which cannot go to stdout; give a path "
+            "with -o."
+        )
+    if options.zarr_format not in (None, 2, 3):
+        raise ValueError("--zarr-format must be 2 or 3.")
+
+    src_format = src_format or detect_format(file)
+    dst_format = output_format(output, dst_format)
+    converter = converter_for(src_format, dst_format)
+    check_options(converter, options, src_format, dst_format)
+
+    plan = converter.plan(file, output, src_format, dst_format, options)
+    for out in plan.outputs:
+        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}")
+        if out.exists() and not options.overwrite:
+            raise FileExistsError(
+                f"'{out}' already exists. Pass --overwrite to replace it."
+            )
+
+    console.print(f"[cyan]Converting[/] {file}: {plan.summary}")
+    for warning in plan.warnings:
+        console.print(f"[yellow]Warning:[/] {warning}")
+
+    with staged_outputs(plan.outputs) as staged:
+        converter.write(plan, staged, console)
+
+    for out in plan.outputs:
+        console.print(f"[green]Wrote[/] {out}")
+    return plan.outputs