Export/Import commands

.github/workflows/tests.yml

@@ -11,7 +11,7 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  test:
+  tests:
     runs-on: ubuntu-latest
     timeout-minutes: 20
 
@@ -23,6 +23,21 @@ jobs:
       fail-fast: false
       matrix:
         python-version: ["3.12"]  # add "3.13" if you want
+        module:
+          - name: cli
+            tests: tests/test_cli.py
+          - name: export
+            tests: tests/test_export.py
+          - name: import
+            tests: tests/test_import.py
+          - name: info-read
+            tests: tests/test_info_read.py
+          - name: subset
+            tests: tests/test_subset.py
+          - name: zarr
+            tests: tests/test_zarr.py
+
+    name: tests (${{ matrix.module.name }})
 
     steps:
       - uses: actions/checkout@v4
@@ -35,36 +50,36 @@ jobs:
       - name: Set up uv
         uses: astral-sh/setup-uv@v3
         with:
-          enable-cache: true
+          enable-cache: false
 
       - name: Install dependencies (frozen)
         run: uv sync --extra dev --frozen
 
       - name: Run tests with coverage
         run: |
-          uv run pytest -v \
+          uv run pytest -v -W default ${{ matrix.module.tests }} \
             --cov=h5ad \
             --cov-report=term-missing \
             --cov-report=xml \
             --cov-report=html \
-            --junitxml=pytest-results.xml
+            --junitxml=pytest-results-${{ matrix.module.name }}.xml
 
       - name: Publish test results summary
         uses: EnricoMi/publish-unit-test-result-action@v2
         if: always()
         with:
-          files: pytest-results.xml
-          check_name: Test Results
+          files: pytest-results-${{ matrix.module.name }}.xml
+          check_name: Test Results (${{ matrix.module.name }})
 
       - name: Upload coverage artifacts
         uses: actions/upload-artifact@v4
         if: always()
         with:
-          name: coverage
+          name: coverage-${{ matrix.module.name }}
           path: |
             coverage.xml
             htmlcov/
-            pytest-results.xml
+            pytest-results-${{ matrix.module.name }}.xml
           retention-days: 30
 
       - name: Upload coverage to Codecov

README.md

@@ -1,18 +1,20 @@
 # h5ad CLI
 
-A command-line tool for exploring huge `.h5ad` (AnnData) files without loading them fully into memory. Streams data directly from disk for efficient inspection of structure, metadata, and matrices.
+A command-line tool for exploring huge AnnData stores (`.h5ad` and `.zarr`) without loading them fully into memory. Streams data directly from disk for efficient inspection of structure, metadata, and matrices.
 
 ## Features
 
-- **`info`** – Show file structure and dimensions (`n_obs × n_var`)
-- **`table`** – Export obs/var metadata to CSV with chunked streaming
-- **`subset`** – Filter h5ad files by cell/gene names (supports dense and sparse CSR/CSC matrices)
-- Memory-efficient chunked processing for large files
-- Rich terminal output with colors and progress bars
+- Streaming access to very large `.h5ad` and `.zarr` stores
+- Auto-detects `.h5ad` files vs `.zarr` directories
+- Chunked processing for dense and sparse matrices (CSR/CSC)
+- Rich terminal output with progress indicators
 
 ## Installation
 
+Using [uv](https://docs.astral.sh/uv/) (recommended):
 ```bash
+git clone https://github.com/cellgeni/h5ad-cli.git
+cd h5ad-cli
 uv sync
 ```
 
@@ -21,45 +23,27 @@ For development and testing:
 uv sync --extra dev
 ```
 
-See [docs/TESTING.md](docs/TESTING.md) for testing documentation.
-
-## Usage
-Invoke any subcommand via `uv run h5ad ...`:
-
-```bash
-uv run h5ad --help
-```
-
-#### Examples
-
-**Inspect overall structure and axis sizes:**
+Alternative with pip:
 ```bash
-uv run h5ad info data.h5ad
+git clone https://github.com/cellgeni/h5ad-cli.git
+cd h5ad-cli
+pip install .
 ```
 
-**Export full obs metadata to CSV:**
+For development and testing with pip:
 ```bash
-uv run h5ad table data.h5ad --axis obs --out obs_metadata.csv
+pip install -e ".[dev]"
 ```
 
-**Export selected obs columns to stdout:**
-```bash
-uv run h5ad table data.h5ad --axis obs --cols cell_type,donor
-```
+See [docs/TESTING.md](docs/TESTING.md) for testing documentation.
 
-**Export var metadata with custom chunk size:**
-```bash
-uv run h5ad table data.h5ad --axis var --chunk-rows 5000 --out var_metadata.csv
-```
+## Commands (Overview)
 
-**Subset by cell names:**
-```bash
-uv run h5ad subset input.h5ad output.h5ad --obs cells.txt
-```
+Run help at any level (e.g. `uv run h5ad --help`, `uv run h5ad export --help`).
 
-**Subset by both cells and genes:**
-```bash
-uv run h5ad subset input.h5ad output.h5ad --obs cells.txt --var genes.txt
-```
+- `info` – read-only inspection of store layout, shapes, and type hints; supports drilling into paths like `obsm/X_pca` or `uns`.
+- `subset` – stream and write a filtered copy based on obs/var name lists, preserving dense and sparse matrix encodings.
+- `export` – extract data from a store; subcommands: `dataframe` (obs/var to CSV), `array` (dense to `.npy`), `sparse` (CSR/CSC to `.mtx`), `dict` (JSON), `image` (PNG).
+- `import` – write new data into a store; subcommands: `dataframe` (CSV → obs/var), `array` (`.npy`), `sparse` (`.mtx`), `dict` (JSON).
 
-All commands stream from disk, so even multi-GB `.h5ad` files remain responsive.
+See [docs/GET_STARTED.md](docs/GET_STARTED.md) for a short tutorial.