xarray-dataclass

What it is and what it does

xarray-dataclass wraps xarray's DataArray and Dataset objects in a dataclass-based interface, letting you declare typed multidimensional data structures with fixed dimensions, coordinates, and attributes at definition time. Instead of building xarray objects imperatively with method calls, you define a dataclass using special type hints (Data, Coord, Attr, Name) that encode the structure, then instantiate it with `.new()` or NumPy-like factory methods (`.zeros()`, `.ones()`). The package validates that your data matches the declared schema and provides static type checking support through Pyright.

It is primarily useful for scientific and data-analysis workflows where you want to enforce a consistent structure across xarray objects—for example, ensuring all images in a batch have the same dimensions and dtype, or defining reusable templates for multidimensional datasets. The package depends on numpy, xarray, and typing-extensions; it is actively maintained and supports Python 3.9 through 3.13.

Use it for

• Define reusable typed templates for multidimensional scientific data (e.g., images, time series, gridded fields) with fixed dimensions and dtypes.
• Create xarray DataArrays or Datasets with static type checking to catch dimension/dtype mismatches at development time.
• Build batch processing pipelines where all inputs must conform to a declared schema (e.g., all images must be 2D float arrays with x and y coordinates).
• Attach metadata (attributes, coordinate names) to xarray objects declaratively rather than imperatively after creation.
• Generate xarray objects with NumPy-like constructors (zeros, ones) while enforcing the declared structure.

Worth the install?

AI-flagged interpretation of the facts on this page. Verify before relying on it.

Install

xarray-dataclass on PyPI

Before you install

Low friction install with only three runtime dependencies (numpy, typing-extensions, xarray). Active maintenance as of August 2026 with recent commits.

Requires Python 3.9 or later; xarray and numpy must be installed.

License in practice

MIT License permits commercial and private use with minimal restrictions; you may use, modify, and distribute the package freely provided you include the original copyright notice.

Quickstart

pip install xarray-dataclass

from dataclasses import dataclass
from typing import Literal
from xarray_dataclass import AsDataArray, Data, Coord

X, Y = Literal["x"], Literal["y"]

@dataclass
class Image(AsDataArray):
    data: Data[tuple[X, Y], float]
    x: Coord[X, int] = 0
    y: Coord[Y, int] = 0

image = Image.new([[0, 1], [2, 3]], x=[0, 1], y=[0, 1])

Package facts

Evidence: xarray_dataclass-3.0.0-py3-none-any.whl

Tags

More Scientific/Engineering packages

See also pint-xarray · spatial_image · xarray · cf-xarray · multiscale-spatial-image · xproj · abstractcp · typed-json-dataclass · dataclass-csv · odc-loader