VLArray

Overview

VLArray is a variable-length array container backed by a single Blosc2 SChunk.

Each entry is stored as one compressed chunk:

• entries can be any serializable Python object

• items are serialized with msgpack before compression

• Blosc2 containers (NDArray, SChunk, VLArray, BatchArray, EmbedStore) are serialized transparently via to_cframe() / blosc2.from_cframe()

• structured Blosc2 reference objects (C2Array, LazyExpr, and LazyUDF backed by blosc2.dsl_kernel()) are also supported

VLArray is a good fit when you need:

• a persistent, compressed list of arbitrary Python objects

• per-item random access and mutation

• compact summary information via .info

Quick example

import blosc2

vl = blosc2.VLArray(urlpath="example.b2z", mode="w", contiguous=True)
vl.append({"x": 1, "y": 2})
vl.append([3, 4, 5])
vl.append("hello")

print(vl[0])  # {'x': 1, 'y': 2}
print(vl[1])  # [3, 4, 5]
print(len(vl))  # 3

reopened = blosc2.open("example.b2z", mode="r")
print(type(reopened).__name__)
print(reopened.info)

class blosc2.VLArray(chunksize: int | None = None, _from_schunk: SChunk | None = None, **kwargs: Any)

A variable-length array backed by an blosc2.SChunk.

Entries are serialized with msgpack before compression. Standard Python objects are supported, and Blosc2 containers such as blosc2.NDArray, blosc2.SChunk, blosc2.VLArray, blosc2.BatchArray, and blosc2.EmbedStore are serialized transparently via to_cframe() / blosc2.from_cframe().

Msgpack also supports structured Blosc2 reference objects. Currently this includes blosc2.C2Array, blosc2.LazyExpr, and blosc2.LazyUDF backed by blosc2.dsl_kernel(). Lazy expressions and supported lazy UDFs are serialized as recipes plus durable operand references, so only persistent local operands, blosc2.C2Array operands, and blosc2.DictStore members are supported. Purely in-memory operands are intentionally rejected. Plain Python blosc2.LazyUDF callables are not serialized by msgpack.

Attributes:

cbytes

chunksize

contiguous

cparams

cratio

dparams

info

Print information about this VLArray.

info_items

A list of tuples with summary information about this VLArray.

meta

nbytes

typesize

urlpath

vlmeta

Methods

append(value)	Append one value and return the new number of entries.
clear()	Remove all entries from the container.
copy(**kwargs)	Create a copy of the container with optional constructor overrides.
delete(index)	Delete the value at index and return the new number of entries.
extend(values)	Append all values from an iterable.
insert(index, value)	Insert one value at index and return the new number of entries.
pop([index])	Remove and return the value at index.

to_cframe

Constructors

__init__(chunksize: int | None = None, _from_schunk: SChunk | None = None, **kwargs: Any) → None

Item Interface

__getitem__(index: int) → Any

__setitem__(index: int, value: Any) → None

__delitem__(index: int) → None

__len__() → int

__iter__() → Iterator[Any]

Mutation

append(value: Any) → int

Append one value and return the new number of entries.

extend(values: object) → None

Append all values from an iterable.

insert(index: int, value: Any) → int

Insert one value at index and return the new number of entries.

delete(index: int) → int

Delete the value at index and return the new number of entries.

pop(index: int = -1) → Any

Remove and return the value at index.

clear() → None

Remove all entries from the container.

copy(**kwargs: Any) → VLArray

Create a copy of the container with optional constructor overrides.

Context Manager

__enter__() → VLArray

__exit__(exc_type, exc_val, exc_tb) → bool

Public Members

to_cframe() → bytes

Constructors

blosc2.vlarray_from_cframe(cframe: bytes, copy: bool = True) → VLArray

Deserialize a CFrame buffer into a VLArray.