ak.from_buffers

Defined in awkward.operations.convert on line 4991.

ak.from_buffers(form, length, container, partition_start=0, key_format='part{partition}-{form_key}-{attribute}', lazy=False, lazy_cache='new', lazy_cache_key=None, highlevel=True, behavior=None)
Parameters
  • form (ak.forms.Form or str/dict equivalent) – The form of the Awkward Array to reconstitute from named buffers.

  • length (int or iterable of int) – Length of the array to reconstitute as a non-partitioned array or the lengths (plural) of partitions in a partitioned array.

  • container (Mapping, such as dict) – The str → Python buffers that represent the decomposed Awkward Array. This container is only assumed to have a __getitem__ method that accepts strings as keys.

  • partition_start (int) – First (or only) partition number to get from the container.

  • key_format (str or callable) – Python format string containing "{partition}", "{form_key}", and/or "{attribute}" or a function that takes these as keyword arguments and returns a string to use as keys for buffers in the container. The partition is a partition number (non-negative integer, passed as a string), the form_key is a string associated with each node in the Form, and the attribute is a hard-coded string representing the buffer’s function (e.g. "data", "offsets", "index").

  • lazy (bool) – If True, read the array or its partitions on demand (as ak.layout.VirtualArray, possibly in ak.partition.PartitionedArray if num_partitions is not None); if False, read all requested data immediately. Any RecordArray child nodes will additionally be read on demand.

  • lazy_cache (None, "new", or MutableMapping) – If lazy, pass this cache to the VirtualArrays. If “new”, a new dict (keep-forever cache) is created. If None, no cache is used.

  • lazy_cache_key (None or str) – If lazy, pass this cache_key to the VirtualArrays. If None, a process-unique string is constructed.

  • highlevel (bool) – If True, return an ak.Array; otherwise, return a low-level ak.layout.Content subclass.

  • behavior (None or dict) – Custom ak.behavior for the output array, if high-level.

Reconstitutes an Awkward Array from a Form, length, and a collection of memory buffers, so that data can be losslessly read from file formats and storage devices that only map names to binary blobs (such as a filesystem directory).

The first three arguments of this function are the return values of ak.to_buffers, so a full round-trip is

>>> reconstituted = ak.from_buffers(*ak.to_buffers(original))

The container argument lets you specify your own Mapping, which might be an interface to some storage format or device (e.g. h5py). It’s okay if the container dropped NumPy’s dtype and shape information, leaving raw bytes, since dtype and shape can be reconstituted from the ak.forms.NumpyForm.

The key_format should be the same as the one used in ak.to_buffers.

The arguments that begin with lazy_ are only needed if lazy is True. The lazy_cache and lazy_cache_key determine how the array or its partitions are cached after being read from the container (in a no-eviction dict attached to the output ak.Array as cache if not specified).

See ak.to_buffers for examples.