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 in the way the parameters combine, 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’
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 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:
- The item descriptor is identical to a previous seen one. In this case, no action is taken.
- 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)¶ Update the item descriptors and items from an incoming heap.
Parameters: heap ( spead2.recv.Heap
) – Incoming heapReturns: Items that have been updated from this heap, indexed by name Return type: dict