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

Defines typed xarray DataArray and Dataset objects using Python dataclasses, with fixed dimensions, data types, coordinates, and attributes enforced at the class level.

Yes. The package is actively maintained, has low install friction, carries a permissive MIT license, and solves a real problem for teams working with xarray who want type safety and schema enforcement. It is well-suited for scientific computing and data-analysis workflows where consistency and static checking add value. No known vulnerabilities.

Install

xarray-dataclass on PyPI

pip install xarray-dataclass

uv add xarray-dataclass

poetry add xarray-dataclass

Installing xarray-dataclass

Before you install

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

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])

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

Verify before relying

• Whether static type checking with Pyright works as advertised for all dimension and dtype combinations.
• Performance characteristics when working with large multidimensional arrays compared to raw xarray.
• Compatibility with xarray's latest versions beyond what the dependency specification guarantees.

Package facts

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

Keywords: dataarray, dataclass, dataset, typing, xarray

Tags

More Scientific/Engineering packages