Items and item groups

Each data item that can be communicated over SPEAD is described by a spead2.Descriptor. Items combine a descriptor with a current value, and a version number that is used to detect which items have been changed (either in the library when transmitting, or by the user when receiving).

class spead2.Descriptor(id, name, description, shape, dtype=None, order='C', format=None)

Metadata for a SPEAD item.

There are a number of restrictions on the parameters, which will cause ValueError to be raised if violated:

  • At most one element of shape can be None.

  • Exactly one of dtype and format must be non-None.

  • If dtype is specified, shape cannot have any unknown dimensions.

  • If format is specified, order must be ‘C’

  • If dtype is specified, it cannot contain objects, and must have positive size.

Parameters:

  • id (int) – SPEAD item ID

  • name (str) – Short item name, suitable for use as a key

  • description (str) – Long item description

  • shape (sequence) – Dimensions, with None indicating a variable-size dimension

  • dtype (numpy data type, optional) – Data type, or None if format will be used instead

  • order ({'C', 'F'}) – Indicates C-order or Fortran-order storage

  • format (list of pairs, optional) – Structure fields for generic (non-numpy) type. Each element of the list is a tuple of field code and bit length.

itemsize_bits

Number of bits per element

is_variable_size()

Determine whether any element of the size is dynamic

dynamic_shape(max_elements)

Determine the dynamic shape, given incoming data that is big enough to hold max_elements elements.

compatible_shape(shape)

Determine whether shape is compatible with the (possibly variable-sized) shape for this descriptor

class spead2.Item(*args, **kwargs, value=None)

A SPEAD item with a value and a version number.

Parameters:

value (object, optional) – Initial value

value

Current value. Assigning to this will increment the version number. Assigning None will raise ValueError because there is no way to encode this using SPEAD.

Warning

If you modify a mutable value in-place, the change will not be detected, and by default HeapGenerator.get_heap() will not add the item to the heap it returns. In this case, either manually increment the version number, reassign the value, or pass data="all" to get_heap().

version

Version number

class spead2.ItemGroup

Items are collected into sets called item groups, which can be indexed by either item ID or item name.

There are some subtleties with respect to re-issued item descriptors. There are two cases:

  1. The item descriptor is identical to a previous seen one. In this case, no action is taken.

  2. Otherwise, any existing items with the same name or ID (which could be two different items) are dropped, the new item is added, and its value becomes None. The version is set to be higher than version on an item that was removed, so that consumers who only check the version will detect the change.

add_item(*args, **kwargs)

Add a new item to the group. The parameters are used to construct an Item. If id is None, it will be automatically populated with an ID that is not already in use.

See the class documentation for the behaviour when the name or ID collides with an existing one. In addition, if the item descriptor is identical to an existing one and a value, this value is assigned to the existing item.

keys()

Item names

values()

Item values

items()

Dictionary style (name, value) pairs

ids()

Item IDs

update(heap, new_order='=')

Update the item descriptors and items from an incoming heap.

Parameters:

  • heap (spead2.recv.Heap) – Incoming heap

  • new_order (str) – Byte ordering to coerce new byte arrays into. The default is to force arrays to native byte order. Use '|' to keep whatever byte order was in the heap. See np.dtype.newbyteorder() for the full list of options.

Returns:

Items that have been updated from this heap, indexed by name

Return type:

dict