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 – SPEAD item ID

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

  • description – Long item description

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

  • dtype – Data type, or None if format will be used instead

  • order – Indicates C-order or Fortran-order storage

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

Type id

int

Type name

str

Type description

str

Type shape

sequence

Type dtype

numpy data type, optional

Type order

{‘C’, ‘F’}

Type format

list of pairs, optional

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 – Initial value

Type value

object, optional

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 the new value will not be transmitted. In this case, either manually increment the version number, or reassign the value.

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 – Incoming heap

  • new_order – 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.

Type heap

spead2.recv.Heap

Type new_order

str

Returns

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

Rtype

dict