z3fdb.custom_store_builder#

Classes#

`_VArray`
`_VGroup`
`CustomStoreBuilder`	Builds a zarr store backed by FDB with an arbitrary group/array hierarchy.

Module Contents#

class _VArray#

name: str#

parent: _VGroup#

builder: pychunked_data_view.ChunkedDataViewBuilder#

class _VGroup#

parents: list[_VGroup] | None#

name: str#

children: list[_VGroup | _VArray] = []#

static _join_path(group: _VGroup) → str#

__eq__(value: object) → bool#

descent(name: str) → _VGroup#

Return the single child group called name.

Raises:: Z3fdbError – If there is not exactly one. Names are unique by construction, so this is an internal invariant, a bare assert would vanish under python -O.

class CustomStoreBuilder(fdb_config_file: pathlib.Path | None = None)#

Builds a zarr store backed by FDB with an arbitrary group/array hierarchy.

Use add_part() to register one or more MARS request parts (each producing a virtual zarr array) at arbitrary nested paths, then call build() to obtain a read-only FdbZarrStore that zarr can open directly.

Parameters:: fdb_config_file – Optional path to an FDB config file. None (default) lets FDB resolve its configuration from the environment.

_ROOT_KEY = ''#

_config = None#

_structure: dict[str, _VArray]#

_root#

_merge_vgroup(vgroup: _VGroup) → None#: Insert vgroup into the virtual group tree rooted at self._root.

static _parse_path(path: str) → list[str]#

Convert a zarr-style path string to a list of name segments.

Leading and trailing slashes are stripped; multiple consecutive slashes are collapsed. An empty result (e.g. "" or "/") raises ValueError.

Examples:

"sfc/wind"   -> ["sfc", "wind"]
"/sfc/wind"  -> ["sfc", "wind"]   # leading slash accepted
"t2m"        -> ["t2m"]           # top-level array
""           -> ValueError
"/"          -> ValueError

_build_structure(path: list[str] | None) → pychunked_data_view.ChunkedDataViewBuilder#

Return the ChunkedDataViewBuilder for path, creating it if needed.

Pass None to obtain the builder for the root array.

add_part(path: str | None, mars_request: pychunked_data_view.MarsSelection, axes: list[pychunked_data_view.AxisDefinition], extractor: pychunked_data_view.ExtractorType.Grib | pychunked_data_view.ExtractorType.GribJump) → None#

Calling this method multiple times with the same path adds further parts to the same array (equivalent to ChunkedDataViewBuilder.add_part() called repeatedly).

Parameters:

path – Zarr-style path of the array in the hierarchy, e.g. "group_a/sub_group/my_array" or "t2m" for a top-level (no-group) array. A leading / is accepted and ignored. Pass None to place the array at the store root (accessible via zarr.open_array(store)); this is mutually exclusive with any named path.
mars_request – MARS request as a dict mapping keys to values.
axes – Axis definitions describing how the request dimensions map to zarr array dimensions.
extractor – Extractor configuration (ExtractorType.Grib or ExtractorType.GribJump).

_existing_array(path: list[str] | None) → pychunked_data_view.ChunkedDataViewBuilder#

Return the builder for an array already registered at path.

Unlike _build_structure() this never creates one. extend_on_axis() and fill_missing_value() configure an existing array, so an unknown path is a mistake – usually a typo – rather than a request for a new empty array. Creating one silently would only surface much later, as “must add at least one part” from build().

Parameters:: path – Path segments, or None for the root array.
Returns:: The builder registered at path.
Return type:: ChunkedDataViewBuilder
Raises:: ValueError – If no array is registered at path.

extend_on_axis(path: str | None, axis: int) → None#

Declare the extension axis of the array at path.

The array must already exist: call add_part() for path first.

Parameters:

path – Zarr-style path (same format as add_part()). None refers to the root array.
axis – Zero-based index of the axis to extend.

Raises:

ValueError – If no array is registered at path.

fill_missing_value(path: str | None, value: float) → None#

Set the fill value for the array at path.

The array must already exist: call add_part() for path first.

Parameters:

path – Zarr-style path (same format as add_part()). None refers to the root array.
value – Value written into positions flagged as missing by the GRIB bitmap. Also becomes the zarr array’s fill_value. Defaults to NaN when not set.

Raises:

ValueError – If no array is registered at path.

build() → z3fdb._internal.zarr.FdbZarrStore#

Assemble all registered views into a read-only FdbZarrStore.

Returns:: A zarr-compatible store that can be opened with zarr.open(store) (group hierarchy) or zarr.open_array(store) (when built from a single root array registered via path=None).