Skip to content

abczarr.api.config

Describe a Zarr array or group to create.

An ArrayConfig or GroupConfig is a reusable description of what to create. It carries the coarse choices, such as chunking, sharding, compression and the format version, and lowers them to the exact metadata a driver writes. Pass one to create to make the array or group it describes, or spread its fields into a group's create_array as keyword arguments.

"auto" on a field means that the target version decides. An auto chunk size fits a byte budget, an auto compressor is the version's default, and an auto fill value is the dtype's zero. A single config therefore lowers correctly to either format version.

Classes

ZarrConfig 

ZarrConfig(zarr_version: Literal[1, 2, 3] = 3, overwrite: bool | int | str = False, driver: str | bytes | None = None, attributes: Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any] = {})

The choices shared by everything abczarr creates.

ArrayConfig and GroupConfig build on this class. It is not created on its own.

Parameters:

Name Type Description Default
zarr_version int

The Zarr format version to write.

 3
overwrite bool

Replace whatever is already at the target location instead of raising.

 False
driver str

The name of the driver to create with. None lets abczarr pick one that can write the result.

 None
attributes mapping

User attributes to store on the node.

 {}

Attributes

zarr_version class-attribute instance-attribute 
zarr_version: ZarrVersion = 3
overwrite class-attribute instance-attribute 
overwrite: bool = False
driver class-attribute instance-attribute 
driver: str | None = None
attributes class-attribute instance-attribute 
attributes: JsonDict = field(factory=dict)

Methods:

keys 
keys() -> list[str]

The config's field names, so dict(config) and **config work.

__getitem__ 
__getitem__(key: str) -> Any

Return the value of the field named key.

Parameters:

Name Type Description Default
key str

The field's name.

 required

GroupConfig 

GroupConfig(zarr_version: Literal[1, 2, 3] = 3, overwrite: bool | int | str = False, driver: str | bytes | None = None, attributes: Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any] = {})

Bases: ZarrConfig

A description of a group to create.

A group holds no data of its own, so it adds nothing to ZarrConfig.

Methods:

ArrayConfig 

ArrayConfig(zarr_version: Literal[1, 2, 3] = 3, overwrite: bool | int | str = False, driver: str | bytes | None = None, attributes: Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any] = {}, shape: Iterable[Integral | integer | bool] | None = None, dtype: None = None, dimension_names: Iterable[str | bytes | None] | None = None, chunks: Integral | integer | bool | Iterable[Integral | integer | bool | Literal['auto']] | Iterable[tuple[str | bytes | None, Integral | integer | bool | Literal['auto']]] | Mapping[str | bytes | None, Integral | integer | bool | Literal['auto']] | None = 'auto', shards: Integral | integer | bool | Iterable[Integral | integer | bool | Literal['auto']] | Iterable[tuple[str | bytes | None, Integral | integer | bool | Literal['auto']]] | Mapping[str | bytes | None, Integral | integer | bool | Literal['auto']] | None = None, max_chunk_bytes: Integral | integer | bool = 8388608, max_shard_bytes: Integral | integer | bool = 2147483648, compression_ratio: Real | floating | bool = 1.8, compressor: str | bytes | Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any] | None = 'auto', compressor_options: Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any] = {}, filters: Iterable[Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any]] = (), fill_value: Number | number | bool | str | bytes | None = 'auto', order: Literal['C', 'F'] = 'C', dimension_separator: str | bytes = 'auto')

Bases: ZarrConfig

A description of an array to create.

Set shape and dtype on the config, or supply them when it is lowered. The chunking, sharding, and compression fields accept "auto", which is resolved against the shape, dtype, and format version.

Parameters:

Name Type Description Default
shape tuple of int

The array's shape. Required by the time the config is lowered.

 None
dtype numpy dtype

The array's data type. Required by the time the config is lowered.

 None
dimension_names tuple of str

A name for each axis, used by a chunk mapping and written to v3 metadata.

 None
chunks (int, auto, None, sequence or mapping)

The chunk size per axis. "auto" and None both fit max_chunk_bytes. -1 means the whole axis. A short sequence repeats its last entry.

 'auto'
shards (int, auto, sequence, mapping or None)

The shard size per axis, or None for no sharding. Sharding applies to Zarr v3 only.

 None
max_chunk_bytes int

The target chunk size in bytes when a chunk size is "auto".

 8388608
max_shard_bytes int

The target shard size in bytes when a shard size is "auto".

 2147483648
compression_ratio float

The compression factor the byte budgets assume.

 1.8
compressor (str, mapping, auto or None)

The compressor. "auto" picks abczarr's default, which is zstd. The Zarr v3 spec names no default. This follows zarr-python 3.x, which tensorstore also reads. None and "none" both mean no compression. A mapping is a codec spec passed through untouched.

 'auto'
compressor_options mapping

Options for a named compressor.

 {}
filters tuple of mapping

Codecs applied before the main compressor, passed through as specs.

 ()
fill_value (number, auto or None)

The value read where nothing was written. "auto" is the dtype's zero.

 'auto'
order (C, F)

The in-memory layout. This field is stored in Zarr v2 metadata. On v3 it is a runtime memory-layout preference and is not written to zarr.json.

 "C"
dimension_separator ('/', '.', auto)

The separator between chunk indices in a key. "auto" and None both mean /. This field is a v2 concept. On v3 the separator is carried in the chunk-key encoding instead.

 "/"

Attributes

shape class-attribute instance-attribute 
shape: Shape | None = None
dtype class-attribute instance-attribute 
dtype: dtype | None = None
dimension_names class-attribute instance-attribute 
dimension_names: tuple[str | None, ...] | None = None
chunks class-attribute instance-attribute 
chunks: ChunkSpec | None = 'auto'
shards class-attribute instance-attribute 
shards: ChunkSpec | None = None
max_chunk_bytes class-attribute instance-attribute 
max_chunk_bytes: int = 8 * 1024 ** 2
max_shard_bytes class-attribute instance-attribute 
max_shard_bytes: int = 2 * 1024 ** 3
compression_ratio class-attribute instance-attribute 
compression_ratio: float = 1.8
compressor class-attribute instance-attribute 
compressor: str | JsonDict | None = 'auto'
compressor_options class-attribute instance-attribute 
compressor_options: JsonDict = field(factory=dict)
filters class-attribute instance-attribute 
filters: tuple[JsonDict, ...] = ()
fill_value class-attribute instance-attribute 
fill_value: BuiltinNumber | str | None = 'auto'
order class-attribute instance-attribute 
order: MemoryOrder = 'C'
dimension_separator class-attribute instance-attribute 
dimension_separator: DimensionSeparator | str = 'auto'

Methods:

__attrs_post_init__ 
__attrs_post_init__() -> None
resolve 
resolve(data: ArrayLike | None = None, **overrides: Any) -> Self

Return a copy with "auto" chunking and sharding worked out.

The shape and dtype come from overrides first, then from the config. A missing shape or dtype falls back to data when data is given, so an override or a config value always takes precedence over the data.

Parameters:

Name Type Description Default
data array - like

Existing data to fall back to for a shape or dtype the config does not already carry.

 None
**overrides Any

Field values that take precedence over the config's own values, such as shape or dtype.

 {}

Returns:

Type Description
ArrayConfig

A copy of this config with "auto" chunking and sharding resolved to concrete values.

Raises:

Type Description
ValueError

If none of overrides, the config, and data supplies both a shape and a dtype.
to_metadata 
to_metadata() -> ArrayMetadata

Lower the config to the metadata a driver writes.

This method resolves "auto" fields, builds Zarr v3 metadata, and converts the result to zarr_version if that version is not 3.

Returns:

Type Description
ArrayMetadata

The metadata document describing the array.
compressor_codecs 
compressor_codecs() -> list[JsonDict]

The compressor as a list of zero or one v3 codec specs.

"auto" becomes the version default, zstd. None and "none" both mean no compressor. A mapping passes through unchanged.

resolved_fill_value 
resolved_fill_value() -> Any

The fill value, with "auto" turned into the dtype's zero.

resolved_separator 
resolved_separator() -> str

The chunk-key separator, with "auto" (or None) resolved.

ZarrOptions

Bases: TypedDict

The keyword form of ZarrConfig.

Attributes

zarr_version instance-attribute 
zarr_version: ZarrVersion
overwrite instance-attribute 
overwrite: bool
driver instance-attribute 
driver: str | None
attributes instance-attribute 
attributes: JsonDict

GroupOptions

Bases: ZarrOptions

The keyword form of GroupConfig.

ArrayOptions

Bases: ZarrOptions

The keyword form of ArrayConfig.

This TypedDict carries every ArrayConfig field except shape and dtype. A group's create_array takes those two fields as positional arguments instead.

Attributes

dimension_names instance-attribute 
dimension_names: tuple[str | None, ...] | None
chunks instance-attribute 
chunks: ChunkSpec
shards instance-attribute 
shards: ChunkSpec | None
max_chunk_bytes instance-attribute 
max_chunk_bytes: int
max_shard_bytes instance-attribute 
max_shard_bytes: int
compression_ratio instance-attribute 
compression_ratio: float
compressor instance-attribute 
compressor: str | JsonDict | None
compressor_options instance-attribute 
compressor_options: JsonDict
filters instance-attribute 
filters: tuple[JsonDict, ...]
fill_value instance-attribute 
fill_value: BuiltinNumber | str | None
order instance-attribute 
order: MemoryOrder
dimension_separator instance-attribute 
dimension_separator: DimensionSeparator | str