Getting Started

Installation

zappend requires a Python v3.10+ environment. To install the latest released version from PyPI:

pip install zappend

You can replace zappend with zappend[dev] in the above command to also install development dependencies, with zappend[doc] to also install documentation-building dependencies, or with zappend[dev,doc] to get both additional dependency sets.

To install the latest version for development, clone the repository, and with the repository’s root directory as the current working directory execute:

pip install --editable .

Using the CLI

Get usage help:

zappend --help

Get configuration help in Markdown format (json also available):

zappend --help-config md

Process list of local slice paths:

zappend --target target.zarr slice-1.nc slice-2.nc slice-3.nc

Process list of local slice paths with configuration in config.yaml:

zappend --config config.yaml slice-1.nc slice-2.nc slice-3.nc

Using the Python API

Process list of local slice paths:

from zappend.api import zappend

zappend(
    ["slice-1.nc", "slice-2.nc", "slice-3.nc"],
    target_dir="target.zarr",
    zarr_format=3,
)

Process list of slices stored in S3 configuration in config:

from zappend.api import zappend

config = {
    "target_dir": "target.zarr",
    "zarr_format": 3,
    "slice_storage_options": {
        "key": "...",
        "secret": "...",
    },
}

zappend(
    (
        f"s3:/mybucket/data/{name}"
        for name in ["slice-1.nc", "slice-2.nc", "slice-3.nc"]
    ),
    config=config,
)

Slice items can also be arguments passed to your custom slice source, a function or class that provides the actual slice to be appended:

import xarray as xr
from zappend.api import zappend


def get_dataset(path: str):
    ds = xr.open_dataset(path)
    return ds.drop_vars(["ndvi_min", "ndvi_max"])


zappend(
    ["slice-1.nc", "slice-2.nc", "slice-3.nc"],
    slice_source=get_dataset,
    target_dir="target.zarr",
    zarr_format=3,
)

For the details, please refer to the section Slice Sources in the User Guide.