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
-
Items are collected into sets called item groups, which can be indexed by either item ID or item name.
-
class
spead2.
ItemGroup
¶ -
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.
-
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
-