Group

zarrista.Group

A Zarr group.

attrs property

attrs: dict[str, JSONValue]

The group's user attributes as a dict.

consolidated_metadata property

consolidated_metadata: ZarrV3ConsolidatedMetadataJSON | None

The consolidated metadata, if present in the group metadata.

metadata property

metadata: ZarrV3GroupMetadataJSON

The group's full Zarr v3 metadata.

path property

path: str

The group's path in the store.

storage property

storage: SyncStore

The store that backs this group.

__getitem__

__getitem__(name: str) -> Array | Group

Open a direct child array or group by name.

Parameters:

• name (str) –

  The name of the direct child.

Returns:

• Array | Group –

  The child array or group.

Raises:

• KeyError –

  If the group has no direct child with that name.

array_keys

array_keys() -> list[str]

Return the names of the direct child arrays.

Returns:

• list[str] –

  The name of each direct child array.

child

child(name: str) -> Array | Group

Open a direct child array or group by name.

Parameters:

• name (str) –

  The name of the direct child.

Returns:

• Array | Group –

  The child array or group.

Raises:

• KeyError –

  If the group has no direct child with that name.

child_array_paths

child_array_paths() -> list[str]

Return the full paths of the group's direct child arrays.

Returns:

• list[str] –

  The full path of each direct child array.

child_arrays

child_arrays() -> list[Array]

Return the direct child arrays of the group.

Returns:

• list[Array] –

  Each direct child array.

child_group_paths

child_group_paths() -> list[str]

Return the full paths of the group's direct child groups.

Returns:

• list[str] –

  The full path of each direct child group.

child_groups

child_groups() -> list[Group]

Return the direct child groups of the group.

Returns:

• list[Group] –

  Each direct child group.

child_paths

child_paths() -> list[str]

Return the full paths of the group's direct children.

Returns:

• list[str] –

  The full path of each direct child.

erase_metadata

erase_metadata() -> None

Erase the group metadata from the store.

This succeeds if the metadata does not exist.

group_keys

group_keys() -> list[str]

Return the names of the direct child groups.

Returns:

• list[str] –

  The name of each direct child group.

open staticmethod

open(store: SyncStore, path: str = '/') -> Group

Open the group stored at path in store.

Parameters:

• store (SyncStore) –

  The store that holds the group.

• path (str, default: '/' ) –

  The absolute path of the group in the store.

Returns:

• Group –

  The group at path.

Raises:

• GroupCreateError –

  If the store holds no group metadata at path.

• ValueError –

  If path is not a valid absolute node path.

store_metadata

store_metadata() -> None

Write the group metadata to the store.

This overwrites any metadata that exists at the group's path.

traverse

traverse() -> list[Array | Group]

Return every node under the group, recursively.

Returns:

• list[Array | Group] –

  Each array and group below this group, at any depth.

with_attrs

with_attrs(attrs: Mapping[str, JSONValue]) -> Group

Return a new group reference with attrs, leaving this one unchanged.

The new attributes replace the old ones. Any key that attrs does not contain is gone from the new group reference. To keep the existing attributes, merge them yourself:

group = group.with_attrs({**group.attrs, "title": "root"})

Nothing is persisted to the store. Call Group.store_metadata to persist the new attributes to the store:

group = group.with_attrs({"title": "root"})
group.store_metadata()

This group is unaffected and remains usable; it simply goes on describing the old attributes. Rebinding, as above, is the intended usage.

Parameters:

• attrs (Mapping[str, JSONValue]) –

  The user attributes of the new group reference. Each value must be JSON-serializable.

Returns:

• Group –

  A new group reference that uses attrs.

Raises:

• TypeError –

  If a value in attrs is not JSON-serializable.

with_consolidated_metadata

with_consolidated_metadata(
    consolidated_metadata: ZarrV3ConsolidatedMetadataJSON | None,
) -> Group

Return a new group reference with consolidated_metadata.

This group is unchanged. Pass None to remove the consolidated metadata from the new group reference.

This does not build the consolidated metadata. It stores the block that you give it, and it does not check the block against the hierarchy.

Nothing is persisted to the store. Call Group.store_metadata to persist the new block to the store:

group = group.with_consolidated_metadata(consolidated_metadata)
group.store_metadata()

Parameters:

• consolidated_metadata (ZarrV3ConsolidatedMetadataJSON | None) –

  The consolidated metadata of the new group reference, or None to remove it. The block has the same shape that Group.consolidated_metadata returns.

Returns:

• Group –

  A new group reference that uses consolidated_metadata.

Raises:

• ValueError –

  If the group holds Zarr V2 metadata. Consolidated metadata is a Zarr V3 convention.

zarrista.AsyncGroup

A Zarr group backed by an async store.

attrs property

attrs: dict[str, JSONValue]

The group's user attributes as a dict.

consolidated_metadata property

consolidated_metadata: ZarrV3ConsolidatedMetadataJSON | None

The consolidated metadata, if present in the group metadata.

metadata property

metadata: ZarrV3GroupMetadataJSON

The group's full Zarr v3 metadata.

path property

path: str

The group's path in the store.

storage property

storage: AsyncStore

The store that backs this group.

array_keys async

array_keys() -> list[str]

Return the names of the direct child arrays.

Returns:

• list[str] –

  The name of each direct child array.

child async

child(name: str) -> AsyncArray | AsyncGroup

Open a direct child array or group by name.

Parameters:

• name (str) –

  The name of the direct child.

Returns:

• AsyncArray | AsyncGroup –

  The child array or group.

Raises:

• KeyError –

  If the group has no direct child with that name.

child_array_paths async

child_array_paths() -> list[str]

Return the full paths of the group's direct child arrays.

Returns:

• list[str] –

  The full path of each direct child array.

child_arrays async

child_arrays() -> list[AsyncArray]

Return the direct child arrays of the group.

Returns:

• list[AsyncArray] –

  Each direct child array.

child_group_paths async

child_group_paths() -> list[str]

Return the full paths of the group's direct child groups.

Returns:

• list[str] –

  The full path of each direct child group.

child_groups async

child_groups() -> list[AsyncGroup]

Return the direct child groups of the group.

Returns:

• list[AsyncGroup] –

  Each direct child group.

child_paths async

child_paths() -> list[str]

Return the full paths of the group's direct children.

Returns:

• list[str] –

  The full path of each direct child.

erase_metadata async

erase_metadata() -> None

Erase the group metadata from the store.

This succeeds if the metadata does not exist.

group_keys async

group_keys() -> list[str]

Return the names of the direct child groups.

Returns:

• list[str] –

  The name of each direct child group.

open async staticmethod

open(store: AsyncStore, path: str = '/') -> AsyncGroup

Open the group stored at path in store.

Parameters:

• store (AsyncStore) –

  The store that holds the group. This is either an obstore ObjectStore or an icechunk Session.

• path (str, default: '/' ) –

  The absolute path of the group in the store.

Returns:

• AsyncGroup –

  The group at path.

Raises:

• GroupCreateError –

  If the store holds no group metadata at path.

• ValueError –

  If path is not a valid absolute node path.

store_metadata async

store_metadata() -> None

Write the group metadata to the store.

This overwrites any metadata that exists at the group's path.

traverse async

traverse() -> list[AsyncArray | AsyncGroup]

Return every node under the group, recursively.

Returns:

• list[AsyncArray | AsyncGroup] –

  Each array and group below this group, at any depth.

with_attrs

with_attrs(attrs: Mapping[str, JSONValue]) -> AsyncGroup

Return a new group reference with attrs, leaving this one unchanged.

The new attributes replace the old ones. Any key that attrs does not contain is gone from the new group reference. To keep the existing attributes, merge them yourself:

group = group.with_attrs({**group.attrs, "title": "root"})

Nothing is persisted to the store. Call AsyncGroup.store_metadata to persist the new attributes to the store:

group = group.with_attrs({"title": "root"})
await group.store_metadata()

This group is unaffected and remains usable; it simply goes on describing the old attributes. Rebinding, as above, is the intended usage.

Parameters:

• attrs (Mapping[str, JSONValue]) –

  The user attributes of the new group reference. Each value must be JSON-serializable.

Returns:

• AsyncGroup –

  A new group reference that uses attrs.

Raises:

• TypeError –

  If a value in attrs is not JSON-serializable.

with_consolidated_metadata

with_consolidated_metadata(
    consolidated_metadata: ZarrV3ConsolidatedMetadataJSON | None,
) -> AsyncGroup

Return a new group reference with consolidated_metadata.

This group is unchanged. Pass None to remove the consolidated metadata from the new group reference.

This does not build the consolidated metadata. It stores the block that you give it, and it does not check the block against the hierarchy.

Nothing is persisted to the store. Call AsyncGroup.store_metadata to persist the new block to the store:

group = group.with_consolidated_metadata(consolidated_metadata)
await group.store_metadata()

Parameters:

• consolidated_metadata (ZarrV3ConsolidatedMetadataJSON | None) –

  The consolidated metadata of the new group reference, or None to remove it. The block has the same shape that AsyncGroup.consolidated_metadata returns.

Returns:

• AsyncGroup –

  A new group reference that uses consolidated_metadata.

Raises:

• ValueError –

  If the group holds Zarr V2 metadata. Consolidated metadata is a Zarr V3 convention.