z3fdb.custom_store_builder
==========================

.. py:module:: z3fdb.custom_store_builder


Classes
-------

.. autoapisummary::

   z3fdb.custom_store_builder._VArray
   z3fdb.custom_store_builder._VGroup
   z3fdb.custom_store_builder.CustomStoreBuilder


Module Contents
---------------

.. py:class:: _VArray

   .. py:attribute:: name
      :type:  str


   .. py:attribute:: parent
      :type:  _VGroup


   .. py:attribute:: builder
      :type:  pychunked_data_view.ChunkedDataViewBuilder


.. py:class:: _VGroup

   .. py:attribute:: parents
      :type:  list[_VGroup] | None


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: children
      :type:  list[_VGroup | _VArray]
      :value: []



   .. py:method:: _join_path(group: _VGroup) -> str
      :staticmethod:



   .. py:method:: __eq__(value: object) -> bool


   .. py:method:: descent(name: str) -> _VGroup

      Return the single child group called *name*.

      :raises ~z3fdb.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``.



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

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

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

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


   .. py:attribute:: _ROOT_KEY
      :value: ''



   .. py:attribute:: _config
      :value: None



   .. py:attribute:: _structure
      :type:  dict[str, _VArray]


   .. py:attribute:: _root


   .. py:method:: _merge_vgroup(vgroup: _VGroup) -> None

      Insert *vgroup* into the virtual group tree rooted at self._root.



   .. py:method:: _parse_path(path: str) -> list[str]
      :staticmethod:


      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
      :exc:`ValueError`.

      Examples::

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



   .. py:method:: _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.



   .. py:method:: 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

      Register a MARS request as a part of a virtual zarr array at *path*.

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

      :param 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.
      :param mars_request: MARS request as a dict mapping keys to values.
      :param axes: Axis definitions describing how the request dimensions map
                   to zarr array dimensions.
      :param extractor: Extractor configuration (``ExtractorType.Grib`` or
                        ``ExtractorType.GribJump``).



   .. py:method:: _existing_array(path: list[str] | None) -> pychunked_data_view.ChunkedDataViewBuilder

      Return the builder for an array already registered at *path*.

      Unlike :meth:`_build_structure` this never creates one. :meth:`extend_on_axis` and
      :meth:`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
      :meth:`build`.

      :param path: Path segments, or ``None`` for the root array.

      :returns: The builder registered at *path*.
      :rtype: ChunkedDataViewBuilder

      :raises ValueError: If no array is registered at *path*.



   .. py:method:: extend_on_axis(path: str | None, axis: int) -> None

      Declare the extension axis of the array at *path*.

      The array must already exist: call :meth:`add_part` for *path* first.

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

      :raises ValueError: If no array is registered at *path*.



   .. py:method:: fill_missing_value(path: str | None, value: float) -> None

      Set the fill value for the array at *path*.

      The array must already exist: call :meth:`add_part` for *path* first.

      :param path: Zarr-style path (same format as :meth:`add_part`). ``None`` refers to the
                   root array.
      :param 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*.



   .. py:method:: build() -> z3fdb._internal.zarr.FdbZarrStore

      Assemble all registered views into a read-only :class:`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``).