API Reference

Multi-convention

zarr_cm

Copyright (c) 2026 Davis Bennett. All rights reserved.

zarr-cm: Python implementation of Zarr Conventions Metadata

CONVENTION_NAMES module-attribute

CONVENTION_NAMES: Final = frozenset(_REGISTRY)

ALL_CONVENTION_KEYS module-attribute

ALL_CONVENTION_KEYS: Final = frozenset(
    CONVENTION_KEYS
    | CONVENTION_KEYS
    | CONVENTION_KEYS
    | CONVENTION_KEYS
    | CONVENTION_KEYS
)

MultiConventionAttrs module-attribute

MultiConventionAttrs = TypedDict(
    "MultiConventionAttrs",
    {
        "zarr_conventions": NotRequired[
            list[ConventionMetadataObject]
        ],
        "proj:code": NotRequired[str],
        "proj:wkt2": NotRequired[str],
        "proj:projjson": NotRequired[dict[str, Any]],
        "spatial:dimensions": NotRequired[list[str]],
        "spatial:bbox": NotRequired[list[float]],
        "spatial:transform_type": NotRequired[str],
        "spatial:transform": NotRequired[list[float]],
        "spatial:shape": NotRequired[list[int]],
        "spatial:registration": NotRequired[str],
        "multiscales": NotRequired[MultiscalesAttrs],
        "license": NotRequired[LicenseAttrs],
        "uom": NotRequired[UomAttrs],
    },
)

create_many

create_many(
    conventions: dict[ConventionName, dict[str, Any]],
) -> dict[str, Any]

Create and insert multiple conventions into a single attributes dict.

Parameters

conventions Mapping from convention display name (e.g. "geo-proj") to already-formed convention data (the AttrsT value).

Returns

dict[str, Any] A new attributes dict containing all convention data and a combined zarr_conventions array.

Source code in src/zarr_cm/__init__.py

def create_many(
    conventions: dict[ConventionName, dict[str, Any]],
) -> dict[str, Any]:
    """Create and insert multiple conventions into a single attributes dict.

    Parameters
    ----------
    conventions
        Mapping from convention display name (e.g. ``"geo-proj"``) to
        already-formed convention data (the ``AttrsT`` value).

    Returns
    -------
    dict[str, Any]
        A new attributes dict containing all convention data and a
        combined ``zarr_conventions`` array.
    """
    result: dict[str, Any] = {}
    for name, data in conventions.items():
        mod = _get_module(name)
        mod.validate(data)
        result = mod.insert(result, data, overwrite=True)
    return result

validate_many

validate_many(
    attrs: dict[str, Any],
    conventions: Iterable[ConventionName],
) -> dict[str, Any]

Validate multiple conventions within an attributes dict.

Parameters

attrs The attributes dict to validate. conventions Convention names to validate.

Returns

dict[str, Any] The input attrs (pass-through on success).

Source code in src/zarr_cm/__init__.py

def validate_many(
    attrs: dict[str, Any],
    conventions: Iterable[ConventionName],
) -> dict[str, Any]:
    """Validate multiple conventions within an attributes dict.

    Parameters
    ----------
    attrs
        The attributes dict to validate.
    conventions
        Convention names to validate.

    Returns
    -------
    dict[str, Any]
        The input *attrs* (pass-through on success).
    """
    for name in conventions:
        mod = _get_module(name)
        _, extracted = mod.extract(attrs)
        mod.validate(dict(extracted))
    return attrs

validate_all

validate_all(attrs: dict[str, Any]) -> dict[str, Any]

Validate all detected conventions within an attributes dict.

Detects which conventions are present by matching UUIDs in zarr_conventions, then validates each one.

Parameters

attrs The attributes dict to validate.

Returns

dict[str, Any] The input attrs (pass-through on success).

Source code in src/zarr_cm/__init__.py

def validate_all(
    attrs: dict[str, Any],
) -> dict[str, Any]:
    """Validate all detected conventions within an attributes dict.

    Detects which conventions are present by matching UUIDs in
    ``zarr_conventions``, then validates each one.

    Parameters
    ----------
    attrs
        The attributes dict to validate.

    Returns
    -------
    dict[str, Any]
        The input *attrs* (pass-through on success).
    """
    return validate_many(attrs, _detect_conventions(attrs))

insert_many

insert_many(
    attrs: dict[str, Any],
    conventions: dict[ConventionName, dict[str, Any]],
    *,
    overwrite: bool = False
) -> dict[str, Any]

Insert multiple conventions into an attributes dict.

Parameters

attrs The existing attributes dict. conventions Mapping from convention display name to already-formed convention data. overwrite If False (default), raise ValueError when attrs already contains keys present in a convention's data.

Returns

dict[str, Any] A new attributes dict with all convention data merged in.

Source code in src/zarr_cm/__init__.py

def insert_many(
    attrs: dict[str, Any],
    conventions: dict[ConventionName, dict[str, Any]],
    *,
    overwrite: bool = False,
) -> dict[str, Any]:
    """Insert multiple conventions into an attributes dict.

    Parameters
    ----------
    attrs
        The existing attributes dict.
    conventions
        Mapping from convention display name to already-formed convention data.
    overwrite
        If False (default), raise ``ValueError`` when *attrs* already
        contains keys present in a convention's data.

    Returns
    -------
    dict[str, Any]
        A new attributes dict with all convention data merged in.
    """
    result = attrs
    for name, data in conventions.items():
        mod = _get_module(name)
        mod.validate(data)
        result = mod.insert(result, data, overwrite=overwrite)
    return result

extract_many

extract_many(
    attrs: dict[str, Any],
    conventions: Iterable[ConventionName],
) -> tuple[
    dict[str, Any], dict[ConventionName, dict[str, Any]]
]

Extract multiple conventions from an attributes dict.

Parameters

attrs The attributes dict to extract from. conventions Convention names to extract.

Returns

tuple[dict[str, Any], dict[str, dict[str, Any]]] (remaining_attrs, extracted) where extracted maps convention names to their convention data dicts.

Source code in src/zarr_cm/__init__.py

def extract_many(
    attrs: dict[str, Any],
    conventions: Iterable[ConventionName],
) -> tuple[dict[str, Any], dict[ConventionName, dict[str, Any]]]:
    """Extract multiple conventions from an attributes dict.

    Parameters
    ----------
    attrs
        The attributes dict to extract from.
    conventions
        Convention names to extract.

    Returns
    -------
    tuple[dict[str, Any], dict[str, dict[str, Any]]]
        ``(remaining_attrs, extracted)`` where *extracted* maps
        convention names to their convention data dicts.
    """
    remaining = attrs
    extracted: dict[ConventionName, dict[str, Any]] = {}
    for name in conventions:
        mod = _get_module(name)
        remaining, data = mod.extract(remaining)
        extracted[name] = dict(data)
    return remaining, extracted

extract_all

extract_all(
    attrs: dict[str, Any],
) -> tuple[
    dict[str, Any], dict[ConventionName, dict[str, Any]]
]

Extract all detected conventions from an attributes dict.

Detects which conventions are present by matching UUIDs in zarr_conventions, then extracts each one.

Parameters

attrs The attributes dict to extract from.

Returns

tuple[dict[str, Any], dict[str, dict[str, Any]]] (remaining_attrs, extracted) where extracted maps convention names to their convention data dicts.

Source code in src/zarr_cm/__init__.py

def extract_all(
    attrs: dict[str, Any],
) -> tuple[dict[str, Any], dict[ConventionName, dict[str, Any]]]:
    """Extract all detected conventions from an attributes dict.

    Detects which conventions are present by matching UUIDs in
    ``zarr_conventions``, then extracts each one.

    Parameters
    ----------
    attrs
        The attributes dict to extract from.

    Returns
    -------
    tuple[dict[str, Any], dict[str, dict[str, Any]]]
        ``(remaining_attrs, extracted)`` where *extracted* maps
        convention names to their convention data dicts.
    """
    return extract_many(attrs, _detect_conventions(attrs))

Core

zarr_cm._core

ConventionMetadataObject

Bases: TypedDict

A convention metadata object for the zarr_conventions array.

Source code in src/zarr_cm/_core.py

class ConventionMetadataObject(TypedDict):
    """A convention metadata object for the ``zarr_conventions`` array."""

    uuid: NotRequired[str]
    schema_url: NotRequired[str]
    spec_url: NotRequired[str]
    name: NotRequired[str]
    description: NotRequired[str]

uuid instance-attribute

uuid: NotRequired[str]

schema_url instance-attribute

schema_url: NotRequired[str]

spec_url instance-attribute

spec_url: NotRequired[str]

name instance-attribute

name: NotRequired[str]

description instance-attribute

description: NotRequired[str]

ConventionAttrs

Bases: TypedDict

Attributes dict with a zarr_conventions array.

Source code in src/zarr_cm/_core.py

class ConventionAttrs(TypedDict):
    """Attributes dict with a ``zarr_conventions`` array."""

    zarr_conventions: list[ConventionMetadataObject]

zarr_conventions instance-attribute

zarr_conventions: list[ConventionMetadataObject]

validate_convention_metadata_object

validate_convention_metadata_object(
    cmo: dict[str, Any],
) -> None

Validate that a ConventionMetadataObject has at least one identifier.

Source code in src/zarr_cm/_core.py

def validate_convention_metadata_object(cmo: dict[str, Any]) -> None:
    """Validate that a ConventionMetadataObject has at least one identifier."""
    if not any(k in cmo for k in ("uuid", "schema_url", "spec_url")):
        msg = "ConventionMetadataObject must have at least one of 'uuid', 'schema_url', or 'spec_url'"
        raise ValueError(msg)

insert_convention

insert_convention(
    attrs: dict[str, Any],
    cmo: ConventionMetadataObject,
    convention_data: dict[str, Any],
    *,
    overwrite: bool = False
) -> dict[str, Any]

Insert convention metadata into an attributes dict.

Returns a new dict with the convention data merged in and the CMO appended to the zarr_conventions array.

Parameters

attrs The existing attributes dict. cmo The convention metadata object to append to zarr_conventions. convention_data Convention-specific keys to merge into attrs. overwrite If False (default), raise ValueError when attrs already contains keys present in convention_data. If True, the convention data silently overwrites colliding keys.

Source code in src/zarr_cm/_core.py

def insert_convention(
    attrs: dict[str, Any],
    cmo: ConventionMetadataObject,
    convention_data: dict[str, Any],
    *,
    overwrite: bool = False,
) -> dict[str, Any]:
    """Insert convention metadata into an attributes dict.

    Returns a new dict with the convention data merged in and the CMO
    appended to the ``zarr_conventions`` array.

    Parameters
    ----------
    attrs
        The existing attributes dict.
    cmo
        The convention metadata object to append to ``zarr_conventions``.
    convention_data
        Convention-specific keys to merge into *attrs*.
    overwrite
        If False (default), raise ``ValueError`` when *attrs* already
        contains keys present in *convention_data*.  If True, the
        convention data silently overwrites colliding keys.
    """
    if not overwrite:
        collisions = set(attrs) & (set(convention_data) - {"zarr_conventions"})
        if collisions:
            msg = f"attrs already contains keys that would be overwritten by convention data: {sorted(collisions)}. Pass overwrite=True to allow."
            raise ValueError(msg)
    result = {**attrs, **convention_data}
    existing: list[ConventionMetadataObject] = list(result.get("zarr_conventions", []))
    if cmo not in existing:
        existing.append(cmo)
    result["zarr_conventions"] = existing
    return result

extract_convention

extract_convention(
    attrs: dict[str, Any],
    convention_keys: set[str],
    match_fn: Callable[[ConventionMetadataObject], bool],
) -> tuple[dict[str, Any], dict[str, Any]]

Extract convention metadata from an attributes dict.

Returns (remaining_attrs, convention_data) where the matching CMO is removed from zarr_conventions and the convention-specific keys are separated out.

Source code in src/zarr_cm/_core.py

def extract_convention(
    attrs: dict[str, Any],
    convention_keys: set[str],
    match_fn: Callable[[ConventionMetadataObject], bool],
) -> tuple[dict[str, Any], dict[str, Any]]:
    """Extract convention metadata from an attributes dict.

    Returns ``(remaining_attrs, convention_data)`` where the matching CMO
    is removed from ``zarr_conventions`` and the convention-specific keys
    are separated out.
    """
    remaining: dict[str, Any] = {}
    convention_data: dict[str, Any] = {}

    for key, value in attrs.items():
        if key == "zarr_conventions":
            continue
        if key in convention_keys:
            convention_data[key] = value
        else:
            remaining[key] = value

    old_conventions: list[ConventionMetadataObject] = attrs.get("zarr_conventions", [])
    new_conventions = [cmo for cmo in old_conventions if not match_fn(cmo)]
    if new_conventions:
        remaining["zarr_conventions"] = new_conventions

    return remaining, convention_data

geo-proj

zarr_cm.geo_proj

geo-proj convention: https://github.com/zarr-experimental/geo-proj

GeoProjAttrs module-attribute

GeoProjAttrs = TypedDict(
    "GeoProjAttrs",
    {
        "proj:code": NotRequired[str],
        "proj:wkt2": NotRequired[str],
        "proj:projjson": NotRequired[dict[str, Any]],
    },
)

GeoProjConventionAttrs module-attribute

GeoProjConventionAttrs = TypedDict(
    "GeoProjConventionAttrs",
    {
        "zarr_conventions": list[ConventionMetadataObject],
        "proj:code": NotRequired[str],
        "proj:wkt2": NotRequired[str],
        "proj:projjson": NotRequired[dict[str, Any]],
    },
)

UUID module-attribute

UUID: Final = 'f17cb550-5864-4468-aeb7-f3180cfb622f'

SCHEMA_URL module-attribute

SCHEMA_URL: Final = (
    "https://raw.githubusercontent.com/zarr-experimental/geo-proj/refs/tags/v1/schema.json"
)

SPEC_URL module-attribute

SPEC_URL: Final = (
    "https://github.com/zarr-experimental/geo-proj/blob/v1/README.md"
)

CMO module-attribute

CMO: Final[ConventionMetadataObject] = {
    "uuid": UUID,
    "schema_url": SCHEMA_URL,
    "spec_url": SPEC_URL,
    "name": "proj:",
    "description": "Coordinate reference system information for geospatial data",
}

CONVENTION_KEYS module-attribute

CONVENTION_KEYS: Final = {
    "proj:code",
    "proj:wkt2",
    "proj:projjson",
}

create

create(
    *,
    code: str | None = None,
    wkt2: str | None = None,
    projjson: dict[str, Any] | None = None
) -> GeoProjAttrs

Create a GeoProjAttrs dict from keyword arguments.

Source code in src/zarr_cm/geo_proj.py

def create(
    *,
    code: str | None = None,
    wkt2: str | None = None,
    projjson: dict[str, Any] | None = None,
) -> GeoProjAttrs:
    """Create a ``GeoProjAttrs`` dict from keyword arguments."""
    result = GeoProjAttrs()
    if code is not None:
        result["proj:code"] = code
    if wkt2 is not None:
        result["proj:wkt2"] = wkt2
    if projjson is not None:
        result["proj:projjson"] = projjson
    validate(dict(result))
    return result

insert

insert(
    attrs: dict[str, Any],
    data: GeoProjAttrs,
    *,
    overwrite: bool = False
) -> dict[str, Any]

Insert geo-proj convention metadata into an attributes dict.

Source code in src/zarr_cm/geo_proj.py

def insert(
    attrs: dict[str, Any], data: GeoProjAttrs, *, overwrite: bool = False
) -> dict[str, Any]:
    """Insert geo-proj convention metadata into an attributes dict."""
    return insert_convention(attrs, CMO, dict(data), overwrite=overwrite)

extract

extract(
    attrs: dict[str, Any],
) -> tuple[dict[str, Any], GeoProjAttrs]

Extract geo-proj convention metadata from an attributes dict.

Source code in src/zarr_cm/geo_proj.py

def extract(
    attrs: dict[str, Any],
) -> tuple[dict[str, Any], GeoProjAttrs]:
    """Extract geo-proj convention metadata from an attributes dict."""
    remaining, convention_data = extract_convention(
        attrs,
        CONVENTION_KEYS,
        lambda cmo: cmo.get("uuid") == UUID,
    )
    return remaining, GeoProjAttrs(**convention_data)  # type: ignore[typeddict-item]

validate

validate(data: dict[str, Any]) -> GeoProjAttrs

Validate geo-proj convention data.

Exactly one of proj:code, proj:wkt2, or proj:projjson must be present.

Source code in src/zarr_cm/geo_proj.py

def validate(data: dict[str, Any]) -> GeoProjAttrs:
    """Validate geo-proj convention data.

    Exactly one of ``proj:code``, ``proj:wkt2``, or ``proj:projjson``
    must be present.
    """
    present = [k for k in ("proj:code", "proj:wkt2", "proj:projjson") if k in data]
    if len(present) != 1:
        msg = f"Exactly one of 'proj:code', 'proj:wkt2', 'proj:projjson' must be present, got: {present}"
        raise ValueError(msg)
    return data  # type: ignore[return-value]

spatial

zarr_cm.spatial

spatial convention: https://github.com/zarr-conventions/spatial

SpatialAttrs module-attribute

SpatialAttrs = TypedDict(
    "SpatialAttrs",
    {
        "spatial:dimensions": list[str],
        "spatial:bbox": NotRequired[list[float]],
        "spatial:transform_type": NotRequired[str],
        "spatial:transform": NotRequired[list[float]],
        "spatial:shape": NotRequired[list[int]],
        "spatial:registration": NotRequired[str],
    },
)

SpatialConventionAttrs module-attribute

SpatialConventionAttrs = TypedDict(
    "SpatialConventionAttrs",
    {
        "zarr_conventions": list[ConventionMetadataObject],
        "spatial:dimensions": list[str],
        "spatial:bbox": NotRequired[list[float]],
        "spatial:transform_type": NotRequired[str],
        "spatial:transform": NotRequired[list[float]],
        "spatial:shape": NotRequired[list[int]],
        "spatial:registration": NotRequired[str],
    },
)

UUID module-attribute

UUID: Final = '689b58e2-cf7b-45e0-9fff-9cfc0883d6b4'

SCHEMA_URL module-attribute

SCHEMA_URL: Final = (
    "https://raw.githubusercontent.com/zarr-conventions/spatial/refs/tags/v1/schema.json"
)

SPEC_URL module-attribute

SPEC_URL: Final = (
    "https://github.com/zarr-conventions/spatial/blob/v1/README.md"
)

CMO module-attribute

CMO: Final[ConventionMetadataObject] = {
    "uuid": UUID,
    "schema_url": SCHEMA_URL,
    "spec_url": SPEC_URL,
    "name": "spatial:",
    "description": "Spatial coordinate information",
}

CONVENTION_KEYS module-attribute

CONVENTION_KEYS: Final = {
    "spatial:dimensions",
    "spatial:bbox",
    "spatial:transform_type",
    "spatial:transform",
    "spatial:shape",
    "spatial:registration",
}

create

create(
    *,
    dimensions: list[str],
    bbox: list[float] | None = None,
    transform_type: str | None = None,
    transform: list[float] | None = None,
    shape: list[int] | None = None,
    registration: str | None = None
) -> SpatialAttrs

Create a SpatialAttrs dict from keyword arguments.

Source code in src/zarr_cm/spatial.py

def create(
    *,
    dimensions: list[str],
    bbox: list[float] | None = None,
    transform_type: str | None = None,
    transform: list[float] | None = None,
    shape: list[int] | None = None,
    registration: str | None = None,
) -> SpatialAttrs:
    """Create a ``SpatialAttrs`` dict from keyword arguments."""
    result = SpatialAttrs({"spatial:dimensions": dimensions})
    if bbox is not None:
        result["spatial:bbox"] = bbox
    if transform_type is not None:
        result["spatial:transform_type"] = transform_type
    if transform is not None:
        result["spatial:transform"] = transform
    if shape is not None:
        result["spatial:shape"] = shape
    if registration is not None:
        result["spatial:registration"] = registration
    validate(dict(result))
    return result

insert

insert(
    attrs: dict[str, Any],
    data: SpatialAttrs,
    *,
    overwrite: bool = False
) -> dict[str, Any]

Insert spatial convention metadata into an attributes dict.

Source code in src/zarr_cm/spatial.py

def insert(
    attrs: dict[str, Any], data: SpatialAttrs, *, overwrite: bool = False
) -> dict[str, Any]:
    """Insert spatial convention metadata into an attributes dict."""
    return insert_convention(attrs, CMO, dict(data), overwrite=overwrite)

extract

extract(
    attrs: dict[str, Any],
) -> tuple[dict[str, Any], SpatialAttrs]

Extract spatial convention metadata from an attributes dict.

Source code in src/zarr_cm/spatial.py

def extract(
    attrs: dict[str, Any],
) -> tuple[dict[str, Any], SpatialAttrs]:
    """Extract spatial convention metadata from an attributes dict."""
    remaining, convention_data = extract_convention(
        attrs,
        CONVENTION_KEYS,
        lambda cmo: cmo.get("uuid") == UUID,
    )
    return remaining, SpatialAttrs(**convention_data)  # type: ignore[typeddict-item]

validate

validate(data: dict[str, Any]) -> SpatialAttrs

Validate spatial convention data.

Source code in src/zarr_cm/spatial.py

def validate(data: dict[str, Any]) -> SpatialAttrs:
    """Validate spatial convention data."""
    if "spatial:dimensions" not in data:
        msg = "'spatial:dimensions' is required"
        raise ValueError(msg)

    for key, valid in _VALID_LENGTHS.items():
        if key in data:
            n = len(data[key])
            if n not in valid:
                msg = f"'{key}' must have {' or '.join(str(v) for v in valid)} items, got {n}"
                raise ValueError(msg)

    if (
        "spatial:registration" in data
        and data["spatial:registration"] not in _VALID_REGISTRATIONS
    ):
        msg = f"'spatial:registration' must be one of {_VALID_REGISTRATIONS}, got {data['spatial:registration']!r}"
        raise ValueError(msg)
    return data  # type: ignore[return-value]

multiscales

zarr_cm.multiscales

multiscales convention: https://github.com/zarr-conventions/multiscales

UUID module-attribute

UUID: Final = 'd35379db-88df-4056-af3a-620245f8e347'

SCHEMA_URL module-attribute

SCHEMA_URL: Final = (
    "https://raw.githubusercontent.com/zarr-conventions/multiscales/refs/tags/v1/schema.json"
)

SPEC_URL module-attribute

SPEC_URL: Final = (
    "https://github.com/zarr-conventions/multiscales/blob/v1/README.md"
)

CMO module-attribute

CMO: Final[ConventionMetadataObject] = {
    "uuid": UUID,
    "schema_url": SCHEMA_URL,
    "spec_url": SPEC_URL,
    "name": "multiscales",
    "description": "Multiscale layout of zarr datasets",
}

CONVENTION_KEYS module-attribute

CONVENTION_KEYS: Final = {'multiscales'}

Transform

Bases: TypedDict

Coordinate transformation with scale and translation.

Source code in src/zarr_cm/multiscales.py

class Transform(TypedDict):
    """Coordinate transformation with scale and translation."""

    scale: NotRequired[list[float]]
    translation: NotRequired[list[float]]

scale instance-attribute

scale: NotRequired[list[float]]

translation instance-attribute

translation: NotRequired[list[float]]

LayoutObject

Bases: TypedDict

A single resolution level in a multiscale pyramid.

Source code in src/zarr_cm/multiscales.py

class LayoutObject(TypedDict):
    """A single resolution level in a multiscale pyramid."""

    asset: str
    derived_from: NotRequired[str]
    transform: NotRequired[Transform]
    resampling_method: NotRequired[str]

asset instance-attribute

asset: str

derived_from instance-attribute

derived_from: NotRequired[str]

transform instance-attribute

transform: NotRequired[Transform]

resampling_method instance-attribute

resampling_method: NotRequired[str]

MultiscalesAttrs

Bases: TypedDict

Multiscale pyramid layout and metadata.

Source code in src/zarr_cm/multiscales.py

class MultiscalesAttrs(TypedDict):
    """Multiscale pyramid layout and metadata."""

    layout: list[LayoutObject]
    resampling_method: NotRequired[str]

layout instance-attribute

layout: list[LayoutObject]

resampling_method instance-attribute

resampling_method: NotRequired[str]

MultiscalesConventionAttrs

Bases: TypedDict

Attributes dict containing multiscales convention metadata.

Source code in src/zarr_cm/multiscales.py

class MultiscalesConventionAttrs(TypedDict):
    """Attributes dict containing multiscales convention metadata."""

    zarr_conventions: list[ConventionMetadataObject]
    multiscales: MultiscalesAttrs

zarr_conventions instance-attribute

zarr_conventions: list[ConventionMetadataObject]

multiscales instance-attribute

multiscales: MultiscalesAttrs

create

create(
    *,
    layout: list[LayoutObject],
    resampling_method: str | None = None
) -> MultiscalesAttrs

Create a MultiscalesAttrs dict from keyword arguments.

Source code in src/zarr_cm/multiscales.py

def create(
    *,
    layout: list[LayoutObject],
    resampling_method: str | None = None,
) -> MultiscalesAttrs:
    """Create a ``MultiscalesAttrs`` dict from keyword arguments."""
    result = MultiscalesAttrs(layout=layout)
    if resampling_method is not None:
        result["resampling_method"] = resampling_method
    validate(dict(result))
    return result

insert

insert(
    attrs: dict[str, Any],
    data: MultiscalesAttrs,
    *,
    overwrite: bool = False
) -> dict[str, Any]

Insert multiscales convention metadata into an attributes dict.

Source code in src/zarr_cm/multiscales.py

def insert(
    attrs: dict[str, Any], data: MultiscalesAttrs, *, overwrite: bool = False
) -> dict[str, Any]:
    """Insert multiscales convention metadata into an attributes dict."""
    return insert_convention(
        attrs, CMO, {"multiscales": dict(data)}, overwrite=overwrite
    )

extract

extract(
    attrs: dict[str, Any],
) -> tuple[dict[str, Any], MultiscalesAttrs]

Extract multiscales convention metadata from an attributes dict.

Source code in src/zarr_cm/multiscales.py

def extract(
    attrs: dict[str, Any],
) -> tuple[dict[str, Any], MultiscalesAttrs]:
    """Extract multiscales convention metadata from an attributes dict."""
    remaining, convention_data = extract_convention(
        attrs,
        CONVENTION_KEYS,
        lambda cmo: cmo.get("uuid") == UUID,
    )
    if not convention_data:
        return remaining, MultiscalesAttrs(layout=[])
    if "multiscales" not in convention_data:
        msg = "Extracted convention data does not contain 'multiscales' key"
        raise KeyError(msg)
    return remaining, MultiscalesAttrs(**convention_data["multiscales"])  # type: ignore[typeddict-item]

validate

validate(data: dict[str, Any]) -> MultiscalesAttrs

Validate multiscales convention data.

layout must have at least one item, and each layout entry that has derived_from must also have transform.

Source code in src/zarr_cm/multiscales.py

def validate(data: dict[str, Any]) -> MultiscalesAttrs:
    """Validate multiscales convention data.

    ``layout`` must have at least one item, and each layout entry
    that has ``derived_from`` must also have ``transform``.
    """
    if "layout" not in data:
        msg = "'layout' is required"
        raise ValueError(msg)

    if len(data["layout"]) < 1:
        msg = "'layout' must have at least one item"
        raise ValueError(msg)

    for i, entry in enumerate(data["layout"]):
        if "derived_from" in entry and "transform" not in entry:
            msg = f"layout[{i}] has 'derived_from' but is missing 'transform'"
            raise ValueError(msg)
    return data  # type: ignore[return-value]

license

zarr_cm.license

license convention: https://github.com/clbarnes/zarr-convention-license

UUID module-attribute

UUID: Final = 'b77365e5-2b0c-4141-b917-c03b7c68e935'

SCHEMA_URL module-attribute

SCHEMA_URL: Final = (
    "https://raw.githubusercontent.com/clbarnes/zarr-convention-license/refs/tags/v1/schema.json"
)

SPEC_URL module-attribute

SPEC_URL: Final = (
    "https://github.com/clbarnes/zarr-convention-license/blob/v1/README.md"
)

CMO module-attribute

CMO: Final[ConventionMetadataObject] = {
    "uuid": UUID,
    "schema_url": SCHEMA_URL,
    "spec_url": SPEC_URL,
    "name": "license",
    "description": "License specifier for Zarr data",
}

CONVENTION_KEYS module-attribute

CONVENTION_KEYS: Final = {'license'}

LicenseAttrs

Bases: TypedDict

License metadata for a Zarr node.

Source code in src/zarr_cm/license.py

class LicenseAttrs(TypedDict):
    """License metadata for a Zarr node."""

    spdx: NotRequired[str]
    url: NotRequired[str]
    text: NotRequired[str]
    file: NotRequired[str]
    path: NotRequired[str]

spdx instance-attribute

spdx: NotRequired[str]

url instance-attribute

url: NotRequired[str]

text instance-attribute

text: NotRequired[str]

file instance-attribute

file: NotRequired[str]

path instance-attribute

path: NotRequired[str]

LicenseConventionAttrs

Bases: TypedDict

Attributes dict containing license convention metadata.

Source code in src/zarr_cm/license.py

class LicenseConventionAttrs(TypedDict):
    """Attributes dict containing license convention metadata."""

    zarr_conventions: list[ConventionMetadataObject]
    license: LicenseAttrs

zarr_conventions instance-attribute

zarr_conventions: list[ConventionMetadataObject]

license instance-attribute

license: LicenseAttrs

create

create(
    *,
    spdx: str | None = None,
    url: str | None = None,
    text: str | None = None,
    file: str | None = None,
    path: str | None = None
) -> LicenseAttrs

Create a LicenseAttrs dict from keyword arguments.

Source code in src/zarr_cm/license.py

def create(
    *,
    spdx: str | None = None,
    url: str | None = None,
    text: str | None = None,
    file: str | None = None,
    path: str | None = None,
) -> LicenseAttrs:
    """Create a ``LicenseAttrs`` dict from keyword arguments."""
    result = LicenseAttrs()
    if spdx is not None:
        result["spdx"] = spdx
    if url is not None:
        result["url"] = url
    if text is not None:
        result["text"] = text
    if file is not None:
        result["file"] = file
    if path is not None:
        result["path"] = path
    validate(dict(result))
    return result

insert

insert(
    attrs: dict[str, Any],
    data: LicenseAttrs,
    *,
    overwrite: bool = False
) -> dict[str, Any]

Insert license convention metadata into an attributes dict.

Source code in src/zarr_cm/license.py

def insert(
    attrs: dict[str, Any], data: LicenseAttrs, *, overwrite: bool = False
) -> dict[str, Any]:
    """Insert license convention metadata into an attributes dict."""
    return insert_convention(attrs, CMO, {"license": dict(data)}, overwrite=overwrite)

extract

extract(
    attrs: dict[str, Any],
) -> tuple[dict[str, Any], LicenseAttrs]

Extract license convention metadata from an attributes dict.

Source code in src/zarr_cm/license.py

def extract(
    attrs: dict[str, Any],
) -> tuple[dict[str, Any], LicenseAttrs]:
    """Extract license convention metadata from an attributes dict."""
    remaining, convention_data = extract_convention(
        attrs,
        CONVENTION_KEYS,
        lambda cmo: cmo.get("uuid") == UUID,
    )
    if not convention_data:
        return remaining, LicenseAttrs()
    if "license" not in convention_data:
        msg = "Extracted convention data does not contain 'license' key"
        raise KeyError(msg)
    return remaining, LicenseAttrs(**convention_data["license"])  # type: ignore[typeddict-item]

validate

validate(data: dict[str, Any]) -> LicenseAttrs

Validate license convention data.

At least one of spdx, url, text, file, or path must be present.

Source code in src/zarr_cm/license.py

def validate(data: dict[str, Any]) -> LicenseAttrs:
    """Validate license convention data.

    At least one of ``spdx``, ``url``, ``text``, ``file``, or ``path``
    must be present.
    """
    if not any(k in data for k in ("spdx", "url", "text", "file", "path")):
        msg = "At least one of 'spdx', 'url', 'text', 'file', or 'path' must be present"
        raise ValueError(msg)
    return data  # type: ignore[return-value]

uom

zarr_cm.uom

uom convention: https://github.com/clbarnes/zarr-convention-uom

UUID module-attribute

UUID: Final = '3bbe438d-df37-49fe-8e2b-739296d46dfb'

SCHEMA_URL module-attribute

SCHEMA_URL: Final = (
    "https://raw.githubusercontent.com/clbarnes/zarr-convention-uom/refs/tags/v1/schema.json"
)

SPEC_URL module-attribute

SPEC_URL: Final = (
    "https://github.com/clbarnes/zarr-convention-uom/blob/v1/README.md"
)

CMO module-attribute

CMO: Final[ConventionMetadataObject] = {
    "uuid": UUID,
    "schema_url": SCHEMA_URL,
    "spec_url": SPEC_URL,
    "name": "uom",
    "description": "Units of measurement for Zarr arrays",
}

CONVENTION_KEYS module-attribute

CONVENTION_KEYS: Final = {'uom'}

UCUM

Bases: TypedDict

Unified Code for Units of Measurement information.

Source code in src/zarr_cm/uom.py

class UCUM(TypedDict):
    """Unified Code for Units of Measurement information."""

    unit: NotRequired[str]
    version: NotRequired[str]

unit instance-attribute

unit: NotRequired[str]

version instance-attribute

version: NotRequired[str]

UomAttrs

Bases: TypedDict

Unit of measurement metadata for a Zarr array.

Source code in src/zarr_cm/uom.py

class UomAttrs(TypedDict):
    """Unit of measurement metadata for a Zarr array."""

    ucum: UCUM
    description: NotRequired[str]

ucum instance-attribute

ucum: UCUM

description instance-attribute

description: NotRequired[str]

UomConventionAttrs

Bases: TypedDict

Attributes dict containing uom convention metadata.

Source code in src/zarr_cm/uom.py

class UomConventionAttrs(TypedDict):
    """Attributes dict containing uom convention metadata."""

    zarr_conventions: list[ConventionMetadataObject]
    uom: UomAttrs

zarr_conventions instance-attribute

zarr_conventions: list[ConventionMetadataObject]

uom instance-attribute

uom: UomAttrs

create

create(
    *, ucum: UCUM, description: str | None = None
) -> UomAttrs

Create a UomAttrs dict from keyword arguments.

Source code in src/zarr_cm/uom.py

def create(
    *,
    ucum: UCUM,
    description: str | None = None,
) -> UomAttrs:
    """Create a ``UomAttrs`` dict from keyword arguments."""
    result = UomAttrs(ucum=ucum)
    if description is not None:
        result["description"] = description
    validate(dict(result))
    return result

insert

insert(
    attrs: dict[str, Any],
    data: UomAttrs,
    *,
    overwrite: bool = False
) -> dict[str, Any]

Insert uom convention metadata into an attributes dict.

Source code in src/zarr_cm/uom.py

def insert(
    attrs: dict[str, Any], data: UomAttrs, *, overwrite: bool = False
) -> dict[str, Any]:
    """Insert uom convention metadata into an attributes dict."""
    return insert_convention(attrs, CMO, {"uom": dict(data)}, overwrite=overwrite)

extract

extract(
    attrs: dict[str, Any],
) -> tuple[dict[str, Any], UomAttrs]

Extract uom convention metadata from an attributes dict.

Source code in src/zarr_cm/uom.py

def extract(
    attrs: dict[str, Any],
) -> tuple[dict[str, Any], UomAttrs]:
    """Extract uom convention metadata from an attributes dict."""
    remaining, convention_data = extract_convention(
        attrs,
        CONVENTION_KEYS,
        lambda cmo: cmo.get("uuid") == UUID,
    )
    if not convention_data:
        return remaining, UomAttrs(ucum={})
    if "uom" not in convention_data:
        msg = "Extracted convention data does not contain 'uom' key"
        raise KeyError(msg)
    return remaining, UomAttrs(**convention_data["uom"])  # type: ignore[typeddict-item]

validate

validate(data: dict[str, Any]) -> UomAttrs

Validate uom convention data.

ucum must be present.

Source code in src/zarr_cm/uom.py

def validate(data: dict[str, Any]) -> UomAttrs:
    """Validate uom convention data.

    ``ucum`` must be present.
    """
    if "ucum" not in data:
        msg = "'ucum' is required"
        raise ValueError(msg)
    return data  # type: ignore[return-value]