ExZarr.Version (ExZarr v1.1.0)

View Source

Version detection and routing for Zarr v2 and v3 formats.

This module provides utilities for detecting which Zarr specification version is being used and managing version-specific behavior throughout the library.

Supported Versions

  • Zarr v2: Original specification with .zarray/.zgroup metadata files
  • Zarr v3: New specification with unified zarr.json metadata format

Version Detection

Versions are detected from the zarr_format field in metadata:

iex> ExZarr.Version.detect_version(%{"zarr_format" => 2})
{:ok, 2}

iex> ExZarr.Version.detect_version(%{"zarr_format" => 3})
{:ok, 3}

Default Version

The default version for new arrays can be configured:

# config/config.exs
config :ex_zarr, default_zarr_version: 3

If not configured, v3 is used by default for new arrays.

Summary

Types

version()
version_error()

Functions

default_version()

Returns the default Zarr version for new arrays.

detect_version(metadata_json)

Detects the Zarr format version from metadata JSON.

metadata_filename(version, node_type \\ :array)

Returns the metadata filename for a given version.

supported?(version)

Checks if a version number is supported.

supported_versions()

Returns the list of supported Zarr specification versions.

Types

version()

@type version() :: 2 | 3

version_error()

@type version_error() :: :missing_zarr_format | {:unsupported_version, integer()}

Functions

default_version()

@spec default_version() :: version()

Returns the default Zarr version for new arrays.

The default can be configured via application config:

config :ex_zarr, default_zarr_version: 2  # or 3

If not configured, defaults to version 3.

Returns

  • 2 or 3 - The default version number

Examples

iex> ExZarr.Version.default_version()
3

detect_version(metadata_json)

@spec detect_version(map()) :: {:ok, version()} | {:error, version_error()}

Detects the Zarr format version from metadata JSON.

Parameters

  • metadata_json - Decoded metadata map containing zarr_format field

Returns

  • {:ok, version} - Version 2 or 3
  • {:error, :missing_zarr_format} - No zarr_format field found
  • {:error, {:unsupported_version, v}} - Unsupported version number

Examples

iex> ExZarr.Version.detect_version(%{"zarr_format" => 2})
{:ok, 2}

iex> ExZarr.Version.detect_version(%{"zarr_format" => 3})
{:ok, 3}

iex> ExZarr.Version.detect_version(%{"zarr_format" => 4})
{:error, {:unsupported_version, 4}}

iex> ExZarr.Version.detect_version(%{})
{:error, :missing_zarr_format}

metadata_filename(version, node_type \\ :array)

@spec metadata_filename(version(), :array | :group) :: String.t()

Returns the metadata filename for a given version.

  • v2 uses .zarray for arrays and .zgroup for groups
  • v3 uses unified zarr.json for both

Parameters

  • version - Zarr format version (2 or 3)
  • node_type - Type of node (:array or :group, default :array)

Returns

  • Metadata filename string

Examples

iex> ExZarr.Version.metadata_filename(2)
".zarray"

iex> ExZarr.Version.metadata_filename(2, :group)
".zgroup"

iex> ExZarr.Version.metadata_filename(3)
"zarr.json"

iex> ExZarr.Version.metadata_filename(3, :group)
"zarr.json"

supported?(version)

@spec supported?(integer()) :: boolean()

Checks if a version number is supported.

Parameters

  • version - Version number to check

Returns

  • true if version is supported
  • false otherwise

Examples

iex> ExZarr.Version.supported?(2)
true

iex> ExZarr.Version.supported?(3)
true

iex> ExZarr.Version.supported?(4)
false

supported_versions()

@spec supported_versions() :: [version(), ...]

Returns the list of supported Zarr specification versions.

Returns

  • List of supported version numbers

Examples

iex> ExZarr.Version.supported_versions()
[2, 3]