Add docs for new structured Blosc2 serialization

Author: FrancescAlted

doc/reference/batch_store.rst

@@ -31,6 +31,32 @@ BatchStore currently supports two serializers:
 - ``"arrow"``: optional and requires ``pyarrow``; mainly useful when data is
   already Arrow-shaped before ingestion
 
+For ``"msgpack"``, python-blosc2 supports both ordinary msgpack-safe Python
+values and selected Blosc2 objects.
+
+Blosc2 objects serialized by value via :meth:`to_cframe` /
+:func:`blosc2.from_cframe`:
+
+- ``NDArray``
+- ``SChunk``
+- ``VLArray``
+- ``BatchStore``
+- ``EmbedStore``
+
+Structured reference-style Blosc2 objects currently supported:
+
+- ``C2Array``
+- ``LazyExpr``
+
+``LazyExpr`` values preserve reference semantics and are serialized as a recipe
+plus durable operand references. Supported operands are:
+
+- persistent local Blosc2 operands reopenable from ``urlpath``
+- remote ``C2Array`` operands
+- ``DictStore`` members reopenable from ``(.b2d|.b2z, key)``
+
+Purely in-memory operands are intentionally not supported.
+
 Quick example
 -------------
 

doc/reference/index.rst

@@ -6,6 +6,7 @@ API Reference
 
     classes
     save_load
+    msgpack_serialization
     storage
     array_operations
     utilities

src/blosc2/batch_store.py

@@ -171,8 +171,13 @@ class BatchStore:
         containers such as :class:`blosc2.NDArray`, :class:`blosc2.SChunk`,
         :class:`blosc2.VLArray`, :class:`blosc2.BatchStore`, and
         :class:`blosc2.EmbedStore`, which are serialized transparently via
-        :meth:`to_cframe` / :func:`blosc2.from_cframe`. ``"arrow"`` is optional
-        and requires ``pyarrow``.
+        :meth:`to_cframe` / :func:`blosc2.from_cframe`. Msgpack also supports
+        structured Blosc2 reference objects, currently
+        :class:`blosc2.C2Array` and :class:`blosc2.LazyExpr`. Lazy expressions
+        preserve reference semantics, so only persistent local operands,
+        :class:`blosc2.C2Array` operands, and :class:`blosc2.DictStore`
+        members are supported; purely in-memory operands are rejected.
+        ``"arrow"`` is optional and requires ``pyarrow``.
     _from_schunk : blosc2.SChunk, optional
         Internal hook used when reopening an already-tagged BatchStore.
     **kwargs

src/blosc2/vlarray.py

@@ -36,6 +36,13 @@ class VLArray:
     :class:`blosc2.NDArray`, :class:`blosc2.SChunk`, :class:`blosc2.VLArray`,
     :class:`blosc2.BatchStore`, and :class:`blosc2.EmbedStore` are serialized
     transparently via :meth:`to_cframe` / :func:`blosc2.from_cframe`.
+
+    Msgpack also supports structured Blosc2 reference objects. Currently this
+    includes :class:`blosc2.C2Array` and :class:`blosc2.LazyExpr`. Lazy
+    expressions are serialized as recipes plus durable operand references, so
+    only persistent local operands, :class:`blosc2.C2Array` operands, and
+    :class:`blosc2.DictStore` members are supported. Purely in-memory operands
+    are intentionally rejected.
     """
 
     @staticmethod