API

This part of the documentation lists the full API reference of all public classes and functions.

Provider

class konfoo.Provider

The Provider class provides access for the Pointer class to read and write byte streams from and back to a data source.

The Provider class servers as a metaclass.

A derived class must implement the two methods read() and write() for reading and writing byte streams from and back to the data source.

abstract read(address: int = 0, count: int = 0) → bytes

Returns a number of bytes read from a data source beginning at the start address.

Parameters:

• address (int) – start address to read from.

• count (int) – number of bytes to read from a data source.

Note

This abstract method must be implemented by a derived class.

abstract write(buffer: bytes | bytearray = bytearray(b''), address: int = 0, count: int = 0) → None

Writes the content of the buffer to a data source beginning at the start address.

Parameters:

• buffer (bytes|bytearray) – content to write.

• address (int) – start address to write to.

• count (int) – number of bytes to write to a data source.

Note

This abstract method must be implemented by a derived class.

FileProvider

class konfoo.FileProvider(file: Path | str)

The FileProvider is a byte stream Provider for binary files.

The file content is internal stored in a cache.

The read() and write() methods only operate on the internal cache.

Call flush() to store the updated file content to the same or a new file.

Parameters:

file (Path|str) – name and location of the file to read.

path

File path.

property cache: bytearray

Returns the internal byte stream cache of the Provider (read-only).

read(address: int = 0, count: int = 0) → bytes

Returns a number of bytes read from the cache beginning at the start address.

Parameters:

• address (int) – start address.

• count (int) – number of bytes to read from the cache.

write(buffer: bytes | bytearray = b'', address: int = 0, count: int = 0) → None

Writes the content of the buffer to the cache beginning at the start address.

Parameters:

• buffer (bytes|bytearray) – content to write.

• address (int) – start address.

• count (int) – number of bytes to write to the cache.

flush(file: Path | str | None = None) → None

Flushes the updated file content to the given file.

Note

Overwrites an existing file.

Parameters:

file (Path|str|None) – name and location of the file. Default is the original file.

Container

class konfoo.Container

The Container class is an abstract interface for all classes which can contain Field items. Container classes are Structures, Sequences, Arrays and Pointers.

The Container class provides core features to view, save and load the attributes of the Field items in the Container.

abstract view_fields(*attributes: str, **options: Any) → dict[str, Any] | list[Any]

Returns a container with the selected field attribute or with the dictionary of the selected field attributes for each Field nested in the Container.

The attributes of each Field for containers nested in the Container are viewed as well (chained method call).

Parameters:

• attributes (str) – selected Field attributes. Fallback is the field value.

• fieldnames (tuple[str, ...]) – sequence of dictionary keys for the selected field attributes. Defaults to (*attributes).

• nested (bool) – if True all Pointer fields in the Container views their referenced data object field attributes as well (chained method call).

Note

This abstract method must be implemented by a derived class.

abstract field_items(path: str = '', **options: Any) → list[tuple[str, konfoo.core.Field]]

Returns a flatten list of ('field path', field item) tuples for each Field nested in the Container.

Parameters:

• path (str) – item path.

• nested (bool) – if True all Pointer fields in the data objects of all Pointer fields in the Container list their referenced data object field items as well (chained method call).

Note

This abstract method must be implemented by a derived class.

to_list(*attributes: str, **options: Any) → list[tuple[str, Any] | tuple[str, tuple[Any, ...]]]

Returns a flatten list of ('field path', attribute) or ('field path', tuple(attributes)) tuples for each Field nested in the Container.

Parameters:

• attributes (str) – selected Field attributes. Fallback is the field value.

• name (str) – name of the Container. Default is the class name of the instance.

• chain (bool) – if True the field attributes are chained to its field path. Defaults to False.

• nested (bool) – if True all Pointer fields in the Container lists their referenced data object field attributes as well (chained method call).

to_dict(*attributes: str, **options: Any) → dict[str, Any | tuple[Any, ...]]

Returns a flatten dict of {'field path': attribute} or {'field path': tuple(attributes)} pairs for each Field nested in the Container.

Parameters:

• attributes (str) – selected Field attributes. Fallback is the field value.

• name (str) – name of the Container. Default is the class name of the instance.

• nested (bool) – if True all Pointer fields in the Container lists their referenced data object field attributes as well (chained method call).

save(file: str, *attributes: str, **options: Any) → None

Saves the selected field attributes for each Field nested in the Container to an .ini file.

Parameters:

• file (str) – name and location of the .ini file.

• attributes (str) – selected Field attributes. Fallback is the field value.

• section (str) – section in the .ini file to look for the Field values of the Container. If no section is specified the class name of the instance is used.

• nested (bool) – if True all Pointer fields in the Container saves their referenced data object field attributes as well (chained method call).

Example:

>>> class Foo(Structure):
...     def __init__(self):
...         super().__init__()
...         self.stream = Stream()
...         self.float = Float()
...         self.structure = Structure()
...         self.structure.decimal = Decimal(8)
...         self.array = Array(Byte, 3)
...         self.pointer = Pointer()
>>> foo = Foo()
>>> foo.to_list(nested=True)
[('Foo.stream', ''),
 ('Foo.float', 0.0),
 ('Foo.structure.decimal', 0),
 ('Foo.array[0]', '0x0'),
 ('Foo.array[1]', '0x0'),
 ('Foo.array[2]', '0x0'),
 ('Foo.pointer', '0x0')]
>>> foo.to_json(nested=True)
'{"stream": "",
  "float": 0.0,
  "structure": {"decimal": 0},
  "array": ["0x0", "0x0", "0x0"],
  "pointer": {"value": "0x0",
              "data": null}}'
>>> foo.save('foo.ini')

File foo.ini:

[Foo]
stream =
float = 0.0
structure.decimal = 0
array[0] = 0x0
array[1] = 0x0
array[2] = 0x0
pointer = 0x0

load(file: str, **options: Any) → None

Loads the field value for each Field nested in the Container from an .ini file.

Parameters:

• file (str) – name and location of the .ini file.

• section (str) – section in the .ini file to look-up the value for each Field in the Container. If no section is specified the class name of the instance is used.

• nested (bool) – if True all Pointer fields in the Container load their referenced data object field values as well (chained method call).

• verbose (bool) – if True the loading is executed in verbose mode.

File foo.ini:

[Foo]
stream =
float = 0.0
structure.decimal = 0
array[0] = 0x0
array[1] = 0x0
array[2] = 0x0
pointer = 0x0

Example:

>>> class Foo(Structure):
...     def __init__(self):
...         super().__init__()
...         self.stream = Stream()
...         self.float = Float()
...         self.structure = Structure()
...         self.structure.decimal = Decimal(8)
...         self.array = Array(Byte, 3)
...         self.pointer = Pointer()
>>> foo = Foo()
>>> foo.load('foo.ini')
[Foo]
Foo.stream =
Foo.float = 0.0
Foo.structure.decimal = 0
Foo.array[0] = 0x0
Foo.array[1] = 0x0
Foo.array[2] = 0x0
Foo.pointer = 0x0
>>> foo.to_list(nested=True)
[('Foo.stream', ''),
 ('Foo.float', 0.0),
 ('Foo.structure.decimal', 0),
 ('Foo.array[0]', '0x0'),
 ('Foo.array[1]', '0x0'),
 ('Foo.array[2]', '0x0'),
 ('Foo.pointer', '0x0')]
>>> foo.to_json(nested=True)
'{"stream": "",
  "float": 0.0,
  "structure": {"decimal": 0},
  "array": ["0x0", "0x0", "0x0"],
  "pointer": {"value": "0x0",
              "data": null}}'

to_json(*attributes: str, **options: Any) → str

Returns the selected field attributes for each Field nested in the Container as a JSON formatted string.

The attributes of each Field for containers nested in the Container are viewed as well (chained method call).

Parameters:

• attributes (str) – selected Field attributes. Fallback is the field value.

• fieldnames (tuple[str, ...]) – sequence of dictionary keys for the selected field attributes. Defaults to (*attributes).

• nested (bool) – if True all Pointer fields in the Container views their referenced data object field attributes as well (chained method call).

write_json(file: str, *attributes: str, **options: Any) → None

Writes the selected field attributes for each Field nested in the Container to a .json file.

Parameters:

• file (str) – name and location of the .json file.

• attributes (str) – selected Field attributes. Fallback is the field value.

• fieldnames (tuple[str, ...]) – sequence of dictionary keys for the field path and the selected field attributes. Defaults to (*attributes).

• nested (bool) – if True all Pointer fields in the Container lists their referenced data object field attributes as well (chained method call).

to_csv(*attributes: str, **options: Any) → list[dict[str, Any]]

Returns a flatten list of dictionaries containing the field path and the selected field attributes for each Field nested in the Container.

Parameters:

• attributes (str) – selected Field attributes. Fallback is the field value.

• name (str) – name of the Container. Default is the class name of the instance.

• fieldnames (tuple[str, ...]) – sequence of dictionary keys for the field path and the selected field attributes. Defaults to ('id', *attributes).

• nested (bool) – if True all Pointer fields in the Container lists their referenced data object field attributes as well (chained method call).

write_csv(file: str, *attributes: str, **options: Any) → None

Writes the field path and the selected field attributes for each Field nested in the Container to a .csv file.

Parameters:

• file (str) – name and location of the .csv file.

• attributes (str) – selected Field attributes. Fallback is the field value.

• name (str) – name of the Container. Default is the class name of the instance.

• fieldnames (tuple[str, ...]) – sequence of dictionary keys for the field path and the selected field attributes. Defaults to ('id', *attributes).

• nested (bool) – if True all Pointer fields in the Container lists their referenced data object field attributes as well (chained method call).

Structure

class konfoo.Structure(*args: Mapping | None, **kwargs: Any)

The Structure is a dict whereby the dictionary key describes the name of a member of the Structure and the value of the dictionary key describes the type of the member. Allowed members are Structure, Sequence, Array or Field instances.

The Structure class extends the dict with the Container interface and attribute getter and setter for the {'key': value} tuples to access and to assign the members of the Structure easier, but this comes with the trade-off that the dictionary keys must be valid Python attribute names.

A Structure has additional methods to read, deserialize, serialize and view binary data:

• Read from a Provider the necessary bytes for each data object referenced by the Pointer fields in the Structure via read_from().

• Deserialize the value for each Field in the Structure from a byte stream via deserialize().

• Serialize the value for each Field in the Structure to a byte stream via serialize().

• Indexes all fields in the Structure via index_fields().

• Get the first Field in the Structure via first_field().

• Get the accumulated size of all fields in the Structure via container_size().

• View the selected attributes for each Field in the Structure via view_fields().

• List the path to the field and the field item itself for each Field in the Structure as a flatted list via field_items().

• Get the metadata of the Structure via describe().

read_from(provider: Provider, **options: Any) → None

All Pointer fields in the Structure read the necessary number of bytes from the data Provider for their referenced data object. Null pointer are ignored.

Parameters:

• provider (Provider) – data Provider.

• nested (bool) – if True all Pointer fields in the data objects of all Pointer fields in the Structure reads their referenced data object as well (chained method call). Each Pointer field stores the bytes for its referenced data object in its bytestream.

deserialize(buffer: bytes = b'', index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) → Index

De-serializes the Structure from the byte buffer starting at the beginning of the buffer or with the given index by mapping the bytes to the value for each Field in the Structure in accordance with the decoding byte order for the de-serialization and the decoding byte_order of each Field in the Structure.

A specific decoding byte_order of a Field overrules the decoding byte order for the de-serialization.

Returns the Index of the buffer after the last de-serialized Field in the Structure.

Optional the de-serialization of the referenced data objects of all Pointer fields in the Structure can be enabled.

Parameters:

• buffer (bytes) – byte stream to de-serialize from.

• index (Index) – current read Index within the buffer to de-serialize.

• byte_order (Byteorder|Literal['auto', 'big', 'little']) – decoding byte order for the de-serialization.

• nested (bool) – if True all Pointer fields of a Structure de-serialize their referenced data object as well (chained method call). Each Pointer field uses for the de-serialization of its referenced data object its own bytestream.

serialize(buffer: bytearray = bytearray(b''), index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) → Index

Serializes the Structure to the byte buffer starting at the beginning of the buffer or with the given index by mapping the value for each Field in the Structure to the byte buffer in accordance with the encoding byte order for the serialization and the encoding byte_order of each Field in the Structure.

A specific encoding byte_order of a Field overrules the encoding byte order for the serialization.

Returns the Index of the buffer after the last serialized Field in the Structure.

Optional the serialization of the referenced data objects of all Pointer fields in the Structure can be enabled.

Parameters:

• buffer (bytearray) – byte stream to serialize to.

• index (Index) – current write Index within the buffer.

• byte_order (Byteorder|Literal['auto', 'big', 'little']) – encoding byte order for the serialization.

• nested (bool) – if True all Pointer fields of a Structure serialize their referenced data object as well (chained method call). Each Pointer field uses for the serialization of its referenced data object its own bytestream.

index_fields(index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) → Index

Indexes all fields in the Structure starting with the given index and returns the Index after the last Field in the Structure.

Parameters:

• index (Index) – start Index for the first Field in the Structure.

• nested (bool) – if True all Pointer fields of the Structure indexes their referenced data object fields as well (chained method call).

container_size() → tuple[int, int]

Returns the accumulated bit size of all fields in the Structure as a tuple in the form of (number of bytes, remaining number of bits).

first_field() → Field | None

Returns the first Field in the Structure, or None for an empty Structure.

initialize_fields(content: dict[str, Any]) → None

Initializes the Field members in the Structure with the values in the content dictionary.

Parameters:

content (dict[str, Any]) – a dictionary contains the Field values for each member in the Structure.

view_fields(*attributes: str, **options: Any) → dict[str, Any]

Returns an dict which contains the {'member name': field attribute}, or the {'member name': dict(field attributes)} tuples for each Field nested in the Structure.

The attributes of each Field for containers nested in the Structure are viewed as well (chained method call).

Parameters:

• attributes (str) – selected Field attributes. Fallback is the field value.

• fieldnames (tuple[str, ...]) – sequence of dictionary keys for the selected field attributes. Defaults to (*attributes).

• nested (bool) – if True all Pointer fields nested in the Structure views their referenced data object field attributes as well (chained method call).

field_items(path: str = '', **options: Any) → list[tuple[str, konfoo.core.Field]]

Returns a flatten list of ('field path', field item) tuples for each Field nested in the Structure.

Parameters:

• path (str) – field path of the Structure.

• nested (bool) – if True all Pointer fields in the data objects of all Pointer fields in the Structure list their referenced data object field items as well (chained method call).

describe(name: str = '', **options: Any) → dict[str, Any]

Returns the metadata of the Structure as a dict.

metadata = {
    'class': self.__class__.__name__,
    'name': name if name else self.__class__.__name__,
    'size': len(self),
    'type': Structure.item_type.name
    'member': [
        item.describe(member) for member, item in self.items()
    ]
}

Parameters:

• name (str) – optional name for the Structure. Fallback is the class name.

• nested (bool) – if True all Pointer fields of the Structure lists their referenced data object fields as well (chained method call). Default is True.

Sequence

class konfoo.Sequence(iterable: Iterable[Structure | Sequence | Field] | Structure | Sequence | Field | None = None)

The Sequence is a mutable sequence containing heterogeneous items, and is extended with the Container interface.

Allowed items are Structure, Sequence, Array or Field instances.

A Sequence is:

• containable: item in self returns True if item is in the Sequence.

• sized: len(self) returns the number of items in the Sequence.

• indexable self[index] returns the item at the index of the Sequence.

• iterable iter(self) iterates over the items in the Sequence

A Sequence supports the usual methods for sequences:

• Append an item to the Sequence via append().

• Insert an item before the index into the Sequence via insert().

• Extend the Sequence with items via extend().

• Clear the Sequence via clear().

• Pop an item with the index from the Sequence via pop().

• Remove the first occurrence of an item from the Sequence via remove().

• Reverse all items in the Sequence via reverse().

A Sequence has additional methods to read, deserialize, serialize and view binary data:

• Read from a Provider the necessary bytes for each data object referenced by the Pointer fields in the Sequence via read_from().

• Deserialize the value for each Field in the Sequence from a byte stream via deserialize().

• Serialize the value for each Field in the Sequence to a byte stream via serialize().

• Indexes all fields in the Sequence via index_fields().

• Get the first Field in the Sequence via first_field().

• Get the accumulated size of all fields in the Sequence via container_size().

• View the selected attributes for each Field in the Sequence via view_fields().

• List the path to the field and the field item itself for each Field in the Sequence as a flatted list via field_items().

• Get the metadata of the Sequence via describe().

Parameters:

iterable (Iterable[Structure|Sequence|Field]|Structure|Sequence|Field|None) – any iterable that contains items of Structure, Sequence, Array or Field instances. If the iterable is one of these instances itself then the iterable itself is appended to the Sequence.

append(item: Structure | Sequence | Field) → None

Appends the item to the end of the Sequence.

Parameters:

item (Structure|Sequence|Field) – any Structure, Sequence, Array or Field instance.

insert(index: int, item: Structure | Sequence | Field) → None

Inserts the item before the index into the Sequence.

Parameters:

• index (int) – Sequence index.

• item (Structure|Sequence|Field) – any Structure, Sequence, Array or Field instance.

pop(index: int = -1) → Structure | Sequence | Field

Removes and returns the item at the index from the Sequence.

Parameters:

index (int) – Sequence index.

clear() → None

Remove all items from the Sequence.

remove(item: Structure | Sequence | Field) → None

Removes the first occurrence of an item from the Sequence.

Parameters:

item (Structure|Sequence|Field) – any Structure, Sequence, Array or Field instance.

reverse() → None

In place reversing of the Sequence items.

extend(iterable: Iterable[Structure | Sequence | Field] | Structure | Sequence | Field) → None

Extends the Sequence by appending items from the iterable.

Parameters:

iterable (Iterable[Structure|Sequence|Field]|Structure|Sequence|Field) – any iterable that contains items of Structure, Sequence, Array or Field instances. If the iterable is one of these instances itself then the iterable itself is appended to the Sequence.

read_from(provider: Provider, **options: Any) → None

All Pointer fields in the Sequence read the necessary number of bytes from the data Provider for their referenced data object. Null pointer are ignored.

Parameters:

• provider (Provider) – data Provider.

• nested (bool) – if True all Pointer fields in the data objects of all Pointer fields in the Sequence reads their referenced data object as well (chained method call). Each Pointer field stores the bytes for its referenced data object in its bytestream.

deserialize(buffer: bytes = b'', index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) → Index

De-serializes the Sequence from the byte buffer starting at the beginning of the buffer or with the given index by mapping the bytes to the value for each Field in the Sequence in accordance with the decoding byte order for the de-serialization and the decoding byte_order of each Field in the Sequence.

A specific decoding byte_order of a Field overrules the decoding byte order for the de-serialization.

Returns the Index of the buffer after the last de-serialized Field in the Sequence.

Optional the de-serialization of the referenced data objects of all Pointer fields in the Sequence can be enabled.

Parameters:

• buffer (bytes) – byte stream to de-serialize from.

• index (Index) – current read Index within the buffer to de-serialize.

• byte_order (Byteorder|Literal['auto', 'big', 'little']) – decoding byte order for the de-serialization.

• nested (bool) – if True all Pointer fields of a Sequence de-serialize their referenced data object as well (chained method call). Each Pointer field uses for the de-serialization of its referenced data object its own bytestream.

serialize(buffer: bytearray = bytearray(b''), index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) → Index

Serializes the Sequence to the byte buffer starting at the beginning of the buffer or with the given index by mapping the value for each Field in the Sequence to the byte buffer in accordance with the encoding byte order for the serialization and the encoding byte_order of each Field in the Sequence.

A specific encoding byte_order of a Field overrules the encoding byte order for the serialization.

Returns the Index of the buffer after the last serialized Field in the Sequence.

Optional the serialization of the referenced data objects of all Pointer fields in the Sequence can be enabled.

Parameters:

• buffer (bytearray) – byte stream to serialize to.

• index (Index) – current write Index within the buffer.

• byte_order (Byteorder|Literal['auto', 'big', 'little']) – encoding byte order for the serialization.

• nested (bool) – if True all Pointer fields of a Sequence serialize their referenced data object as well (chained method call). Each Pointer field uses for the serialization of its referenced data object its own bytestream.

index_fields(index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) → Index

Indexes all fields in the Sequence starting with the given index and returns the Index after the last Field in the Sequence.

Parameters:

• index (Index) – start Index for the first Field in the Sequence.

• nested (bool) – if True all Pointer fields in the Sequence indexes their referenced data object fields as well (chained method call).

container_size() → tuple[int, int]

Returns the accumulated bit size of all fields in the Sequence as a tuple in the form of (number of bytes, remaining number of bits).

first_field() → Field | None

Returns the first Field in the Sequence, or None for an empty Sequence.

initialize_fields(content: list[Any]) → None

Initializes the Field items in the Sequence with the values in the content list.

Parameters:

content (list[Any]) – a list contains the Field values for each item in the Sequence.

view_fields(*attributes: str, **options: Any) → list[Any]

Returns a list with the selected field attribute or a list with the dictionaries of the selected field attributes for each Field nested in the Sequence.

The attributes of each Field for containers nested in the Sequence are viewed as well (chained method call).

Parameters:

• attributes (str) – selected Field attributes. Fallback is the field value.

• fieldnames (tuple[str, ...]) – sequence of dictionary keys for the selected field attributes. Defaults to (*attributes).

• nested (bool) – if True all Pointer fields nested in the Sequence views their referenced data object field attributes as well (chained method call).

field_items(path: str = '', **options: Any)

Returns a flatten list of ('field path', field item) tuples for each Field nested in the Sequence.

Parameters:

• path (str) – field path of the Sequence.

• nested (bool) – if True all Pointer fields in the data objects of all Pointer fields in the Sequence list their referenced data object field items as well (chained method call).

describe(name: str = '', **options: Any) → dict[str, Any]

Returns the metadata of the Sequence as a dict.

metadata = {
    'class': self.__class__.__name__,
    'name': name if name else self.__class__.__name__,
    'size': len(self),
    'type': Sequence.item_type.name
    'member': [
        item.describe('name[idx]') for idx, item in enumerate(self)
    ]
}

Parameters:

• name (str) – optional name for the Sequence. Fallback is the class name.

• nested (bool) – if True all Pointer fields in the Sequence lists their referenced data object fields as well (chained method call). Default is True.

Array

class konfoo.Array(template: Callable | Structure | Sequence | Field, capacity: int = 0)

The Array is a Sequence which contains elements of one type. The template for the array element can be any Field instance or a callable (factory) which returns a Structure, Sequence, Array or any Field instance.

A callable template (factory) is necessary to ensure that the internal constructor for the array element produces complete copies for each array element including the nested objects in the template for the array element.

An Array of Pointer fields should use a callable instead of assigning a Pointer field instance directly as the array element template to ensure that the referenced data object of a Pointer field is also complete copied for each array element.

An Array adapts and extends a Sequence with the following features:

• Append a new array element to the Array via append().

• Insert a new array element before the index into the Array via insert().

• Re-size the Array via resize().

An Array replaces the 'type' key of the metadata of a Sequence with its own item type.

Parameters:

• template – template for the array element. The template can be any Field instance or any callable that returns a Structure, Sequence, Array or any Field instance.

• capacity (int) – capacity of the Array in number of array elements.

append() → None

Appends a new array element to the Array.

insert(index: int) → None

Inserts a new array element before the index of the Array.

Parameters:

index (int) – Array index.

resize(capacity: int) → None

Re-sizes the Array by appending new array elements or removing array elements from the end.

Parameters:

capacity (int) – new capacity of the Array in number of array elements.

initialize_fields(content: list[Any]) → None

Initializes the Field elements in the Array with the values in the content list.

If the content list is shorter than the Array then the content list is used as a rotating fill pattern for the Field elements in the Array.

Parameters:

content (list[Any]) – a list contains the Field values for each element in the Array or one Field value for all elements in the Array.

Fields

class konfoo.Field(bit_size: int = 0, align_to: int = 0, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Field class is the abstract class for all field classes.

A Field has a specific name, bit size, byte order, and can be aligned to other fields.

A Field has methods to unpack, pack, deserialize and serialize its field value from and to a byte stream, and stores its location within the byte stream and the providing data source in its field index.

Parameters:

• bit_size (int) – is the size of a Field in bits.

• align_to (int) – aligns the Field to the number of bytes, can be between 1 and 8.

• byte_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the Field. Default is auto.

property alignment: Alignment

Returns the Alignment of the Field (read-only).

property bit_size: int

Returns the size of the Field in bits (read-only).

property byte_order: Byteorder

Byteorder used to decode and encode the value of the Field.

property index: Index

Index of the Field.

property name: str

Returns the type name of the Field (read-only).

property value: Any

Field value.

static is_bit() → bool

Returns False.

static is_bool() → bool

Returns False.

static is_decimal() → bool

Returns False.

static is_float() → bool

Returns False.

static is_pointer() → bool

Returns False.

static is_stream() → bool

Returns False.

static is_string() → bool

Returns False.

abstract unpack(buffer: bytes = b'', index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) → Any

Unpacks the field value from the buffer at the given index in accordance with the decoding byte order for the de-serialization and the byte_order and alignment of the Field.

The specific decoding byte_order of the Field overrules the decoding byte order for the de-serialization.

Returns the deserialized field value.

Parameters:

• buffer (bytes) – byte stream to unpack from.

• index (Index) – current read Index within the buffer.

• byte_order (Byteorder|Literal['auto', 'big', 'little']) – decoding byte order for the de-serialization.

Note

This abstract method must be implemented by a derived class.

abstract pack(buffer: bytearray = bytearray(b''), **options: Any) → bytes

Packs the field value to the buffer at the given index in accordance with the encoding byte order for the serialization and the byte_order and alignment of the Field.

The specific encoding byte_order of the Field overrules the encoding byte order for the serialization.

Returns the bytes for the serialized field value.

Parameters:

• buffer (bytearray) – byte stream to pack to.

• byte_order (Byteorder|Litreal['auto', 'big', 'little']) – encoding byte order for the serialization.

Note

This abstract method must be implemented by a derived class.

deserialize(buffer: bytes = b'', index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) → Index

De-serializes the Field from the byte buffer starting at the beginning of the buffer or with the given index by unpacking the bytes to the value of the Field in accordance with the decoding byte order for the de-serialization and the decoding byte_order of the Field.

The specific decoding byte_order of the Field overrules the decoding byte order for the de-serialization.

Returns the Index of the buffer after the Field.

Optional the de-serialization of the referenced data object of a Pointer field can be enabled.

Parameters:

• buffer (bytes) – byte stream to de-serialize from.

• index (Index) – current read Index within the buffer to de-serialize.

• byte_order (Byteorder|Literal['auto', 'big', 'little']) – decoding byte order for the de-serialization.

• nested (bool) – if True a Pointer field de-serialize its referenced data object as well (chained method call). Each Pointer field uses for the de-serialization of its referenced data object its own bytestream.

serialize(buffer: bytearray = bytearray(b''), index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) → Index

Serializes the Field to the byte buffer starting at the beginning of the buffer or with the given index by packing the value of the Field to the byte buffer in accordance with the encoding byte order for the serialization and the encoding byte_order of the Field.

The specific encoding byte_order of the Field overrules the encoding byte order for the serialization.

Returns the Index of the buffer after the Field.

Optional the serialization of the referenced data object of a Pointer field can be enabled.

Parameters:

• buffer (bytearray) – byte stream to serialize to.

• index (Index) – current write Index of the buffer.

• byte_order (Byteorder|Literal['auto', 'big', 'little']) – encoding byte order for the serialization.

• nested (bool) – if True a Pointer field serializes its referenced data object as well (chained method call). Each Pointer field uses for the encoding of its referenced data object its own bytestream.

index_field(index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False)) → Index

Indexes the Field with the given index und returns the Index after the Field.

Parameters:

index (Index) – start Index for the Field.

describe(name: str = '', **options: Any) → dict[str, Any]

Returns the metadata of a Field as a dict.

metadata = {
    'address': self.index.address,
    'alignment': [self.alignment.byte_size, self.alignment.bit_offset],
    'class': self.name,
    'index': [self.index.byte, self.index.bit],
    'name': name if name else self.name,
    'order': self.byte_order.value,
    'size': self.bit_size,
    'type': Field.item_type.name,
    'value': self.value
}

Parameters:

• name (str) – optional name for the Field. Fallback is the class name.

• nested (bool) – if True a Pointer field lists its referenced data object fields as well (chained method call). Default is True.

Stream

class konfoo.Stream(capacity: int = 0)

The Stream field is a Field with a variable size, and returns its field value as a hexadecimal string.

Internally a Stream field uses a bytes class to store the data of its field value.

A Stream field is:

• containable: item in self returns True if item is part of the Stream field.

• sized: len(self) returns the length of the Stream field.

• indexable self[index] returns the byte at the index of the Stream field.

• iterable iter(self) iterates over the bytes of the Stream field.

Parameters:

capacity (int) – is the capacity of the Stream field in bytes.

Example:

>>> stream = Stream()
>>> stream.is_stream()
True
>>> stream.name
'Stream'
>>> stream.alignment
Alignment(byte_size=0, bit_offset=0)
>>> stream.byte_order
Byteorder.auto = 'auto'
>>> stream.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> stream.index_field()
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> stream.bit_size
0
>>> len(stream)
0
>>> bool(stream)
False
>>> stream.value
''
>>> bytes(stream)
b''
>>> stream.hex()
''
>>> stream.resize(10)
>>> stream.name
'Stream10'
>>> stream.alignment
Alignment(byte_size=10, bit_offset=0)
>>> stream.bit_size
80
>>> stream.index_field()
Index(byte=10, bit=0, address=10, base_address=0, update=False)
>>> stream.value
'00000000000000000000'
>>> stream.value = '0102030405'
>>> stream.value
'01020304050000000000'
>>> stream.resize(15)
>>> stream.value
'010203040500000000000000000000'
>>> stream.resize(10)
>>> stream.value = '0102030405060708090a0b0c'
>>> stream.value
'0102030405060708090a'
>>> stream.hex()
'0102030405060708090a'
>>> len(stream)
10
>>> [byte for byte in stream]  # converts to int
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
>>> [hex(byte) for byte in stream]
['0x1', '0x2', '0x3', '0x4', '0x5', '0x6', '0x7', '0x8', '0x9', '0xa']
>>> stream[5]  # converts to int
6
>>> 7 in stream
True
>>> 0x0 in stream
False
>>> stream[5:].hex()  # converts to bytes
'060708090a'
>>> stream.describe()
{'address': 0,
 'alignment': [10, 0],
 'class': 'Stream10',
 'index': [0, 0],
 'name': 'Stream10',
 'order': 'auto',
 'size': 80,
 'type': 'Field',
 'value': '0102030405060708090a'}

property name: str

Returns the type name of the Stream field (read-only).

property value: str

Field value as a lowercase hexadecimal encoded string.

hex() → str

Returns a string containing two hexadecimal digits for each byte in the value of the Stream field.

static is_stream() → bool

Returns True.

resize(capacity: int) → None

Re-sizes the Stream field by appending zero bytes or removing bytes from the end.

Parameters:

capacity (int) – Stream capacity in number of bytes.

String

class konfoo.String(capacity: int = 0)

The String field is a Stream field with a variable size, and returns its field value as a zero-terminated ASCII string.

A String field is:

• containable: item in self returns True if item is part of the String field.

• sized: len(self) returns the length of the String field.

• indexable self[index] returns the byte at the index of the String field.

• iterable iter(self) iterates over the bytes of the String field.

Parameters:

capacity (int) – is the capacity of the String field in bytes.

Example:

>>> string = String()
>>> string.is_stream()
True
>>> string.is_string()
True
>>> string.is_terminated()
False
>>> string.name
'String'
>>> string.alignment
Alignment(byte_size=0, bit_offset=0)
>>> string.byte_order
Byteorder.auto = 'auto'
>>> string.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> string.index_field()
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> string.bit_size
0
>>> len(string)
0
>>> bool(string)
False
>>> string.value
''
>>> bytes(string)
b''
>>> string.hex()
''
>>> string.resize(10)
>>> string.name
'String10'
>>> string.alignment
Alignment(byte_size=10, bit_offset=0)
>>> string.bit_size
80
>>> string.index_field()
Index(byte=10, bit=0, address=10, base_address=0, update=False)
>>> string.value
''
>>> string.value = 'KonFoo'
>>> string.value
'KonFoo'
>>> string.resize(3)
>>> string.value
'Kon'
>>> string.resize(10)
>>> string.value
'Kon'
>>> string.value = 'KonFoo is Fun'
>>> string.value
'KonFoo is '
>>> string.hex()
'4b6f6e466f6f20697320'
>>> len(string)
10
>>> [byte for byte in string]  # converts to int
[75, 111, 110, 70, 111, 111, 32, 105, 115, 32]
>>> [chr(byte) for byte in string]  # converts to int
['K', 'o', 'n', 'F', 'o', 'o', ' ', 'i', 's', ' ']
>>> chr(string[5])  # converts to int -> chr
'o'
>>> ord(' ') in string
True
>>> 0x0 in string
False
>>> string[:6]  # converts to bytes
b'KonFoo'
>>> string[3:6]  # converts to bytes
b'Foo'
>>> string.describe()
{'address': 0,
 'alignment': [10, 0],
 'class': 'String10',
 'index': [0, 0],
 'name': 'String10',
 'order': 'auto',
 'size': 80,
 'type': 'Field',
 'value': 'KonFoo is '}

property value: str

Field value as an ascii encoded string.

static is_string() → bool

Returns True.

is_terminated() → bool

Returns True if the String field is zero-terminated.

Float

class konfoo.Float(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Float field is a Field with a fix size of four bytes, and returns its field value as a single precision float.

Internally a Float field uses a float class to store the data of its field value.

A Float field extends the metadata of a Field with a 'max' and 'min' key for its maximum and minimum possible field value.

Parameters:

byte_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the Float field.

Example:

>>> real = Float()
>>> real.is_float()
True
>>> real.name
'Float32'
>>> real.alignment
Alignment(byte_size=4, bit_offset=0)
>>> real.byte_order
Byteorder.auto = 'auto'
>>> real.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> real.index_field()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> real.bit_size
32
>>> real.min()
-3.4028234663852886e+38
>>> real.max()
3.4028234663852886e+38
>>> real.smallest()
1.1754943508222875e-38
>>> real.epsilon()
5.960464477539063e-08
>>> real.value
0.0
>>> bytes(real)
b'\x00\x00\x00\x00'
>>> int(real)
0
>>> float(real)
0.0
>>> bool(real)
False
>>> real.value = 0x10
>>> real.value
16.0
>>> real.value = -3.4028234663852887e+38
>>> real.value
-3.4028234663852886e+38
>>> real.value = 3.4028234663852887e+38
>>> real.value
3.4028234663852886e+38
>>> real.describe()
{'address': 0,
 'alignment': [4, 0],
 'class': 'Float32',
 'index': [0, 0],
 'max': 3.4028234663852886e+38,
 'min': -3.4028234663852886e+38,
 'name': 'Float32',
 'order': 'auto',
 'size': 32,
 'type': 'Field',
 'value': 3.4028234663852886e+38}

property value: float

Field value as a single precision floating-point number.

static is_float() → bool

Returns True.

static smallest() → float

Returns the smallest normalized field value of the Float field.

static max() → float

Returns the maximal possible field value of the Float field.

static min() → float

Returns the minimal possible field value of the Float field.

Double

class konfoo.Double(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Double field is a Field with a fix size of eight bytes, and returns its field value as a double precision float.

Internally a Double field uses a float class to store the data of its field value.

A Double field extends the metadata of a Field with a 'max' and 'min' key for its maximum and minimum possible field value.

Parameters:

byte_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the Double field.

Example:

>>> double = Double()
>>> double.is_float()
True
>>> double.name
'Double64'
>>> double.alignment
Alignment(byte_size=8, bit_offset=0)
>>> double.byte_order
Byteorder.auto = 'auto'
>>> double.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> double.index_field()
Index(byte=8, bit=0, address=8, base_address=0, update=False)
>>> double.bit_size
64
>>> double.min()
-1.7976931348623157e+308
>>> double.max()
1.7976931348623157e+308
>>> double.smallest()
2.2250738585072014e-308
>>> double.epsilon()
1.1102230246251565e-16
>>> double.value
0.0
>>> bytes(double)
b'\x00\x00\x00\x00\x00\x00\x00\x00'
>>> int(double)
0
>>> float(double)
0.0
>>> bool(double)
False
>>> double.value = 0x10
>>> double.value
16.0
>>> double.value = -1.7976931348623158e+308
>>> double.value
-1.7976931348623157e+308
>>> double.value = 1.7976931348623158e+308
>>> double.value
1.7976931348623157e+308
>>> double.describe()
{'address': 0,
 'alignment': [8, 0],
 'class': 'Double64',
 'index': [0, 0],
 'max': 1.7976931348623157e+308,
 'min': -1.7976931348623157e+308,
 'name': 'Double64',
 'order': 'auto',
 'size': 64,
 'type': 'Field',
 'value': 1.7976931348623157e+308}

property value: float

Field value as a double precision floating-point number.

static is_float() → bool

Returns True.

static smallest() → float

Returns the smallest normalized field value of the Double field.

static max() → float

Returns the maximal possible field value of the Double field.

static min() → float

Returns the minimal possible field value of the Double field.

Decimal

class konfoo.Decimal(bit_size: int, align_to: int | None = None, signed: bool = False, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Decimal field is a Field with a variable size and returns its field value as a decimal number.

Internally a Decimal field uses an int class to store the data of its field value.

A Decimal field extends the metadata of a Field with a 'max' and 'min' key for its maximum and minimum possible field value and a 'signed' key to mark the decimal number as signed or unsigned.

Parameters:

• bit_size (int) – is the size of the Decimal field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the Decimal field to the number of bytes, can be between 1 and 8. If no field alignment is set the Decimal field aligns itself to the next matching byte size according to the size of the Decimal field.

• signed (bool) – if True the Decimal field is signed otherwise unsigned.

• byte_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the Decimal field.

Example:

>>> unsigned = Decimal(16)
>>> unsigned.is_decimal()
True
>>> unsigned.name
'Decimal16'
>>> unsigned.alignment
Alignment(byte_size=2, bit_offset=0)
>>> unsigned.byte_order
Byteorder.auto = 'auto'
>>> unsigned.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> unsigned.index_field()
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> unsigned.bit_size
16
>>> unsigned.signed
False
>>> unsigned.min()
0
>>> unsigned.max()
65535
>>> unsigned.value
0
>>> bytes(unsigned)
b'\x00\x00'
>>> int(unsigned)
0
>>> float(unsigned)
0.0
>>> hex(unsigned)
'0x0'
>>> bin(unsigned)
'0b0'
>>> oct(unsigned)
'0o0'
>>> bool(unsigned)
False
>>> unsigned.as_signed()
0
>>> unsigned.as_unsigned()
0
>>> unsigned.deserialize(bytes.fromhex('0080'))
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> unsigned.value
32768
>>> unsigned.value = 0x4000
>>> unsigned.value
16384
>>> unsigned.value = -1
>>> unsigned.value
0
>>> unsigned.value = 65536
>>> unsigned.value
65535
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> unsigned.serialize(bytestream)
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> bytestream.hex()
'ffff'
>>> unsigned.describe()
{'address': 0,
 'alignment': [2, 0],
 'class': 'Decimal16',
 'index': [0, 0],
 'max': 65535,
 'min': 0,
 'name': 'Decimal16',
 'order': 'auto',
 'signed': False,
 'size': 16,
 'type': 'Field',
 'value': 65535}

Example:

>>> signed = Decimal(16, signed=True)
>>> signed.is_decimal()
True
>>> signed.name
'Decimal16'
>>> signed.alignment
Alignment(byte_size=2, bit_offset=0)
>>> signed.byte_order
Byteorder.auto = 'auto'
>>> signed.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> signed.index_field()
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> signed.bit_size
16
>>> signed.signed
True
>>> signed.min()
-32768
>>> signed.max()
32767
>>> signed.value
0
>>> bytes(signed)
b'\x00\x00'
>>> int(signed)
0
>>> float(signed)
0.0
>>> hex(signed)
'0x0'
>>> bin(signed)
'0b0'
>>> oct(signed)
'0o0'
>>> bool(signed)
False
>>> signed.deserialize(bytes.fromhex('00c0'))
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> signed.value
-16384
>>> signed.value = -0x4000
>>> signed.value
-16384
>>> signed.value = -32769
>>> signed.value
-32768
>>> signed.value = 32768
>>> signed.value
32767
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> signed.serialize(bytestream)
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> bytestream.hex()
'ff7f'
>>> signed.describe()
{'address': 0,
 'alignment': [2, 0],
 'class': 'Decimal16',
 'index': [0, 0],
 'max': 32767,
 'min': -32768,
 'name': 'Decimal16',
 'order': 'auto',
 'signed': True,
 'size': 16,
 'type': 'Field',
 'value': 32767}

property value: int

Field value as a decimal number.

property signed: bool

Returns True if the Decimal field is signed.

static is_decimal() → bool

Returns True.

max() → int

Returns the maximal possible field value of the Decimal field.

min() → int

Returns the minimal possible field value of the Decimal field.

as_unsigned() → int

Returns the field value of the Decimal field as an unsigned integer.

as_signed() → int

Returns the field value of the Decimal field as a signed integer.

class konfoo.Decimal8(signed: bool = False, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Decimal8 field is a Decimal field with a size of one byte and is by default unsigned.

class konfoo.Decimal16(signed: bool = False, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Decimal16 field is a Decimal field with a size of two bytes and is by default unsigned.

class konfoo.Decimal24(signed: bool = False, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Decimal24 field is a Decimal field with a size of three bytes and is by default unsigned.

class konfoo.Decimal32(signed: bool = False, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Decimal32 field is a Decimal field with a size of four bytes and is by default unsigned.

class konfoo.Decimal64(signed: bool = False, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Decimal64 field is a Decimal field with a size of eight bytes and is by default unsigned.

Bit

class konfoo.Bit(number: int, align_to: int | None = None)

The Bit field is an unsigned Decimal with a size of one bit, and returns its field value as an unsigned integer number.

Parameters:

• number (int) – is the bit offset of the Bit field within the aligned bytes, can be between 0 and 63.

• align_to (int|None) – aligns the Bit field to the number of bytes, can be between 1 and 8.

Example:

>>> bit = Bit(0)
>>> bit.is_decimal()
True
>>> bit.is_bit()
True
>>> bit.name
'Bit'
>>> bit.alignment
Alignment(byte_size=1, bit_offset=0)
>>> bit.byte_order
Byteorder.auto = 'auto'
>>> bit.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> bit.index_field()
Index(byte=0, bit=1, address=0, base_address=0, update=False)
>>> bit.bit_size
1
>>> bit.signed
False
>>> bit.min()
0
>>> bit.max()
1
>>> bit.value
0
>>> bit.signed
False
>>> bit.value
0
>>> bytes(bit)
b'\x00'
>>> int(bit)
0
>>> float(bit)
0.0
>>> hex(bit)
'0x0'
>>> bin(bit)
'0b0'
>>> oct(bit)
'0o0'
>>> bool(bit)
False
>>> bit.as_signed()
0
>>> bit.as_unsigned()
0
>>> bit.deserialize(bytes.fromhex('01'))
Index(byte=0, bit=1, address=0, base_address=0, update=False)
>>> bit.value
1
>>> bit.value = 0
>>> bit.value
0
>>> bit.value = False
>>> bit.value
0
>>> bit.value = True
>>> bit.value
1
>>> bit.value = -1
>>> bit.value
0
>>> bit.value = 2
>>> bit.value
1
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> bit.serialize(bytestream)
Index(byte=0, bit=1, address=0, base_address=0, update=False)
>>> bytestream.hex()
'01'
>>> bit.describe()
{'address': 0,
 'alignment': [1, 0],
 'class': 'Bit',
 'index': [0, 0],
 'max': 1,
 'min': 0,
 'name': 'Bit',
 'order': 'auto',
 'signed': False,
 'size': 1,
 'type': 'Field',
 'value': 1}

property name: str

Returns the type name of the Bit field (read-only).

static is_bit() → bool

Returns True.

Byte

class konfoo.Byte(align_to: int | None = None)

The Byte field is an unsigned Decimal field with a size of one byte, and returns its field value as a lowercase hexadecimal string prefixed with 0x.

Parameters:

align_to (int|None) – aligns the Byte field to the number of bytes, can be between 1 and 8. If no field alignment is set the Byte field aligns itself to the next matching byte size according to the size of the Byte field.

Example:

>>> byte = Byte()
>>> byte.is_decimal()
True
>>> byte.name
'Byte'
>>> byte.alignment
Alignment(byte_size=1, bit_offset=0)
>>> byte.byte_order
Byteorder.auto = 'auto'
>>> byte.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> byte.index_field()
Index(byte=1, bit=0, address=1, base_address=0, update=False)
>>> byte.bit_size
8
>>> byte.signed
False
>>> byte.min()
0
>>> byte.max()
255
>>> byte.value
'0x0'
>>> bytes(byte)
b'\x00'
>>> int(byte)
0
>>> float(byte)
0.0
>>> hex(byte)
'0x0'
>>> bin(byte)
'0b0'
>>> oct(byte)
'0o0'
>>> bool(byte)
False
>>> byte.as_signed()
0
>>> byte.as_unsigned()
0
>>> byte.deserialize(bytes.fromhex('20'))
Index(byte=1, bit=0, address=1, base_address=0, update=False)
>>> byte.value
'0x20'
>>> byte.value = 16
>>> byte.value
'0x10'
>>> byte.value = -1
>>> byte.value
'0x0'
>>> byte.value = 256
>>> byte.value
'0xff'
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> byte.serialize(bytestream)
Index(byte=1, bit=0, address=1, base_address=0, update=False)
>>> bytestream.hex()
'ff'
>>> byte.describe()
{'address': 0,
 'alignment': [1, 0],
 'class': 'Byte',
 'index': [0, 0],
 'max': 255,
 'min': 0,
 'name': 'Byte',
 'order': 'auto',
 'signed': False,
 'size': 8,
 'type': 'Field',
 'value': '0xff'}

property name: str

Returns the type name of the Byte field (read-only).

property value: str

Field value as a lowercase hexadecimal string prefixed with 0x.

Char

class konfoo.Char(align_to: int | None = None)

The Char field is an unsigned Decimal field with a size of one byte, and returns its field value as a unicode string character.

Parameters:

align_to (int|None) – aligns the Char field to the number of bytes, can be between 1 and 8. If no field alignment is set the Char field aligns itself to the next matching byte size according to the size of the Char field.

Example:

>>> char = Char()
>>> char.is_decimal()
True
>>> char.name
'Char'
>>> char.alignment
Alignment(byte_size=1, bit_offset=0)
>>> char.byte_order
Byteorder.auto = 'auto'
>>> char.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> char.index_field()
Index(byte=1, bit=0, address=1, base_address=0, update=False)
>>> char.bit_size
8
>>> char.signed
False
>>> char.min()
0
>>> char.max()
255
>>> char.value
'\x00'
>>> bytes(char)
b'\x00'
>>> ord(char.value)
0
>>> int(char)
0
>>> float(char)
0.0
>>> hex(char)
'0x0'
>>> bin(char)
'0b0'
>>> oct(char)
'0o0'
>>> bool(char)
False
>>> char.as_signed()
0
>>> char.as_unsigned()
0
>>> char.deserialize(bytes.fromhex('41'))
Index(byte=1, bit=0, address=1, base_address=0, update=False)
>>> char.value
'A'
>>> char.value = 66
>>> char.value
'B'
>>> char.value = 0x41
>>> char.value
'A'
>>> char.value = 'F'
>>> char.value
'F'
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> char.serialize(bytestream)
Index(byte=1, bit=0, address=1, base_address=0, update=False)
>>> bytestream.hex()
'46'
>>> char.describe()
{'address': 0,
 'alignment': [1, 0],
 'class': 'Char',
 'index': [0, 0],
 'max': 255,
 'min': 0,
 'name': 'Char',
 'order': 'auto',
 'signed': False,
 'size': 8,
 'type': 'Field',
 'value': 'F'}

property name: str

Returns the type name of the Char field (read-only).

property value: str

Field value as a unicode string character.

Signed

class konfoo.Signed(bit_size: int, align_to: int | None = None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Signed field is a signed Decimal field with a variable size, and returns its field value as a signed integer number.

Parameters:

• bit_size (int) – is the size of the Signed field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the Signed field to the number of bytes, can be between 1 and 8. If no field alignment is set the Signed field aligns itself to the next matching byte size according to the size of the Signed field.

• byte_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the Signed field.

Example:

>>> signed = Signed(16)
>>> signed.is_decimal()
True
>>> signed.name
'Signed16'
>>> signed.alignment
Alignment(byte_size=2, bit_offset=0)
>>> signed.byte_order
Byteorder.auto = 'auto'
>>> signed.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> signed.index_field()
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> signed.bit_size
16
>>> signed.signed
True
>>> signed.min()
-32768
>>> signed.max()
32767
>>> signed.value
0
>>> bytes(signed)
b'\x00\x00'
>>> int(signed)
0
>>> float(signed)
0.0
>>> hex(signed)
'0x0'
>>> bin(signed)
'0b0'
>>> oct(signed)
'0o0'
>>> bool(signed)
False
>>> signed.as_signed()
0
>>> signed.as_unsigned()
0
>>> signed.deserialize(bytes.fromhex('00c0'))
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> signed.value
-16384
>>> signed.value = -0x4000
>>> signed.value
-16384
>>> signed.value = -32769
>>> signed.value
-32768
>>> signed.value = 32768
>>> signed.value
32767
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> signed.serialize(bytestream)
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> bytestream.hex()
'ff7f'
>>> signed.describe()
{'address': 0,
 'alignment': [2, 0],
 'class': 'Signed16',
 'index': [0, 0],
 'max': 32767,
 'min': -32768,
 'name': 'Signed16',
 'order': 'auto',
 'signed': True,
 'size': 16,
 'type': 'Field',
 'value': 32767}

class konfoo.Signed8(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Signed8 field is a Signed field with a size of one byte.

class konfoo.Signed16(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Signed16 field is a Signed field with a size of two bytes.

class konfoo.Signed24(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Signed24 field is a Signed field with a size of three bytes.

class konfoo.Signed32(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Signed32 field is a Signed field with a size of four bytes.

class konfoo.Signed64(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Signed64 field is a Signed field with a size of eight bytes.

Unsigned

class konfoo.Unsigned(bit_size: int, align_to: int | None = None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Unsigned field is an unsigned Decimal field with a variable size, and returns its field value as a lowercase hexadecimal string prefixed with 0x.

Parameters:

• bit_size (int) – is the size of the Unsigned field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the Unsigned field to the number of bytes, can be between 1 and 8. If no field alignment is set the Unsigned field aligns itself to the next matching byte size according to the size of the Unsigned field.

• byte_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the Unsigned field.

Example:

>>> unsigned = Unsigned(16)
>>> unsigned.is_decimal()
True
>>> unsigned.name
'Unsigned16'
>>> unsigned.alignment
Alignment(byte_size=2, bit_offset=0)
>>> unsigned.byte_order
Byteorder.auto = 'auto'
>>> unsigned.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> unsigned.index_field()
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> unsigned.bit_size
16
>>> unsigned.signed
False
>>> unsigned.min()
0
>>> unsigned.max()
65535
>>> unsigned.value
'0x0'
>>> bytes(unsigned)
b'\x00\x00'
>>> int(unsigned)
0
>>> float(unsigned)
0.0
>>> hex(unsigned)
'0x0'
>>> bin(unsigned)
'0b0'
>>> oct(unsigned)
'0o0'
>>> bool(unsigned)
False
>>> unsigned.as_signed()
0
>>> unsigned.as_unsigned()
0
>>> unsigned.deserialize(bytes.fromhex('00c0'))
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> unsigned.value
'0xc000'
>>> unsigned.value = 0x4000
>>> unsigned.value
'0x4000'
>>> unsigned.value = -0x1
>>> unsigned.value
'0x0'
>>> unsigned.value = 0x10000
>>> unsigned.value
'0xffff'
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> unsigned.serialize(bytestream)
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> bytestream.hex()
'ffff'
>>> unsigned.describe()
{'address': 0,
 'alignment': [2, 0],
 'class': 'Unsigned16',
 'index': [0, 0],
 'max': 65535,
 'min': 0,
 'name': 'Unsigned16',
 'order': 'auto',
 'signed': False,
 'size': 16,
 'type': 'Field',
 'value': '0xffff'}

property value: str

Field value as a lowercase hexadecimal string prefixed with 0x.

class konfoo.Unsigned8(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Unsigned8 field is an Unsigned field with a size of one byte.

class konfoo.Unsigned16(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Unsigned16 field is an Unsigned field with a size of two bytes.

class konfoo.Unsigned24(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Unsigned24 field is an Unsigned field with a size of three bytes.

class konfoo.Unsigned32(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Unsigned32 field is an Unsigned field with a size of four bytes.

class konfoo.Unsigned64(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Unsigned64 field is an Unsigned field with a size of eight bytes.

Bitset

class konfoo.Bitset(bit_size: int, align_to: int | None = None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Bitset field is an unsigned Decimal field with a variable size and returns its field value as a binary string prefixed with 0b.

Parameters:

• bit_size (int) – is the size of the Bitset field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the Bitset field to the number of bytes, can be between 1 and 8. If no field alignment is set the Bitset field aligns itself to the next matching byte size according to the size of the Bitset field.

• byte_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the Bitset field.

Example:

>>> bitset = Bitset(16)
>>> bitset.is_decimal()
True
>>> bitset.name
'Bitset16'
>>> bitset.alignment
Alignment(byte_size=2, bit_offset=0)
>>> bitset.byte_order
Byteorder.auto = 'auto'
>>> bitset.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> bitset.index_field()
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> bitset.bit_size
16
>>> bitset.signed
False
>>> bitset.min()
0
>>> bitset.max()
65535
>>> bitset.value
'0b0000000000000000'
>>> bytes(bitset)
b'\x00\x00'
>>> int(bitset)
0
>>> float(bitset)
0.0
>>> hex(bitset)
'0x0'
>>> bin(bitset)
'0b0'
>>> oct(bitset)
'0o0'
>>> bool(bitset)
False
>>> bitset.as_signed()
0
>>> bitset.as_unsigned()
0
>>> bitset.deserialize(bytes.fromhex('f00f'))
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> bitset.value
'0b0000111111110000'
>>> bitset.value = 0b1111
>>> bitset.value
'0b0000000000001111'
>>> bitset.value = -1
>>> bitset.value
'0b0000000000000000'
>>> bitset.value = 0x10000
>>> bitset.value
'0b1111111111111111'
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> bitset.serialize(bytestream)
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> bytestream.hex()
'ffff'
>>> bitset.describe()
{'address': 0,
 'alignment': [2, 0],
 'class': 'Bitset16',
 'index': [0, 0],
 'max': 65535,
 'min': 0,
 'name': 'Bitset16',
 'order': 'auto',
 'signed': False,
 'size': 16,
 'type': 'Field',
 'value': '0b1111111111111111'}

property value: str

Field value as a binary string prefixed with 0b.

class konfoo.Bitset8(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Bitset8 field is a Bitset field with a size of one byte.

class konfoo.Bitset16(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Bitset16 field is a Bitset field with a size of two bytes.

class konfoo.Bitset24(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Bitset24 field is a Bitset field with a size of three bytes.

class konfoo.Bitset32(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Bitset32 field is a Bitset field with a size of four bytes.

class konfoo.Bitset64(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Bitset64 field is a Bitset field with a size of eight bytes.

Bool

class konfoo.Bool(bit_size: int, align_to: int | None = None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Bool field is an unsigned Decimal field with a variable size, and returns its field value as a boolean value.

Parameters:

• bit_size (int) – is the size of the Bool field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the Bool field to the number of bytes, can be between 1 and 8. If no field alignment is set the Bool field aligns itself to the next matching byte size according to the size of the Bool field.

• byte_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the Bool field.

Example:

>>> boolean = Bool(16)
>>> boolean.is_decimal()
True
>>> boolean.is_bool()
True
>>> boolean.name
'Bool16'
>>> boolean.alignment
Alignment(byte_size=2, bit_offset=0)
>>> boolean.byte_order
Byteorder.auto = 'auto'
>>> boolean.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> boolean.index_field()
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> boolean.bit_size
16
>>> boolean.signed
False
>>> boolean.min()
0
>>> boolean.max()
65535
>>> boolean.value
False
>>> bytes(boolean)
b'\x00\x00'
>>> int(boolean)
0
>>> float(boolean)
0.0
>>> hex(boolean)
'0x0'
>>> bin(boolean)
'0b0'
>>> oct(boolean)
'0o0'
>>> bool(boolean)
False
>>> boolean.as_signed()
0
>>> boolean.as_unsigned()
0
>>> boolean.deserialize(bytes.fromhex('0f00'))
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> boolean.value
True
>>> boolean.value = False
>>> boolean.value
False
>>> boolean.value = -1
>>> boolean.value
False
>>> boolean.value = 0x10000
>>> boolean.value
True
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> boolean.serialize(bytestream)
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> bytestream.hex()
'ffff'
>>> boolean.describe()
{'address': 0,
 'alignment': [2, 0],
 'class': 'Bool16',
 'index': [0, 0],
 'max': 65535,
 'min': 0,
 'name': 'Bool16',
 'order': 'auto',
 'signed': False,
 'size': 16,
 'type': 'Field',
 'value': True}

property value: bool

Field value as a boolean value, True or False.

static is_bool() → bool

Returns True.

class konfoo.Bool8(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Bool8 field is a Bool field with a size of one byte.

class konfoo.Bool16(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Bool16 field is a Bool field with a size of two bytes.

class konfoo.Bool24(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Bool24 field is a Bool field with a size of three bytes.

class konfoo.Bool32(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Bool32 field is a Bool field with a size of four bytes.

class konfoo.Bool64(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Bool64 field is a Bool field with a size of eight bytes.

Enum

class konfoo.Enum(bit_size: int, align_to: int | None = None, enumeration: Type[Enumeration] | None = None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Enum field is an unsigned Decimal field with a variable size, and returns its field value as an unsigned integer number.

If an Enumeration is available and a member matches the integer number then the member name string is returned otherwise the integer number is returned.

Parameters:

• bit_size (int) – is the size of the Enum field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the Enum field to the number of bytes, can be between 1 and 8. If no field alignment is set the Enum field aligns itself to the next matching byte size according to the size of the Enum field.

• enumeration (Type[Enumeration]|None) – Enumeration definition of the Enum field.

• byte_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the Enum field.

Example:

>>> enum = Enum(16, enumeration=ItemClass)
>>> enum.is_decimal()
True
>>> enum.name
'Enum16'
>>> enum.alignment
Alignment(byte_size=2, bit_offset=0)
>>> enum.byte_order
Byteorder.auto = 'auto'
>>> enum.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> enum.index_field()
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> enum.bit_size
16
>>> enum.signed
False
>>> bytes(enum)
b'\x00\x00'
>>> enum.min()
0
>>> enum.max()
65535
>>> enum.value
0
>>> int(enum)
0
>>> float(enum)
0.0
>>> hex(enum)
'0x0'
>>> bin(enum)
'0b0'
>>> oct(enum)
'0o0'
>>> bool(enum)
False
>>> enum.as_signed()
0
>>> enum.as_unsigned()
0
>>> enum.deserialize(bytes.fromhex('2800'))
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> enum.value
'Decimal'
>>> enum.value = 48
>>> enum.value
'Enum'
>>> enum.value = 'Enum'
>>> enum.value
'Enum'
>>> enum.value = 40
>>> enum.value
'Decimal'
>>> enum.value = -1
>>> enum.value
0
>>> enum.value = 65536
>>> enum.value
65535
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> enum.serialize(bytestream)
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> bytestream.hex()
'ffff'
>>> enum.describe()
{'address': 0,
 'alignment': [2, 0],
 'class': 'Enum16',
 'index': [0, 0],
 'max': 65535,
 'min': 0,
 'name': 'Enum16',
 'order': 'auto',
 'signed': False,
 'size': 16,
 'type': 'Field',
 'value': 65535}

property value: int | str

Field value as an enum name string. Fall back is an unsigned integer number.

class konfoo.Antivalent(align_to: int | None = None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Antivalent field is an Enum field with a size of two bits and a fix assigned enumeration.

class Validity(value)

An enumeration.

class konfoo.Enum4(align_to: int | None = None, enumeration: Enumeration | None = None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Enum4 field is an Enum field with a size of four bits.

class konfoo.Enum8(enumeration: Enumeration | None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Enum8 field is an Enum field with a size of one byte.

class konfoo.Enum16(enumeration: Enumeration | None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Enum16 field is an Enum field with a size of two bytes.

class konfoo.Enum24(enumeration: Enumeration | None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Enum24 field is an Enum field with a size of three bytes.

class konfoo.Enum32(enumeration: Enumeration | None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Enum32 field is an Enum field with a size of four bytes.

class konfoo.Enum64(enumeration: Enumeration | None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Enum64 field is an Enum field with a size of eight bytes.

Scaled

class konfoo.Scaled(scale: float | int, bit_size: int, align_to: int | None = None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Scaled field is a signed Decimal field with a variable size, and returns its scaled field value as a floating-point number.

The scaled field value is:

(unscaled field value / scaling base) * scaling factor

The unscaled field value is:

(scaled field value / scaling factor) * scaling base

The scaling base is:

2 ** (field size - 1) / 2

A Scaled field extends the metadata of a Decimal with a 'scale' key for its scaling factor.

Parameters:

• scale (float|int) – scaling factor of the Scaled field.

• bit_size (int) – is the size of the Scaled field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the Scaled field to the number of bytes, can be between 1 and 8. If no field alignment is set the Scaled field aligns itself to the next matching byte size according to the size of the Scaled field.

• byte_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the Scaled field.

Example:

>>> scaled = Scaled(100, 16)
>>> scaled.is_decimal()
True
>>> scaled.name
'Scaled16'
>>> scaled.alignment
Alignment(byte_size=2, bit_offset=0)
>>> scaled.byte_order
Byteorder.auto = 'auto'
>>> scaled.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> scaled.index_field()
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> scaled.scale
100.0
>>> scaled.scaling_base()
16384.0
>>> scaled.bit_size
16
>>> scaled.signed
True
>>> scaled.min()
-32768
>>> scaled.max()
32767
>>> scaled.value
0.0
>>> bytes(scaled)
b'\x00\x00'
>>> int(scaled)
0
>>> float(scaled)
0.0
>>> hex(scaled)
'0x0'
>>> bin(scaled)
'0b0'
>>> oct(scaled)
'0o0'
>>> bool(scaled)
False
>>> scaled.as_signed()
0
>>> scaled.as_unsigned()
0
>>> scaled.deserialize(bytes.fromhex('0040'))
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> scaled.value
100.0
>>> scaled.value = -100
>>> scaled.value
-100.0
>>> scaled.value = -200.001
>>> scaled.value
-200.0
>>> scaled.value = 200
>>> scaled.value
199.993896484375
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> scaled.serialize(bytestream)
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> bytestream.hex()
'ff7f'
>>> scaled.describe()
{'address': 0,
 'alignment': [2, 0],
 'class': 'Scaled16',
 'index': [0, 0],
 'max': 32767,
 'min': -32768,
 'name': 'Scaled16',
 'order': 'auto',
 'scale': 100.0,
 'signed': True,
 'size': 16,
 'type': 'Field',
 'value': 199.993896484375}

property value: float

Field value as a floating-point number.

property scale: float

Scaling factor of the Scaled field.

scaling_base()

Returns the scaling base of the Scaled field.

class konfoo.Scaled8(scale: float | int, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Scaled8 field is a Scaled field with a size of one byte.

class konfoo.Scaled16(scale: float | int, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Scaled16 field is a Scaled field with a size of two bytes.

class konfoo.Scaled24(scale: float | int, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Scaled24 field is a Scaled field with a size of three bytes.

class konfoo.Scaled32(scale: float | int, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Scaled32 field is a Scaled field with a size of four bytes.

class konfoo.Scaled64(scale: float | int, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Scaled64 field is a Scaled field with a size of eight bytes.

Fraction

class konfoo.Fraction(bits_integer: int, bit_size: int, align_to: int | None = None, signed: bool = False, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Fraction field is an unsigned Decimal field with a variable size, and returns its fractional field value as a floating-point number.

A fractional number is bitwise encoded and has up to three bit parts for this task.

The first part are the bits for the fraction part of a fractional number. The number of bits for the fraction part is derived from the bit size of the field and the required bits for the other two parts. The fraction part is always smaller than one.

fraction part = (2**bits - 1) / (2**bits)

The second part are the bits for the integer part of a fractional number.

integer part = (2**bits - 1)

The third part is the bit for the sign of a signed fractional number. Only a signed fractional number posses this bit.

sign part = {'0': '+', '1': '-'}

A fractional number is multiplied by hundred.

Parameters:

• bits_integer (int) – number of bits for the integer part of the fraction number, can be between 1 and the size of the Fraction field.

• bit_size (int) – is the size of the Fraction field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the Fraction field to the number of bytes, can be between 1 and 8. If no field alignment is set the Fraction field aligns itself to the next matching byte size according to the size of the Fraction field.

• signed (bool) – if True the Fraction field is signed otherwise unsigned.

• byte_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the Fraction field

Example:

>>> unipolar = Fraction(2, 16)
>>> unipolar.is_decimal()
True
>>> unipolar.name
'Fraction2.16'
>>> unipolar.alignment
Alignment(byte_size=2, bit_offset=0)
>>> unipolar.byte_order
Byteorder.auto = 'auto'
>>> unipolar.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> unipolar.index_field()
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> unipolar.bit_size
16
>>> unipolar.signed
False
>>> unipolar.min()
0
>>> unipolar.max()
65535
>>> unipolar.value
0.0
>>> bytes(unipolar)
b'\x00\x00'
>>> int(unipolar)
0
>>> float(unipolar)
0.0
>>> hex(unipolar)
'0x0'
>>> bin(unipolar)
'0b0'
>>> oct(unipolar)
'0o0'
>>> bool(unipolar)
False
>>> unipolar.as_signed()
0
>>> unipolar.as_unsigned()
0
>>> unipolar.deserialize(bytes.fromhex('0080'))
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> unipolar.value
200.0
>>> unipolar.value = 100
>>> unipolar.value
100.0
>>> unipolar.as_float(0x4000)
100.0
>>> unipolar.value = -1
>>> unipolar.value
0.0
>>> unipolar.value = 400
>>> unipolar.value
399.993896484375
>>> unipolar.as_float(0xffff)
399.993896484375
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> unipolar.serialize(bytestream)
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> bytestream.hex()
'ffff'
>>> unipolar.describe()
{'address': 0,
 'alignment': [2, 0],
 'class': 'Fraction2.16',
 'index': [0, 0],
 'max': 65535,
 'min': 0,
 'name': 'Fraction2.16',
 'order': 'auto',
 'signed': False,
 'size': 16,
 'type': 'Field',
 'value': 399.993896484375}

Example:

>>> bipolar = Fraction(2, 16, 2, True)
>>> bipolar.is_decimal()
True
>>> bipolar.name
'Fraction2.16'
>>> bipolar.alignment
Alignment(byte_size=2, bit_offset=0)
>>> bipolar.byte_order
Byteorder.auto = 'auto'
>>> bipolar.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> bipolar.index_field()
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> bipolar.bit_size
16
>>> bipolar.signed
False
>>> bipolar.min()
0
>>> bipolar.max()
65535
>>> bipolar.value
0.0
>>> bytes(bipolar)
b'\x00\x00'
>>> int(bipolar)
0
>>> float(bipolar)
0.0
>>> hex(bipolar)
'0x0'
>>> bin(bipolar)
'0b0'
>>> oct(bipolar)
'0o0'
>>> bool(bipolar)
False
>>> bipolar.as_signed()
0
>>> bipolar.as_unsigned()
0
>>> bipolar.deserialize(bytes.fromhex('0040'))
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> bipolar.value
100.0
>>> bipolar.value = -100
>>> bipolar.value
-100.0
>>> bipolar.as_float(0xc000)
-100.0
>>> bipolar.as_float(0x8000)
-0.0
>>> bipolar.value = -200
>>> bipolar.value
-199.993896484375
>>> bipolar.as_float(0xffff)
-199.993896484375
>>> bipolar.value = 200
>>> bipolar.value
199.993896484375
>>> bipolar.as_float(0x7fff)
199.993896484375
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> bipolar.serialize(bytestream)
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> bytestream.hex()
'ff7f'
>>> bipolar.describe()
{'address': 0,
 'alignment': [2, 0],
 'class': 'Fraction2.16',
 'index': [0, 0],
 'max': 65535,
 'min': 0,
 'name': 'Fraction2.16',
 'order': 'auto',
 'signed': True,
 'size': 16,
 'type': 'Field',
 'value': 199.993896484375}

property name: str

Returns the type name of the Fraction field (read-only).

property value: float

Field value as a floating-point number.

Bipolar

class konfoo.Bipolar(bits_integer: int, bit_size: int, align_to: int | None = None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Bipolar field is a signed Fraction field with a variable size, and returns its fractional field value as a floating-point number.

Parameters:

• bits_integer (int) – number of bits for the integer part of the fraction number, can be between 1 and the size of the Bipolar field.

• bit_size (int) – is the size of the Bipolar field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the Bipolar field to the number of bytes, can be between 1 and 8. If no field alignment is set the Bipolar field aligns itself to the next matching byte size according to the size of the Bipolar field.

• byte_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the Bipolar field.

Example:

>>> bipolar = Bipolar(2, 16)
>>> bipolar.is_decimal()
True
>>> bipolar.name
'Bipolar2.16'
>>> bipolar.alignment
Alignment(byte_size=2, bit_offset=0)
>>> bipolar.byte_order
Byteorder.auto = 'auto'
>>> bipolar.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> bipolar.index_field()
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> bipolar.bit_size
16
>>> bipolar.signed
False
>>> bipolar.min()
0
>>> bipolar.max()
65535
>>> bipolar.value
0.0
>>> bytes(bipolar)
b'\x00\x00'
>>> int(bipolar)
0
>>> float(bipolar)
0.0
>>> hex(bipolar)
'0x0'
>>> bin(bipolar)
'0b0'
>>> oct(bipolar)
'0o0'
>>> bool(bipolar)
False
>>> bipolar.as_signed()
0
>>> bipolar.as_unsigned()
0
>>> bipolar.value = -100
>>> bipolar.value
-100.0
>>> bipolar.as_float(0xc000)
-100.0
>>> bipolar.as_float(0x8000)
-0.0
>>> bipolar.value = -200
>>> bipolar.value
-199.993896484375
>>> bipolar.as_float(0xffff)
-199.993896484375
>>> bipolar.value = 200
>>> bipolar.value
199.993896484375
>>> bipolar.as_float(0x7fff)
199.993896484375
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> bipolar.serialize(bytestream)
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> bytestream.hex()
'ff7f'
>>> bipolar.describe()
{'address': 0,
 'alignment': [2, 0],
 'class': 'Bipolar2.16',
 'index': [0, 0],
 'max': 65535,
 'min': 0,
 'name': 'Bipolar2.16',
 'order': 'auto',
 'signed': True,
 'size': 16,
 'type': 'Field',
 'value': 199.993896484375}

class konfoo.Bipolar2(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Bipolar2 field is a Bipolar field with a size of two bytes and an integer part of two bits.

class konfoo.Bipolar4(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Bipolar4 field is a Bipolar field with a size of two bytes and an integer part of four bits.

Unipolar

class konfoo.Unipolar(bits_integer: int, bit_size: int, align_to: int | None = None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Unipolar field is an unsigned Fraction field with a variable size, and returns its fractional field value as a floating-point number.

Parameters:

• bits_integer (int) – number of bits for the integer part of the fraction number, can be between 1 and the size of the Unipolar field.

• bit_size (int) – is the size of the Unipolar field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the Unipolar field to the number of bytes, can be between 1 and 8. If no field alignment is set the Unipolar field aligns itself to the next matching byte size according to the size of the Unipolar field.

• byte_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the Unipolar field.

Example:

>>> unipolar = Unipolar(2, 16)
>>> unipolar.is_decimal()
True
>>> unipolar.name
'Unipolar2.16'
>>> unipolar.alignment
Alignment(byte_size=2, bit_offset=0)
>>> unipolar.byte_order
Byteorder.auto = 'auto'
>>> unipolar.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> unipolar.index_field()
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> unipolar.bit_size
16
>>> unipolar.signed
False
>>> unipolar.min()
0
>>> unipolar.max()
65535
>>> unipolar.value
0.0
>>> bytes(unipolar)
b'\x00\x00'
>>> int(unipolar)
0
>>> float(unipolar)
0.0
>>> hex(unipolar)
'0x0'
>>> bin(unipolar)
'0b0'
>>> oct(unipolar)
'0o0'
>>> bool(unipolar)
False
>>> unipolar.as_signed()
0
>>> unipolar.as_unsigned()
0
>>> unipolar.deserialize(bytes.fromhex('0080'))
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> unipolar.value
200.0
>>> unipolar.value = 100
>>> unipolar.value
100.0
>>> unipolar.as_float(0x4000)
100.0
>>> unipolar.value = -1
>>> unipolar.value
0.0
>>> unipolar.value = 400
>>> unipolar.value
399.993896484375
>>> unipolar.as_float(0xffff)
399.993896484375
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> unipolar.serialize(bytestream)
Index(byte=2, bit=0, address=2, base_address=0, update=False)
>>> bytestream.hex()
'ffff'
>>> unipolar.describe()
{'address': 0,
 'alignment': [2, 0],
 'class': 'Unipolar2.16',
 'index': [0, 0],
 'max': 65535,
 'min': 0,
 'name': 'Unipolar2.16',
 'order': 'auto',
 'signed': False,
 'size': 16,
 'type': 'Field',
 'value': 399.993896484375}

class konfoo.Unipolar2(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Unipolar2 field is an Unipolar field with a size of two bytes and an integer part of two bits.

Datetime

class konfoo.Datetime(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Datetime field is an unsigned Decimal field with a fix size of four bytes, and returns its field value as an UTC datetime string in the ISO format YYYY-mm-dd HH:MM:SS.

Parameters:

byte_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the Datetime field.

Example:

>>> datetime = Datetime()
>>> datetime.is_decimal()
True
>>> datetime.name
'Datetime32'
>>> datetime.alignment
Alignment(byte_size=4, bit_offset=0)
>>> datetime.byte_order
Byteorder.auto = 'auto'
>>> datetime.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> datetime.index_field()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> datetime.bit_size
32
>>> datetime.signed
False
>>> datetime.min()
0
>>> datetime.max()
4294967295
>>> datetime.value
'1970-01-01 00:00:00'
>>> bytes(datetime)
b'\x00\x00\x00\x00'
>>> int(datetime)
0
>>> float(datetime)
0.0
>>> hex(datetime)
'0x0'
>>> bin(datetime)
'0b0'
>>> oct(datetime)
'0o0'
>>> bool(datetime)
False
>>> datetime.as_signed()
0
>>> datetime.as_unsigned()
0
>>> datetime.deserialize(bytes.fromhex('ffffffff'))
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> datetime.value
'2106-02-07 06:28:15'
>>> datetime.value = '1969-12-31 23:59:59'
>>> datetime.value
'1970-01-01 00:00:00'
>>> datetime.value = '2106-02-07 06:28:16'
>>> datetime.value
'2106-02-07 06:28:15'
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> datetime.serialize(bytestream)
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> bytestream.hex()
'ffffffff'
>>> datetime.describe()
{'address': 0,
 'alignment': [4, 0],
 'class': 'Datetime32',
 'index': [0, 0],
 'max': 4294967295,
 'min': 0,
 'name': 'Datetime32',
 'order': 'auto',
 'signed': False,
 'size': 32,
 'type': 'Field',
 'value': '2106-02-07 06:28:15'}

property value: str

Field value as an UTC datetime string in the ISO format YYYY-mm-dd HH:MM:SS

IPv4Address

class konfoo.IPv4Address(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The IPv4Address field is an unsigned Decimal field with a fix size of four bytes and returns its field value as an IPv4 address formatted string.

Parameters:

byte_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the IPv4Address field.

Example:

>>> ipv4 = IPv4Address()
>>> ipv4.is_decimal()
True
>>> ipv4.name
'Ipaddress32'
>>> ipv4.alignment
Alignment(byte_size=4, bit_offset=0)
>>> ipv4.byte_order
Byteorder.auto = 'auto'
>>> ipv4.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> ipv4.index_field()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> ipv4.bit_size
32
>>> ipv4.signed
False
>>> ipv4.min()
0
>>> ipv4.max()
4294967295
>>> ipv4.value
'0.0.0.0'
>>> bytes(ipv4)
b'\x00\x00\x00\x00'
>>> int(ipv4)
0
>>> float(ipv4)
0.0
>>> hex(ipv4)
'0x0'
>>> bin(ipv4)
'0b0'
>>> oct(ipv4)
'0o0'
>>> bool(ipv4)
False
>>> ipv4.as_signed()
0
>>> ipv4.as_unsigned()
0
>>> ipv4.deserialize(bytes.fromhex('ffffffff'))
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> ipv4.value
'255.255.255.255'
>>> ipv4.value = '192.168.0.0'
>>> ipv4.value
'192.168.0.0'
>>> ipv4.value = '255.255.255.255'
>>> ipv4.value
'255.255.255.255'
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> ipv4.serialize(bytestream)
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> bytestream.hex()
'ffffffff'
>>> ipv4.describe()
{'address': 0,
 'alignment': [4, 0],
 'class': 'Ipaddress32',
 'index': [0, 0],
 'max': 4294967295,
 'min': 0,
 'name': 'Ipaddress32',
 'order': 'auto',
 'signed': False,
 'size': 32,
 'type': 'Field',
 'value': '255.255.255.255'}

property value: str

Field value as an IPv4 address formatted string.

Pointer

class konfoo.Pointer(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Pointer field is an unsigned Decimal field with a size of four bytes, and returns its field value as a hexadecimal string.

A Pointer field refers absolutely to a data object of a data Provider.

The Pointer class extends the Decimal field with the Container interface for its referenced data object.

A Pointer field has additional features to read, write, deserialize, serialize and view binary data:

• Deserialize the value for each Field in the data object referenced by the Pointer field from a byte stream via deserialize_data().

• Serialize the value for each Field in the data object referenced by the Pointer field to a byte stream via serialize_data().

• Indexes each Field in the data object referenced by the Pointer field via index_data().

• Read from a Provider the necessary bytes for the data object referenced by the Pointer field via read_from().

• Write to a Provider the necessary bytes for the data object referenced by the Pointer field via write_to().

• Get the accumulated size of all fields in the data object referenced by the Pointer field via data_size.

• Indexes the Pointer field and each Field in the data object referenced by the Pointer field via index_fields().

• View the selected attributes of the Pointer field and for each Field in the data object referenced by the Pointer field via view_fields().

• List the path to the field and the field item for the Pointer field and for each Field in the data object referenced by the Pointer field as a flatted list via field_items().

• Get the metadata of the Pointer field via describe().

Parameters:

• template (Structure|Sequence|Field|None) – template for the data object referenced by the Pointer field.

• address (int|None) – absolute address of the data object referenced by the Pointer field.

• data_order (Byteorder|Literal['big', 'little']) – byte order used to unpack and pack the data object referenced by the Pointer field.

• bit_size (int) – is the size of the Pointer field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the Pointer field to the number of bytes, can be between 1 and 8. If no field alignment is set the Pointer field aligns itself to the next matching byte size according to the size of the Pointer field.

• field_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the Pointer field.

Example:

>>> pointer = Pointer()
>>> pointer.is_decimal()
True
>>> pointer.is_pointer()
True
>>> pointer.name
'Pointer32'
>>> pointer.alignment
Alignment(byte_size=4, bit_offset=0)
>>> pointer.byte_order
Byteorder.auto = 'auto'
>>> pointer.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> pointer.index_field()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.bit_size
32
>>> pointer.signed
False
>>> pointer.min()
0
>>> pointer.max()
4294967295
>>> pointer.base_address
0
>>> pointer.address
0
>>> pointer.is_null()
True
>>> pointer.data
>>> pointer.data_size
0
>>> pointer.data_byte_order
Byteorder.little = 'little'
>>> pointer.bytestream
''
>>> pointer.value
'0x0'
>>> bytes(pointer)
b'\x00\x00\x00\x00'
>>> int(pointer)
0
>>> float(pointer)
0.0
>>> hex(pointer)
'0x0'
>>> bin(pointer)
'0b0'
>>> oct(pointer)
'0o0'
>>> bool(pointer)
False
>>> pointer.as_signed()
0
>>> pointer.as_unsigned()
0
>>> pointer.deserialize(bytes.fromhex('00c0'))
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.value
'0xc000'
>>> pointer.value = 0x4000
>>> pointer.value
'0x4000'
>>> pointer.initialize_fields({'value': 0x8000})
>>> pointer.value
'0x8000'
>>> pointer.value = -0x1
>>> pointer.value
'0x0'
>>> pointer.value = 0x100000000
>>> pointer.value
'0xffffffff'
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> pointer.serialize(bytestream)
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> bytestream.hex()
'ffffffff'
>>> pointer.bytestream = b'KonFoo is Fun'
>>> pointer.bytestream
'4b6f6e466f6f2069732046756e'
>>> pointer.serialize_data()
b''
>>> pointer.deserialize_data()
Index(byte=0, bit=0, address=4294967295, base_address=4294967295, update=False)
>>> pointer.serialize_data()
b''
>>> pointer.describe()
{'address': 0,
 'alignment': [4, 0],
 'class': 'Pointer',
 'index': [0, 0],
 'max': 4294967295,
 'min': 0,
 'name': 'Pointer',
 'order': 'auto',
 'signed': False,
 'size': 32,
 'type': 'Pointer',
 'value': '0xffffffff'}
>>> pointer.index_fields()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.view_fields()
{'value': '0xffffffff', 'data': None}
>>> pointer.to_json()
'{"value": "0xffffffff", "data": null}'
>>> pointer.field_items()
[('field',
  Pointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
          alignment=Alignment(byte_size=4, bit_offset=0),
          bit_size=32,
          value='0xffffffff'))]
>>> pointer.to_list()
[('Pointer.field', '0xffffffff')]
>>> pointer.to_dict()
{'Pointer': {'field': '0xffffffff'}}

property address: int

Returns the data source address of the data object referenced by the Pointer field (read-only).

property base_address: int

Returns the data source base address of the data object referenced by the Pointer field (read-only).

property bytestream: str

Byte stream of the Pointer field for the referenced data object. Returned as a lowercase hexadecimal encoded string.

property data: Structure | Sequence | Field | None

Data object referenced by the Pointer field.

property data_byte_order: Byteorder

Byteorder used to deserialize and serialize the data object referenced by the Pointer field.

property data_size: int

Returns the size of the data object in bytes (read-only).

property value: str

Field value as a lowercase hexadecimal string prefixed with 0x.

static is_pointer() → bool

Returns True.

is_null() → bool

Returns True if the Pointer field points to zero.

deserialize_data(buffer: bytes = b'', byte_order: Literal['big', 'little'] | Byteorder | None = None) → Index

De-serializes the data object referenced by the Pointer field from the byte buffer by mapping the bytes to the value for each Field in the data object in accordance with the decoding byte order for the de-serialization and the decoding byte_order of each Field in the data object.

A specific decoding byte_order of a Field in the data object overrules the decoding byte order for the de-serialization.

Returns the Index of the buffer after the last de-serialized Field in the data object.

Parameters:

• buffer (bytes) – byte stream. Default is the internal bytestream of the Pointer field.

• byte_order (Byteorder|Literal['big', 'little']) – decoding byte order for the de-serialization. Default is the data_byte_order of the Pointer field.

serialize_data(byte_order: Literal['big', 'little'] | Byteorder | None = None) → bytes

Serializes the data object referenced by the Pointer field to bytes by mapping the value for each Field in the data object to a number of bytes in accordance with the encoding byte order for the serialization and the encoding byte_order of each Field in the data object.

A specific encoding byte_order of a Field in the data object overrules the encoding byte order for the serialization.

Returns a number of bytes for the serialized data object referenced by the Pointer field.

Parameters:

byte_order (Byteorder|Literal['big', 'little']) – encoding byte order for the serialization. Default is the data_byte_order of the Pointer field.

index_data() → None

Indexes each Field in the data object referenced by the Pointer field.

read_from(provider: Provider, null_allowed: bool = False, **options: Any) → None

Reads from the data Provider the necessary number of bytes for the data object referenced by the Pointer field.

A Pointer field stores the binary data read from the data Provider in its bytestream.

Parameters:

• provider (Provider) – data Provider.

• null_allowed (bool) – if True read access of address zero (Null) is allowed.

• nested (bool) – if True all Pointer fields in the data object of the Pointer field reads their referenced data object fields as well (chained method call). Each Pointer field stores the bytes for its referenced data object in its bytestream.

patch(item: Structure | Sequence | Field, byte_order: Literal['big', 'little'] | Byteorder = Byteorder.little) → Patch | None

Returns a memory Patch for the given item that shall be patched in the data source.

Parameters:

• item (Structure|Sequence|Field) – item to patch.

• byte_order (Byteorder|Literal['big', 'little']) – encoding Byteorder for the item.

write_to(provider: Provider, item: Structure | Sequence | Field, byte_order: Byteorder = Byteorder.little) → None

Writes via a data Provider the Field values of the given item to the data source.

Parameters:

• provider (Provider) – data Provider.

• item (Structure|Sequence|Field) – item to write.

• byte_order (Byteorder) – encoding byte order of the item to write.

deserialize(buffer: bytes = b'', index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) → Index

De-serializes the Pointer field from the byte buffer starting at the beginning of the buffer or with the given index by mapping the bytes to the value of the Pointer field in accordance with the decoding byte order for the de-serialization and the decoding byte_order of the Pointer field.

The specific decoding byte_order of the Pointer field overrules the decoding byte order for the de-serialization.

Returns the Index of the buffer after the Pointer field.

Optional the de-serialization of the referenced data object of the Pointer field can be enabled.

Parameters:

• buffer (bytes) – byte stream to de-serialize from.

• index (Index) – current read Index within the buffer to de-serialize.

• byte_order (Byteorder|Literal['auto', 'big', 'little']) – decoding byte order for the de-serialization.

• nested (bool) – if True a Pointer field de-serialize its referenced data object as well (chained method call). Each Pointer field uses for the de-serialization of its referenced data object its own bytestream.

serialize(buffer: bytearray = bytearray(b''), index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) → Index

Serializes the Pointer field to the byte buffer starting at the beginning of the buffer or with the given index by mapping the value of the Pointer field to the byte buffer in accordance with the encoding byte order for the serialization and the encoding byte_order of the Pointer field.

The specific encoding byte_order of the Pointer field overrules the encoding byte order for the serialization.

Returns the Index of the buffer after the Pointer field.

Optional the serialization of the referenced data object of the Pointer field can be enabled.

Parameters:

• buffer (bytearray) – byte stream to serialize to.

• index (Index) – current write Index within the buffer.

• byte_order (Byteorder|Literal['auto', 'big', 'little']) – encoding byte order for the serialization.

• nested (bool) – if True a Pointer field serializes its referenced data object as well (chained method call). Each Pointer field uses for the serialization of its referenced data object its own bytestream.

initialize_fields(content: dict[str, Any]) → None

Initializes the Pointer field itself and the Field items in the data object referenced by the Pointer field with the values in the content dictionary.

The ['value'] key in the content dictionary refers to the Pointer field itself and the ['data'] key refers to the data object referenced by the Pointer field.

Parameters:

content (dict[str, Any]) – a dictionary contains the value for the Pointer field and the value for each Field in the data object referenced by the Pointer field.

index_fields(index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) → Index

Indexes the Pointer field and the data object referenced by the Pointer field starting with the given index and returns the Index after the Pointer field.

Parameters:

• index (Index) – Index for the Pointer field.

• nested (bool) – if True all Pointer fields in the data object referenced by the Pointer field indexes their referenced data object fields as well (chained method call).

view_fields(*attributes: str, **options: Any) → dict[str, Any]

Returns a dict which contains the selected field attributes of the Pointer field itself extended with a ['data'] key which contains the selected field attribute or the dictionaries of the selected field attributes for each Field nested in the data object referenced by the Pointer field.

The attributes of each Field for containers nested in the data object referenced by the Pointer field are viewed as well (chained method call).

Parameters:

• attributes (str) – selected Field attributes. Fallback is the field value.

• fieldnames (tuple[str, ...]) – sequence of dictionary keys for the selected field attributes. Defaults to (*attributes).

• nested (bool) – if True all Pointer fields in the data object referenced by the Pointer field views their referenced data object field attributes as well (chained method call).

field_items(path: str = '', **options: Any) → list[tuple[str, konfoo.core.Field]]

Returns a flatten list of ('field path', field item) tuples for the Pointer field itself and for each Field nested in the data object referenced by the Pointer field.

Parameters:

• path (str) – path of the Pointer field.

• nested (bool) – if True all Pointer fields in the data object referenced by the Pointer field lists their referenced data object field items as well (chained method call).

describe(name: str = '', **options: Any) → dict[str, Any]

Returns the metadata of a Pointer as a dict.

metadata = {
    'address': self.index.address,
    'alignment': [self.alignment.byte_size, self.alignment.bit_offset],
    'class': self.__class__.__name__,
    'index': [self.index.byte, self.index.bit],
    'max': self.max(),
    'min': self.min(),
    'name': name if name else self.__class__.__name__,
    'order': self.byte_order.value,
    'size': self.bit_size,
    'type': Pointer.item_type.name,
    'value': self.value,
    'member': [self.data.describe()]
}

Parameters:

• name (str) – optional name for the Pointer field. Fallback is the class name.

• nested (bool) – if True a Pointer field lists its referenced data object fields as well (chained method call). Default is True.

class konfoo.Pointer8(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little)

The Pointer8 field is a Pointer field with a Field size of one byte.

class konfoo.Pointer16(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Pointer16 field is a Pointer field with a Field size of two bytes.

class konfoo.Pointer24(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Pointer24 field is a Pointer field with a Field size of three bytes.

class konfoo.Pointer32(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Pointer32 field is a Pointer field with a Field size of four bytes.

class konfoo.Pointer48(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Pointer48 field is a Pointer field with a Field size of six bytes.

class konfoo.Pointer64(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The Pointer64 field is a Pointer field with a Field size of eight bytes.

Structure Pointer

class konfoo.StructurePointer(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StructurePointer field is a Pointer which refers to a Structure.

Parameters:

• template (Structure|None) – template for the data object referenced by the Pointer field. The template must be a Structure instance.

• address (int|None) – absolute address of the data object referenced by the Pointer field.

• data_order (Byteorder|Literal['big', 'little']) – byte order used to unpack and pack the data object referenced by the Pointer field.

• bit_size (int) – is the size of the Pointer field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the Pointer field to the number of bytes, can be between 1 and 8. If no field alignment is set the Pointer field aligns itself to the next matching byte size according to the size of the Pointer field.

• field_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the Pointer field.

Example:

>>> pointer = StructurePointer()
>>> pointer.is_decimal()
True
>>> pointer.is_pointer()
True
>>> pointer.name
'Pointer32'
>>> pointer.alignment
Alignment(byte_size=4, bit_offset=0)
>>> pointer.byte_order
Byteorder.auto = 'auto'
>>> pointer.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> pointer.index_field()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.bit_size
32
>>> pointer.signed
False
>>> pointer.min()
0
>>> pointer.max()
4294967295
>>> pointer.base_address
0
>>> pointer.address
0
>>> pointer.is_null()
True
>>> pointer.data
{}
>>> pointer.data_size
0
>>> pointer.data_byte_order
Byteorder.little = 'little'
>>> pointer.bytestream
''
>>> pointer.value
'0x0'
>>> bytes(pointer)
b'\x00\x00\x00\x00'
>>> int(pointer)
0
>>> float(pointer)
0.0
>>> hex(pointer)
'0x0'
>>> bin(pointer)
'0b0'
>>> oct(pointer)
'0o0'
>>> bool(pointer)
False
>>> pointer.as_signed()
0
>>> pointer.as_unsigned()
0
>>> pointer.deserialize(bytes.fromhex('00c0'))
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.value
'0xc000'
>>> pointer.value = 0x4000
>>> pointer.value
'0x4000'
>>> pointer.value = -0x1
>>> pointer.value
'0x0'
>>> pointer.value = 0x100000000
>>> pointer.value
'0xffffffff'
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> len(pointer)
0
>>> [name for name in pointer.keys()]
[]
>>> [member.value for member in pointer.values()]
[]
>>> [(name, member.value) for name, member in pointer.items()]
[]
>>> pointer.describe()  
{'address': 0,
 'alignment': [4, 0],
 'class': 'StructurePointer',
 'index': [0, 0],
 'max': 4294967295,
 'min': 0,
 'name': 'StructurePointer',
 'order': 'auto',
 'signed': False,
 'size': 32,
 'type': 'Pointer',
 'value': '0xffffffff',
 'member': [
    {'class': 'Structure',
     'name': 'data',
     'size': 0,
     'type': 'Structure',
     'member': []}
 ]}
>>> pointer.index_fields()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.view_fields()
{'value': '0xffffffff', 'data': {}}
>>> pointer.to_json()
'{"value": "0xffffffff", "data": {}}'
>>> pointer.field_items()
[('field',
  StructurePointer(index=Index(byte=0, bit=0,
                               address=0, base_address=0,
                               update=False),
                   alignment=Alignment(byte_size=4, bit_offset=0),
                   bit_size=32,
                   value='0xffffffff'))]
>>> pointer.to_list(nested=True)
[('StructurePointer.field', '0xffffffff')]
>>> pointer.to_dict(nested=True)
{'StructurePointer': {'field': '0xffffffff'}}

class konfoo.StructurePointer8(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little)

The StructurePointer8 field is a StructurePointer field with a Field size of one byte.

class konfoo.StructurePointer16(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StructurePointer16 field is a StructurePointer field with a Field size of two bytes.

class konfoo.StructurePointer24(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StructurePointer24 field is a StructurePointer field with a Field size of three bytes.

class konfoo.StructurePointer32(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StructurePointer32 field is a StructurePointer field with a Field size of four bytes.

class konfoo.StructurePointer48(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StructurePointer48 field is a StructurePointer field with a Field size of six bytes.

class konfoo.StructurePointer64(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StructurePointer64 field is a StructurePointer field with a Field size of eight bytes.

Sequence Pointer

class konfoo.SequencePointer(iterable: Iterable[Structure | Sequence | Field] | Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The SequencePointer field is a Pointer field which refers to a Sequence.

A SequencePointer field is:

• containable: item in self returns True if item is part of the referenced Sequence.

• sized: len(self) returns the number of items in the referenced Sequence.

• indexable self[index] returns the item at the index of the referenced Sequence.

• iterable iter(self) iterates over the items of the referenced Sequence

A SequencePointer field supports the usual methods for sequences:

• Append an item to the referenced Sequence via append().

• Insert an item before the index into the referenced Sequence via insert().

• Extend the referenced Sequence with items via extend().

• Clear the referenced Sequence via clear().

• Pop an item with the index from the referenced Sequence via pop().

• Remove the first occurrence of an item from the referenced Sequence via remove().

• Reverse all items in the referenced Sequence via reverse().

Parameters:

• iterable (Iterable[Structure|Sequence|Field]|Structure|Sequence|Field|None) – any iterable that contains items of Structure, Sequence, Array or Field instances. If the iterable is one of these instances itself then the iterable itself is appended to the Sequence.

• address (int|None) – absolute address of the data object referenced by the Pointer field.

• data_order (Byteorder|Literal['big', 'little']) – byte order used to unpack and pack the data object referenced by the Pointer field.

• bit_size (int) – is the size of the Pointer field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the Pointer field to the number of bytes, can be between 1 and 8. If no field alignment is set the Pointer field aligns itself to the next matching byte size according to the size of the Pointer field.

• field_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the Pointer field.

Example:

>>> pointer = SequencePointer()
>>> pointer.is_decimal()
True
>>> pointer.is_pointer()
True
>>> pointer.name
'Pointer32'
>>> pointer.alignment
Alignment(byte_size=4, bit_offset=0)
>>> pointer.byte_order
Byteorder.auto = 'auto'
>>> pointer.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> pointer.index_field()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.bit_size
32
>>> pointer.signed
False
>>> pointer.min()
0
>>> pointer.max()
4294967295
>>> pointer.base_address
0
>>> pointer.address
0
>>> pointer.is_null()
True
>>> pointer.data
[]
>>> pointer.data_size
0
>>> pointer.data_byte_order
Byteorder.little = 'little'
>>> pointer.bytestream
''
>>> pointer.value
'0x0'
>>> bytes(pointer).hex()
'00000000'
>>> bytes(pointer)
b'\x00\x00\x00\x00'
>>> int(pointer)
0
>>> float(pointer)
0.0
>>> hex(pointer)
'0x0'
>>> bin(pointer)
'0b0'
>>> oct(pointer)
'0o0'
>>> bool(pointer)
False
>>> pointer.as_signed()
0
>>> pointer.as_unsigned()
0
>>> pointer.deserialize(bytes.fromhex('00c0'))
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.value
'0xc000'
>>> pointer.value = 0x4000
>>> pointer.value
'0x4000'
>>> pointer.value = -0x1
>>> pointer.value
'0x0'
>>> pointer.value = 0x100000000
>>> pointer.value
'0xffffffff'
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> len(pointer)
0
>>> [item for item in pointer]
[]
>>> pointer[:]
[]
>>> pointer.append(Field())
>>> pointer[0]
Field(index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
      alignment=Alignment(byte_size=0, bit_offset=0),
      bit_size=0,
      value=None)
>>> len(pointer)
1
>>> pointer.pop()
Field(index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
      alignment=Alignment(byte_size=0, bit_offset=0),
      bit_size=0,
      value=None)
>>> pointer.insert(0, Field())
>>> pointer.data
[Field(index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
       alignment=Alignment(byte_size=0, bit_offset=0),
       bit_size=0,
       value=None)]
>>> pointer.remove(pointer[0])
>>> pointer.data
[]
>>> pointer.clear()
>>> pointer.describe()  
{'address': 0,
 'alignment': [4, 0],
 'class': 'SequencePointer',
 'index': [0, 0],
 'max': 4294967295,
 'min': 0,
 'name': 'SequencePointer',
 'order': 'auto',
 'signed': False,
 'size': 32,
 'type': 'Pointer',
 'value': '0xffffffff',
 'member': [
    {'class': 'Sequence',
     'name': 'data',
     'size': 0,
     'type': 'Sequence',
     'member': []}
 ]}
>>> pointer.index_fields()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.view_fields()
{'value': '0xffffffff', 'data': []}
>>> pointer.to_json()
'{"value": "0xffffffff", "data": []}'
>>> pointer.field_items()
[('field',
  SequencePointer(index=Index(byte=0, bit=0,
                              address=0, base_address=0,
                              update=False),
                  alignment=Alignment(byte_size=4, bit_offset=0),
                  bit_size=32,
                  value='0xffffffff'))]
>>> pointer.to_list(nested=True)
[('SequencePointer.field', '0xffffffff')]
>>> pointer.to_dict(nested=True)
{'SequencePointer': {'field': '0xffffffff'}}

append(item: Structure | Sequence | Field) → None

Appends the item to the end of the Sequence.

Parameters:

item (Structure|Sequence|Field) – any Structure, Sequence, Array or Field instance.

insert(index: int, item: Structure | Sequence | Field) → None

Inserts the item before the index into the Sequence.

Parameters:

• index (int) – Sequence index.

• item (Structure|Sequence|Field) – any Structure, Sequence, Array or Field instance.

pop(index: int = -1) → Structure | Sequence | Field

Removes and returns the item at the index from the Sequence.

Parameters:

index (int) – Sequence index.

clear() → None

Remove all items from the Sequence.

remove(item: Structure | Sequence | Field) → None

Removes the first occurrence of an item from the Sequence.

Parameters:

item (Structure|Sequence|Field) – any Structure, Sequence, Array or Field instance.

reverse() → None

In place reversing of the Sequence items.

extend(iterable: Iterable[Structure | Sequence | Field] | Structure | Sequence | Field) → None

Extends the Sequence by appending items from the iterable.

Parameters:

iterable (Iterable[Structure|Sequence|Field]|Structure|Sequence|Field) – any iterable that contains items of Structure, Sequence, Array or Field instances. If the iterable is one of these instances itself then the iterable itself is appended to the Sequence.

Array Pointer

class konfoo.ArrayPointer(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The ArrayPointer field is a SequencePointer field which refers to a Array.

An ArrayPointer field adapts and extends a SequencePointer field with the following features:

• Append a new Array element to the referenced Array via append().

• Insert a new Array element before the index

  into the referenced Array via insert().

• Re-size the referenced Array via resize().

Parameters:

• template (Callable|Structure|Sequence|Field) – template for the Array element. The template can be any Field instance or any callable that returns a Structure, Sequence, Array or any Field instance.

• capacity (int) – is the capacity of the Array in number of Array elements.

• address (int|None) – absolute address of the data object referenced by the Pointer field.

• data_order (Byteorder|Literal['big', 'little']) – byte order used to unpack and pack the data object referenced by the Pointer field.

• bit_size (int) – is the size of the Pointer field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the Pointer field to the number of bytes, can be between 1 and 8. If no field alignment is set the Pointer field aligns itself to the next matching byte size according to the size of the Pointer field.

• field_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the Pointer field.

Example:

>>> pointer = ArrayPointer(Byte)
>>> pointer.is_decimal()
True
>>> pointer.is_pointer()
True
>>> pointer.name
'Pointer32'
>>> pointer.alignment
Alignment(byte_size=4, bit_offset=0)
>>> pointer.byte_order
Byteorder.auto = 'auto'
>>> pointer.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> pointer.index_field()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.bit_size
32
>>> pointer.signed
False
>>> pointer.min()
0
>>> pointer.max()
4294967295
>>> pointer.base_address
0
>>> pointer.address
0
>>> pointer.is_null()
True
>>> pointer.data
[]
>>> pointer.data_size
0
>>> pointer.data_byte_order
Byteorder.little = 'little'
>>> pointer.bytestream
''
>>> pointer.value
'0x0'
>>> bytes(pointer)
b'\x00\x00\x00\x00'
>>> int(pointer)
0
>>> float(pointer)
0.0
>>> hex(pointer)
'0x0'
>>> bin(pointer)
'0b0'
>>> oct(pointer)
'0o0'
>>> bool(pointer)
False
>>> pointer.as_signed()
0
>>> pointer.as_unsigned()
0
>>> pointer.deserialize(bytes.fromhex('00c0'))
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.value
'0xc000'
>>> pointer.value = 0x4000
>>> pointer.value
'0x4000'
>>> pointer.value = -0x1
>>> pointer.value
'0x0'
>>> pointer.value = 0x100000000
>>> pointer.value
'0xffffffff'
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> len(pointer)
0
>>> [item for item in pointer]
[]
>>> pointer[:]
[]
>>> pointer.append()
>>> pointer[0]
Byte(index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
     alignment=Alignment(byte_size=1, bit_offset=0),
     bit_size=8,
     value='0x0')
>>> len(pointer)
1
>>> pointer.pop()
Byte(index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
     alignment=Alignment(byte_size=1, bit_offset=0),
     bit_size=8,
     value='0x0')
>>> pointer.insert(0)
>>> pointer.data
[Byte(index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
      alignment=Alignment(byte_size=1, bit_offset=0),
      bit_size=8,
      value='0x0')]
>>> pointer.remove(pointer[0])
>>> pointer.data
[]
>>> pointer.resize(10)
>>> len(pointer)
10
>>> pointer.clear()
>>> pointer.describe()  
{'address': 0,
 'alignment': [4, 0],
 'class': 'ArrayPointer',
 'index': [0, 0],
 'max': 4294967295,
 'min': 0,
 'name': 'ArrayPointer',
 'order': 'auto',
 'signed': False,
 'size': 32,
 'type': 'Pointer',
 'value': '0xffffffff',
 'member': [
    {'class': 'Array',
     'name': 'data',
     'size': 0,
     'type': 'Array',
     'member': []}
 ]}
>>> pointer.index_fields()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.view_fields()
{'value': '0xffffffff', 'data': []}
>>> pointer.to_json()
'{"value": "0xffffffff", "data": []}'
>>> pointer.field_items()
[('field',
  ArrayPointer(index=Index(byte=0, bit=0,
                           address=0, base_address=0,
                           update=False),
               alignment=Alignment(byte_size=4, bit_offset=0),
               bit_size=32,
               value='0xffffffff'))]
>>> pointer.to_list(nested=True)
[('ArrayPointer.field', '0xffffffff')]
>>> pointer.to_dict(nested=True)
{'ArrayPointer': {'field': '0xffffffff'}}

append() → None

Appends a new Array element to the Array.

insert(index: int) → None

Inserts a new Array element before the index of the Array.

Parameters:

index (int) – Array index.

resize(capacity: int) → None

Re-sizes the Array by appending new Array elements or removing Array elements from the end.

Parameters:

capacity (int) – new capacity of the Array in number of Array elements.

class konfoo.ArrayPointer8(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little)

The ArrayPointer8 field is an ArrayPointer field with a Field size of one byte.

class konfoo.ArrayPointer16(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The ArrayPointer16 field is an ArrayPointer field with a Field size of two bytes.

class konfoo.ArrayPointer24(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The ArrayPointer24 field is an ArrayPointer field with a Field size of three bytes.

class konfoo.ArrayPointer32(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The ArrayPointer32 field is an ArrayPointer field with a Field size of four bytes.

class konfoo.ArrayPointer48(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The ArrayPointer48 field is an ArrayPointer field with a Field size of six bytes.

class konfoo.ArrayPointer64(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The ArrayPointer64 field is an ArrayPointer field with a Field size of eight bytes.

Stream Pointer

class konfoo.StreamPointer(capacity: int = 0, address: int | None = None, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StreamPointer field is a Pointer field which refers to a Stream field.

A StreamPointer field is:

• containable: item in self returns True if item is part of the referenced Stream field.

• sized: len(self) returns the length of the referenced Stream field.

• indexable self[index] returns the byte at the index of the referenced Stream field.

• iterable iter(self) iterates over the bytes of the referenced Stream field.

Parameters:

• capacity (int) – is the capacity of the Stream field in bytes.

• address (int|None) – absolute address of the data object referenced by the Pointer field.

• bit_size (int) – is the size of the Pointer field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the Pointer field to the number of bytes, can be between 1 and 8. If no field alignment is set the Pointer field aligns itself to the next matching byte size according to the size of the Pointer field.

• field_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the Pointer field.

Example:

>>> pointer = StreamPointer()
>>> pointer.is_decimal()
True
>>> pointer.is_pointer()
True
>>> pointer.name
'Pointer32'
>>> pointer.alignment
Alignment(byte_size=4, bit_offset=0)
>>> pointer.byte_order
Byteorder.auto = 'auto'
>>> pointer.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> pointer.index_field()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.bit_size
32
>>> pointer.signed
False
>>> pointer.min()
0
>>> pointer.max()
4294967295
>>> pointer.base_address
0
>>> pointer.address
0
>>> pointer.is_null()
True
>>> pointer.data
Stream(index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
       alignment=Alignment(byte_size=0, bit_offset=0),
       bit_size=0,
       value='')
>>> pointer.data_size
0
>>> len(pointer)
0
>>> pointer.data_byte_order
Byteorder.little = 'little'
>>> pointer.bytestream
''
>>> pointer.value
'0x0'
>>> bytes(pointer)
b'\x00\x00\x00\x00'
>>> int(pointer)
0
>>> float(pointer)
0.0
>>> hex(pointer)
'0x0'
>>> bin(pointer)
'0b0'
>>> oct(pointer)
'0o0'
>>> bool(pointer)
False
>>> pointer.as_signed()
0
>>> pointer.as_unsigned()
0
>>> pointer.deserialize(bytes.fromhex('00c0'))
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.value
'0xc000'
>>> pointer.value = 0x4000
>>> pointer.value
'0x4000'
>>> pointer.value = -0x1
>>> pointer.value
'0x0'
>>> pointer.value = 0x100000000
>>> pointer.value
'0xffffffff'
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> pointer.serialize(bytestream)
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> bytestream.hex()
'ffffffff'
>>> pointer.resize(10)
>>> pointer.data_size
10
>>> len(pointer)
10
>>> pointer.bytestream = b'KonFoo is Fun'
>>> pointer.bytestream
'4b6f6e466f6f2069732046756e'
>>> pointer.serialize_data().hex()
'00000000000000000000'
>>> pointer.deserialize_data()
Index(byte=10, bit=0, address=4294967305, base_address=4294967295, update=False)
>>> pointer.serialize_data()
b'KonFoo is '
>>> [byte for byte in pointer]  # converts to int
[75, 111, 110, 70, 111, 111, 32, 105, 115, 32]
>>> [hex(byte) for byte in pointer]
['0x4b', '0x6f', '0x6e', '0x46', '0x6f', '0x6f', '0x20', '0x69', '0x73', '0x20']
>>> pointer[5]  # converts to int
111
>>> 111 in pointer
True
>>> 0x0 in pointer
False
>>> b'KonFoo' in pointer
True
>>> pointer[:6]  # converts to bytes
b'KonFoo'
>>> pointer[3:6]  # converts to bytes
b'Foo'
>>> pointer.describe()  
{'address': 0,
 'alignment': [4, 0],
 'class': 'StreamPointer',
 'index': [0, 0],
 'max': 4294967295,
 'min': 0,
 'name': 'StreamPointer',
 'order': 'auto',
 'signed': False,
 'size': 32,
 'type': 'Pointer',
 'value': '0xffffffff',
 'member': [
    {'address': 4294967295,
     'alignment': [10, 0],
     'class': 'Stream10',
     'index': [0, 0],
     'name': 'data',
     'order': 'auto',
     'size': 80,
     'type': 'Field',
     'value': '4b6f6e466f6f20697320'}
 ]}
>>> pointer.index_fields()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.view_fields()
{'value': '0xffffffff', 'data': '4b6f6e466f6f20697320'}
>>> pointer.to_json()
'{"value": "0xffffffff", "data": "4b6f6e466f6f20697320"}'
>>> pointer.field_items()
[('field',
  StreamPointer(index=Index(byte=0, bit=0,
                            address=0, base_address=0,
                            update=False),
                alignment=Alignment(byte_size=4, bit_offset=0),
                bit_size=32,
                value='0xffffffff')),
 ('data',
  Stream(index=Index(byte=0, bit=0,
                     address=4294967295, base_address=4294967295,
                     update=False),
         alignment=Alignment(byte_size=10, bit_offset=0),
         bit_size=80,
         value='4b6f6e466f6f20697320'))]
>>> pointer.to_list()
[('StreamPointer.field', '0xffffffff'),
 ('StreamPointer.data', '4b6f6e466f6f20697320')]
>>> pointer.to_dict()
{'StreamPointer': {'field': '0xffffffff', 'data': '4b6f6e466f6f20697320'}}

resize(capacity: int) → None

Re-sizes the Stream field by appending zero bytes or removing bytes from the end.

Parameters:

capacity (int) – Stream capacity in number of bytes.

class konfoo.StreamPointer8(capacity: int = 0, address: int | None = None)

The StreamPointer8 field is a StreamPointer field with a Field size of one byte.

class konfoo.StreamPointer16(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StreamPointer16 field is a StreamPointer field with a Field size of two bytes.

class konfoo.StreamPointer24(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StreamPointer24 field is a StreamPointer field with a Field size of three bytes.

class konfoo.StreamPointer32(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StreamPointer32 field is a StreamPointer field with a Field size of four bytes.

class konfoo.StreamPointer48(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StreamPointer48 field is a StreamPointer field with a Field size of six bytes.

class konfoo.StreamPointer64(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StreamPointer64 field is a StreamPointer field with a Field size of eight bytes.

String Pointer

class konfoo.StringPointer(capacity: int = 0, address: int | None = None, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StringPointer field is a StreamPointer field which refers to a String field.

Parameters:

• capacity (int) – is the capacity of the String field in bytes.

• address (int|None) – absolute address of the data object referenced by the Pointer field.

• bit_size (int) – is the size of the Pointer field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the Pointer field to the number of bytes, can be between 1 and 8. If no field alignment is set the Pointer field aligns itself to the next matching byte size according to the size of the Pointer field.

• field_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the Pointer field.

Example:

>>> pointer = StringPointer()
>>> pointer.is_decimal()
True
>>> pointer.is_pointer()
True
>>> pointer.name
'Pointer32'
>>> pointer.alignment
Alignment(byte_size=4, bit_offset=0)
>>> pointer.byte_order
Byteorder.auto = 'auto'
>>> pointer.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> pointer.index_field()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.bit_size
32
>>> pointer.signed
False
>>> pointer.min()
0
>>> pointer.max()
4294967295
>>> pointer.base_address
0
>>> pointer.address
0
>>> pointer.is_null()
True
>>> pointer.data
String(index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
       alignment=Alignment(byte_size=0, bit_offset=0),
       bit_size=0,
       value='')
>>> pointer.data_size
0
>>> len(pointer)
0
>>> pointer.data_byte_order
Byteorder.little = 'little'
>>> pointer.bytestream
''
>>> pointer.value
'0x0'
>>> bytes(pointer)
b'\x00\x00\x00\x00'
>>> int(pointer)
0
>>> float(pointer)
0.0
>>> hex(pointer)
'0x0'
>>> bin(pointer)
'0b0'
>>> oct(pointer)
'0o0'
>>> bool(pointer)
False
>>> pointer.as_signed()
0
>>> pointer.as_unsigned()
0
>>> pointer.deserialize(bytes.fromhex('00c0'))
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.value
'0xc000'
>>> pointer.value = 0x4000
>>> pointer.value
'0x4000'
>>> pointer.value = -0x1
>>> pointer.value
'0x0'
>>> pointer.value = 0x100000000
>>> pointer.value
'0xffffffff'
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> pointer.serialize(bytestream)
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> bytestream.hex()
'ffffffff'
>>> pointer.resize(10)
>>> pointer.data_size
10
>>> len(pointer)
10
>>> pointer.bytestream = b'KonFoo is Fun'
>>> pointer.bytestream
'4b6f6e466f6f2069732046756e'
>>> pointer.serialize_data().hex()
'00000000000000000000'
>>> pointer.deserialize_data()
Index(byte=10, bit=0, address=4294967305, base_address=4294967295, update=False)
>>> pointer.serialize_data()
b'KonFoo is '
>>> [byte for byte in pointer]  # converts to int
[75, 111, 110, 70, 111, 111, 32, 105, 115, 32]
>>> [chr(byte) for byte in pointer]  # converts to int
['K', 'o', 'n', 'F', 'o', 'o', ' ', 'i', 's', ' ']
>>> chr(pointer[5])  # converts to int -> chr
'o'
>>> ord(' ') in pointer
True
>>> 0x0 in pointer
False
>>> pointer[:6]  # converts to bytes
b'KonFoo'
>>> pointer[3:6]  # converts to bytes
b'Foo'
>>> pointer.describe()  
{'address': 0,
 'alignment': [4, 0],
 'class': 'StringPointer',
 'index': [0, 0],
 'max': 4294967295,
 'min': 0,
 'name': 'StringPointer',
 'order': 'auto',
 'signed': False,
 'size': 32,
 'type': 'Pointer',
 'value': '0xffffffff',
 'member': [
    {'address': 4294967295,
     'alignment': [10, 0],
     'class': 'String10',
     'index': [0, 0],
     'name': 'data',
     'order': 'auto',
     'size': 80,
     'type': 'Field',
     'value': 'KonFoo is '}
 ]}
>>> pointer.index_fields()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.view_fields()
{'value': '0xffffffff', 'data': 'KonFoo is '}
>>> pointer.to_json()
'{"value": "0xffffffff", "data": "KonFoo is "}'
>>> pointer.field_items()
[('field',
  StringPointer(index=Index(byte=0, bit=0,
                            address=0, base_address=0,
                            update=False),
                alignment=Alignment(byte_size=4, bit_offset=0),
                bit_size=32,
                value='0xffffffff')),
 ('data',
  String(index=Index(byte=0, bit=0,
                     address=4294967295, base_address=4294967295,
                     update=False),
         alignment=Alignment(byte_size=10, bit_offset=0),
         bit_size=80,
         value='KonFoo is '))]
>>> pointer.to_list()
[('StringPointer.field', '0xffffffff'),
 ('StringPointer.data', 'KonFoo is ')]
>>> pointer.to_dict()
{'StringPointer': {'field': '0xffffffff', 'data': 'KonFoo is '}}

class konfoo.StringPointer8(capacity: int = 0, address: int | None = None)

The StringPointer8 field is a StringPointer field with a Field size of one byte.

class konfoo.StringPointer16(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StringPointer16 field is a StringPointer field with a Field size of two bytes.

class konfoo.StringPointer24(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StringPointer24 field is a StringPointer field with a Field size of three bytes.

class konfoo.StringPointer32(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StringPointer32 field is a StringPointer field with a Field size of four bytes.

class konfoo.StringPointer48(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StringPointer48 field is a StringPointer field with a Field size of six bytes.

class konfoo.StringPointer64(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StringPointer64 field is a StringPointer field with a Field size of eight bytes.

Auto String Pointer

class konfoo.AutoStringPointer(address: int | None = None, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The AutoStringPointer field is a StringPointer field which refers to an auto-sized String field.

Parameters:

• address (int|None) – absolute address of the data object referenced by the Pointer field.

• bit_size (int) – is the size of the Pointer field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the Pointer field to the number of bytes, can be between 1 and 8. If no field alignment is set the Pointer field aligns itself to the next matching byte size according to the size of the Pointer field.

• field_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the Pointer field.

Example:

>>> pointer = AutoStringPointer()
>>> pointer.is_decimal()
True
>>> pointer.is_pointer()
True
>>> pointer.name
'Pointer32'
>>> pointer.alignment
Alignment(byte_size=4, bit_offset=0)
>>> pointer.byte_order
Byteorder.auto = 'auto'
>>> pointer.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> pointer.index_field()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.bit_size
32
>>> pointer.signed
False
>>> pointer.min()
0
>>> pointer.max()
4294967295
>>> pointer.base_address
0
>>> pointer.address
0
>>> pointer.is_null()
True
>>> pointer.data
String(index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
       alignment=Alignment(byte_size=64, bit_offset=0),
       bit_size=512,
       value='')
>>> pointer.data_size
64
>>> len(pointer)
64
>>> pointer.data_byte_order
Byteorder.little = 'little'
>>> pointer.bytestream
''
>>> pointer.value
'0x0'
>>> bytes(pointer)
b'\x00\x00\x00\x00'
>>> int(pointer)
0
>>> float(pointer)
0.0
>>> hex(pointer)
'0x0'
>>> bin(pointer)
'0b0'
>>> oct(pointer)
'0o0'
>>> bool(pointer)
False
>>> pointer.as_signed()
0
>>> pointer.as_unsigned()
0
>>> pointer.deserialize(bytes.fromhex('00c0'))
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.value
'0xc000'
>>> pointer.value = 0x4000
>>> pointer.value
'0x4000'
>>> pointer.value = -0x1
>>> pointer.value
'0x0'
>>> pointer.value = 0x100000000
>>> pointer.value
'0xffffffff'
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> pointer.serialize(bytestream)
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> bytestream.hex()
'ffffffff'
>>> pointer.resize(10)
>>> pointer.data_size
10
>>> len(pointer)
10
>>> pointer.bytestream = b'KonFoo is Fun'
>>> pointer.bytestream
'4b6f6e466f6f2069732046756e'
>>> pointer.serialize_data().hex()
'00000000000000000000'
>>> pointer.deserialize_data()
Index(byte=10, bit=0, address=4294967305, base_address=4294967295, update=False)
>>> pointer.serialize_data()
b'KonFoo is '
>>> [byte for byte in pointer]  # converts to int
[75, 111, 110, 70, 111, 111, 32, 105, 115, 32]
>>> [chr(byte) for byte in pointer]  # converts to int
['K', 'o', 'n', 'F', 'o', 'o', ' ', 'i', 's', ' ']
>>> chr(pointer[5])  # converts to int -> chr
'o'
>>> ord(' ') in pointer
True
>>> 0x0 in pointer
False
>>> pointer[:6]  # converts to bytes
b'KonFoo'
>>> pointer[3:6]  # converts to bytes
b'Foo'
>>> pointer.describe()  
{'address': 0,
 'alignment': [4, 0],
 'class': 'AutoStringPointer',
 'index': [0, 0],
 'max': 4294967295,
 'min': 0,
 'name': 'AutoStringPointer',
 'order': 'auto',
 'signed': False,
 'size': 32,
 'type': 'Pointer',
 'value': '0xffffffff',
 'member': [
    {'address': 4294967295,
     'alignment': [10, 0],
     'class': 'String10',
     'index': [0, 0],
     'name': 'data',
     'order': 'auto',
     'size': 80,
     'type': 'Field',
     'value': 'KonFoo is '}
 ]}
>>> pointer.index_fields()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.view_fields()
{'value': '0xffffffff', 'data': 'KonFoo is '}
>>> pointer.to_json()
'{"value": "0xffffffff", "data": "KonFoo is "}'
>>> pointer.field_items()
[('field',
  AutoStringPointer(index=Index(byte=0, bit=0,
                            address=0, base_address=0,
                            update=False),
                    alignment=Alignment(byte_size=4, bit_offset=0),
                    bit_size=32,
                    value='0xffffffff')),
 ('data',
  String(index=Index(byte=0, bit=0,
                     address=4294967295, base_address=4294967295,
                     update=False),
         alignment=Alignment(byte_size=10, bit_offset=0),
         bit_size=80,
         value='KonFoo is '))]
>>> pointer.to_list()
[('AutoStringPointer.field', '0xffffffff'),
 ('AutoStringPointer.data', 'KonFoo is ')]
>>> pointer.to_dict()
{'AutoStringPointer': {'field': '0xffffffff', 'data': 'KonFoo is '}}

BLOCK_SIZE = 64

Block size in bytes to read for the String field.

MAX_ADDRESS = 4294967295

Maximal allowed address of the String field.

Relative Pointer

class konfoo.RelativePointer(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The RelativePointer field is a Pointer field which references its data object relative to a base address in the data source.

Important

The base_address of a RelativePointer is defined by the field index of the RelativePointer field.

Parameters:

• template (Structure|Sequence|Field|None) – template for the data object referenced by the RelativePointer field.

• address (int|None) – relative address of the data object referenced by the RelativePointer field.

• data_order (Byteorder|Literal['big', 'little']) – byte order used to unpack and pack the data object referenced by the RelativePointer field.

• bit_size (int) – is the size of the RelativePointer field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the RelativePointer field to the number of bytes, can be between 1 and 8. If no field alignment is set the RelativePointer field aligns itself to the next matching byte size according to the size of the RelativePointer field.

• field_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the RelativePointer field.

Example:

>>> pointer = RelativePointer()
>>> pointer.is_decimal()
True
>>> pointer.is_pointer()
True
>>> pointer.name
'Pointer32'
>>> pointer.alignment
Alignment(byte_size=4, bit_offset=0)
>>> pointer.byte_order
Byteorder.auto = 'auto'
>>> pointer.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> pointer.index_field()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.bit_size
32
>>> pointer.signed
False
>>> pointer.min()
0
>>> pointer.max()
4294967295
>>> pointer.base_address
0
>>> pointer.address
0
>>> pointer.is_null()
True
>>> pointer.data
>>> pointer.data_size
0
>>> pointer.data_byte_order
Byteorder.little = 'little'
>>> pointer.bytestream
''
>>> pointer.value
'0x0'
>>> bytes(pointer)
b'\x00\x00\x00\x00'
>>> int(pointer)
0
>>> float(pointer)
0.0
>>> hex(pointer)
'0x0'
>>> bin(pointer)
'0b0'
>>> oct(pointer)
'0o0'
>>> bool(pointer)
False
>>> pointer.as_signed()
0
>>> pointer.as_unsigned()
0
>>> pointer.deserialize(bytes.fromhex('00c0'))
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.value
'0xc000'
>>> pointer.value = 0x4000
>>> pointer.value
'0x4000'
>>> pointer.value = -0x1
>>> pointer.value
'0x0'
>>> pointer.value = 0x100000000
>>> pointer.value
'0xffffffff'
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> pointer.serialize(bytestream)
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> bytestream.hex()
'ffffffff'
>>> pointer.bytestream = b'KonFoo is Fun'
>>> pointer.bytestream
'4b6f6e466f6f2069732046756e'
>>> pointer.serialize_data()
b''
>>> pointer.deserialize_data()
Index(byte=0, bit=0, address=4294967295, base_address=0, update=False)
>>> pointer.serialize_data()
b''
>>> pointer.describe()
{'address': 0,
 'alignment': [4, 0],
 'class': 'RelativePointer',
 'index': [0, 0],
 'max': 4294967295,
 'min': 0,
 'name': 'RelativePointer',
 'order': 'auto',
 'signed': False,
 'size': 32,
 'type': 'Pointer',
 'value': '0xffffffff'}
>>> pointer.index_fields()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.view_fields()
{'value': '0xffffffff', 'data': None}
>>> pointer.to_json()
'{"value": "0xffffffff", "data": null}'
>>> pointer.field_items()
[('field',
  RelativePointer(index=Index(byte=0, bit=0,
                              address=0, base_address=0,
                              update=False),
                  alignment=Alignment(byte_size=4, bit_offset=0),
                  bit_size=32,
                  value='0xffffffff'))]
>>> pointer.to_list()
[('RelativePointer.field', '0xffffffff')]
>>> pointer.to_dict()
{'RelativePointer': {'field': '0xffffffff'}}

property address: int

Returns the data source address of the data object referenced by the RelativePointer field (read-only).

property base_address: int

Returns the data source base address of the data object relative referenced by the RelativePointer field (read-only).

class konfoo.RelativePointer8(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little)

The RelativePointer8 field is a RelativePointer field with a Field size of one byte.

class konfoo.RelativePointer16(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The RelativePointer16 field is a RelativePointer field with a Field size of two bytes.

class konfoo.RelativePointer24(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The RelativePointer24 field is a RelativePointer field with a Field size of three bytes.

class konfoo.RelativePointer32(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The RelativePointer32 field is a RelativePointer field with a Field size of four bytes.

class konfoo.RelativePointer48(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The RelativePointer48 field is a RelativePointer field with a Field size of six bytes.

class konfoo.RelativePointer64(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The RelativePointer64 field is a RelativePointer field with a Field size of eight bytes.

Structure Relative Pointer

class konfoo.StructureRelativePointer(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StructureRelativePointer field is a RelativePointer which refers to a Structure.

Parameters:

• template (Structure|None) – template for the data object referenced by the RelativePointer field. The template must be a Structure instance.

• address (int|None) – relative address of the data object referenced by the RelativePointer field.

• data_order (Byteorder|Literal['big', 'little']) – byte order used to unpack and pack the data object referenced by the RelativePointer field.

• bit_size (int) – is the size of the RelativePointer field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the RelativePointer field to the number of bytes, can be between 1 and 8. If no field alignment is set the RelativePointer field aligns itself to the next matching byte size according to the size of the RelativePointer field.

• field_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the RelativePointer field.

Example:

>>> pointer = StructureRelativePointer()
>>> pointer.is_decimal()
True
>>> pointer.is_pointer()
True
>>> pointer.name
'Pointer32'
>>> pointer.alignment
Alignment(byte_size=4, bit_offset=0)
>>> pointer.byte_order
Byteorder.auto = 'auto'
>>> pointer.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> pointer.index_field()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.bit_size
32
>>> pointer.signed
False
>>> pointer.min()
0
>>> pointer.max()
4294967295
>>> pointer.base_address
0
>>> pointer.address
0
>>> pointer.is_null()
True
>>> pointer.data
{}
>>> pointer.data_size
0
>>> pointer.data_byte_order
Byteorder.little = 'little'
>>> pointer.bytestream
''
>>> pointer.value
'0x0'
>>> bytes(pointer)
b'\x00\x00\x00\x00'
>>> int(pointer)
0
>>> float(pointer)
0.0
>>> hex(pointer)
'0x0'
>>> bin(pointer)
'0b0'
>>> oct(pointer)
'0o0'
>>> bool(pointer)
False
>>> pointer.as_signed()
0
>>> pointer.as_unsigned()
0
>>> pointer.deserialize(bytes.fromhex('00c0'))
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.value
'0xc000'
>>> pointer.value = 0x4000
>>> pointer.value
'0x4000'
>>> pointer.value = -0x1
>>> pointer.value
'0x0'
>>> pointer.value = 0x100000000
>>> pointer.value
'0xffffffff'
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> len(pointer)
0
>>> [name for name in pointer.keys()]
[]
>>> [member.value for member in pointer.values()]
[]
>>> [(name, member.value) for name, member in pointer.items()]
[]
>>> pointer.describe()  
{'address': 0,
 'alignment': [4, 0],
 'class': 'StructureRelativePointer',
 'index': [0, 0],
 'max': 4294967295,
 'min': 0,
 'name': 'StructureRelativePointer',
 'order': 'auto',
 'signed': False,
 'size': 32,
 'type': 'Pointer',
 'value': '0xffffffff',
 'member': [
    {'class': 'Structure',
     'name': 'data',
     'size': 0,
     'type': 'Structure',
     'member': []}
 ]}
>>> pointer.index_fields()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.view_fields()
{'value': '0xffffffff', 'data': {}}
>>> pointer.to_json()
'{"value": "0xffffffff", "data": {}}'
>>> pointer.field_items()
[('field',
  StructureRelativePointer(index=Index(byte=0, bit=0,
                                       address=0, base_address=0,
                                       update=False),
                           alignment=Alignment(byte_size=4, bit_offset=0),
                           bit_size=32,
                           value='0xffffffff'))]
>>> pointer.to_list(nested=True)
[('StructureRelativePointer.field', '0xffffffff')]
>>> pointer.to_dict(nested=True)
{'StructureRelativePointer': {'field': '0xffffffff'}}

class konfoo.StructureRelativePointer8(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little)

The StructureRelativePointer8 field is a StructureRelativePointer field with a Field size of one byte.

class konfoo.StructureRelativePointer16(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StructureRelativePointer16 field is a StructureRelativePointer field with a Field size of two bytes.

class konfoo.StructureRelativePointer24(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StructureRelativePointer24 field is a StructureRelativePointer field with a Field size of three bytes.

Members:

class konfoo.StructureRelativePointer32(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StructureRelativePointer32 field is a StructureRelativePointer field with a Field size of four bytes.

class konfoo.StructureRelativePointer48(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StructureRelativePointer48 field is a StructureRelativePointer field with a Field size of six bytes.

class konfoo.StructureRelativePointer64(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StructureRelativePointer64 field is a StructureRelativePointer field with a Field size of eight bytes.

Sequence Relative Pointer

class konfoo.SequenceRelativePointer(iterable: Iterable[Structure | Sequence | Field] | Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The SequenceRelativePointer field is a RelativePointer which refers to a Sequence.

A SequenceRelativePointer is:

• containable: item in self returns True if item is part of the referenced Sequence.

• sized: len(self) returns the number of items in the referenced Sequence.

• indexable self[index] returns the item at the index of the referenced Sequence.

• iterable iter(self) iterates over the items of the referenced Sequence

A SequenceRelativePointer supports the usual methods:

• Append an item to the referenced Sequence via append().

• Insert an item before the index into the referenced Sequence via insert().

• Extend the referenced Sequence with items via extend().

• Clear the referenced Sequence via clear().

• Pop an item with the index from the referenced Sequence via pop().

• Remove the first occurrence of an item from the referenced Sequence via remove().

• Reverse all items in the referenced Sequence via reverse().

Parameters:

• iterable (Iterable[Structure|Sequence|Field]|Structure|Sequence|Field) – any iterable that contains items of Structure, Sequence, Array or Field instances. If the iterable is one of these instances itself then the iterable itself is appended to the Sequence.

• address (int|None) – relative address of the data object referenced by the RelativePointer field.

• data_order (Byteorder|Literal['big', 'little']) – byte order used to unpack and pack the data object referenced by the RelativePointer field.

• bit_size (int) – is the size of the RelativePointer field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the RelativePointer field to the number of bytes, can be between 1 and 8. If no field alignment is set the RelativePointer field aligns itself to the next matching byte size according to the size of the RelativePointer field.

• field_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the RelativePointer field.

Example:

>>> pointer = SequenceRelativePointer()
>>> pointer.is_decimal()
True
>>> pointer.is_pointer()
True
>>> pointer.name
'Pointer32'
>>> pointer.alignment
Alignment(byte_size=4, bit_offset=0)
>>> pointer.byte_order
Byteorder.auto = 'auto'
>>> pointer.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> pointer.index_field()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.bit_size
32
>>> pointer.signed
False
>>> pointer.min()
0
>>> pointer.max()
4294967295
>>> pointer.base_address
0
>>> pointer.address
0
>>> pointer.is_null()
True
>>> pointer.data
[]
>>> pointer.data_size
0
>>> pointer.data_byte_order
Byteorder.little = 'little'
>>> pointer.bytestream
''
>>> pointer.value
'0x0'
>>> bytes(pointer)
b'\x00\x00\x00\x00'
>>> int(pointer)
0
>>> float(pointer)
0.0
>>> hex(pointer)
'0x0'
>>> bin(pointer)
'0b0'
>>> oct(pointer)
'0o0'
>>> bool(pointer)
False
>>> pointer.as_signed()
0
>>> pointer.as_unsigned()
0
>>> pointer.deserialize(bytes.fromhex('00c0'))
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.value
'0xc000'
>>> pointer.value = 0x4000
>>> pointer.value
'0x4000'
>>> pointer.value = -0x1
>>> pointer.value
'0x0'
>>> pointer.value = 0x100000000
>>> pointer.value
'0xffffffff'
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> len(pointer)
0
>>> [item for item in pointer]
[]
>>> pointer[:]
[]
>>> pointer.append(Field())
>>> pointer[0]
Field(index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
      alignment=Alignment(byte_size=0, bit_offset=0),
      bit_size=0,
      value=None)
>>> len(pointer)
1
>>> pointer.pop()
Field(index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
      alignment=Alignment(byte_size=0, bit_offset=0),
      bit_size=0,
      value=None)
>>> pointer.insert(0, Field())
>>> pointer.data
[Field(index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
       alignment=Alignment(byte_size=0, bit_offset=0),
       bit_size=0,
       value=None)]
>>> pointer.remove(pointer[0])
>>> pointer.data
[]
>>> pointer.clear()
>>> pointer.describe()  
{'address': 0,
 'alignment': [4, 0],
 'class': 'SequenceRelativePointer',
 'index': [0, 0],
 'max': 4294967295,
 'min': 0,
 'name': 'SequenceRelativePointer',
 'order': 'auto',
 'signed': False,
 'size': 32,
 'type': 'Pointer',
 'value': '0xffffffff',
 'member': [
    {'class': 'Sequence',
     'name': 'data',
     'size': 0,
     'type': 'Sequence',
     'member': []}
 ]}
>>> pointer.index_fields()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.view_fields()
{'value': '0xffffffff', 'data': []}
>>> pointer.to_json()
'{"value": "0xffffffff", "data": []}'
>>> pointer.field_items()
[('field',
  SequenceRelativePointer(index=Index(byte=0, bit=0,
                                      address=0, base_address=0,
                                      update=False),
                          alignment=Alignment(byte_size=4, bit_offset=0),
                          bit_size=32,
                          value='0xffffffff'))]
>>> pointer.to_list(nested=True)
[('SequenceRelativePointer.field', '0xffffffff')]
>>> pointer.to_dict(nested=True)
{'SequenceRelativePointer': {'field': '0xffffffff'}}

append(item: Structure | Sequence | Field) → None

Appends the item to the end of the Sequence.

Parameters:

item (Structure|Sequence|Field) – any Structure, Sequence, Array or Field instance.

insert(index: int, item: Structure | Sequence | Field) → None

Inserts the item before the index into the Sequence.

Parameters:

• index (int) – Sequence index.

• item (Structure|Sequence|Field) – any Structure, Sequence, Array or Field instance.

pop(index: int = -1) → Structure | Sequence | Field

Removes and returns the item at the index from the Sequence.

Parameters:

index (int) – Sequence index.

clear() → None

Remove all items from the Sequence.

remove(item: Structure | Sequence | Field) → None

Removes the first occurrence of an item from the Sequence.

Parameters:

item (Structure|Sequence|Field) – any Structure, Sequence, Array or Field instance.

reverse() → None

In place reversing of the Sequence items.

extend(iterable: Iterable[Structure | Sequence | Field] | Structure | Sequence | Field) → None

Extends the Sequence by appending items from the iterable.

Parameters:

iterable (Iterable[Structure|Sequence|Field]|Structure|Sequence|Field) – any iterable that contains items of Structure, Sequence, Array or Field instances. If the iterable is one of these instances itself then the iterable itself is appended to the Sequence.

Array Relative Pointer

class konfoo.ArrayRelativePointer(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The ArrayRelativePointer field is a SequenceRelativePointer which refers to a Array.

An ArrayRelativePointer adapts and extends a SequenceRelativePointer with the following features:

• Append a new Array element to the Array via append().

• Insert a new Array element before the index into the Array via insert().

• Re-size the Array via resize().

Parameters:

• template – template for the Array element. The template can be any Field instance or any callable that returns a Structure, Sequence, Array or any Field instance.

• capacity (int) – is the capacity of the Array in number of Array elements.

• address (int|None) – relative address of the data object referenced by the RelativePointer field.

• data_order (Byteorder|Literal['big', 'little']) – byte order used to unpack and pack the data object referenced by the RelativePointer field.

• bit_size (int) – is the size of the RelativePointer field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the RelativePointer field to the number of bytes, can be between 1 and 8. If no field alignment is set the RelativePointer field aligns itself to the next matching byte size according to the size of the RelativePointer field.

• field_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the RelativePointer field.

Example:

>>> pointer = ArrayRelativePointer(Byte)
>>> pointer.is_decimal()
True
>>> pointer.is_pointer()
True
>>> pointer.name
'Pointer32'
>>> pointer.alignment
Alignment(byte_size=4, bit_offset=0)
>>> pointer.byte_order
Byteorder.auto = 'auto'
>>> pointer.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> pointer.index_field()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.bit_size
32
>>> pointer.signed
False
>>> pointer.min()
0
>>> pointer.max()
4294967295
>>> pointer.base_address
0
>>> pointer.address
0
>>> pointer.is_null()
True
>>> pointer.data
[]
>>> pointer.data_size
0
>>> pointer.data_byte_order
Byteorder.little = 'little'
>>> pointer.bytestream
''
>>> pointer.value
'0x0'
>>> bytes(pointer)
b'\x00\x00\x00\x00'
>>> int(pointer)
0
>>> float(pointer)
0.0
>>> hex(pointer)
'0x0'
>>> bin(pointer)
'0b0'
>>> oct(pointer)
'0o0'
>>> bool(pointer)
False
>>> pointer.as_signed()
0
>>> pointer.as_unsigned()
0
>>> pointer.deserialize(bytes.fromhex('00c0'))
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.value
'0xc000'
>>> pointer.value = 0x4000
>>> pointer.value
'0x4000'
>>> pointer.value = -0x1
>>> pointer.value
'0x0'
>>> pointer.value = 0x100000000
>>> pointer.value
'0xffffffff'
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> len(pointer)
0
>>> [item for item in pointer]
[]
>>> pointer[:]
[]
>>> pointer.append()
>>> pointer[0]
Byte(index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
     alignment=Alignment(byte_size=1, bit_offset=0),
     bit_size=8,
     value='0x0')
>>> len(pointer)
1
>>> pointer.pop()
Byte(index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
     alignment=Alignment(byte_size=1, bit_offset=0),
     bit_size=8,
     value='0x0')
>>> pointer.insert(0)
>>> pointer.data
[Byte(index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
      alignment=Alignment(byte_size=1, bit_offset=0),
      bit_size=8,
      value='0x0')]
>>> pointer.remove(pointer[0])
>>> pointer.data
[]
>>> pointer.resize(10)
>>> len(pointer)
10
>>> pointer.clear()
>>> pointer.describe()  
{'address': 0,
 'alignment': [4, 0],
 'class': 'ArrayRelativePointer',
 'index': [0, 0],
 'max': 4294967295,
 'min': 0,
 'name': 'ArrayRelativePointer',
 'order': 'auto',
 'signed': False,
 'size': 32,
 'type': 'Pointer',
 'value': '0xffffffff',
 'member': [
    {'class': 'Array',
     'name': 'data',
     'size': 0,
     'type': 'Array',
     'member': []}
 ]}
>>> pointer.index_fields()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.view_fields()
{'value': '0xffffffff', 'data': []}
>>> pointer.to_json()
'{"value": "0xffffffff", "data": []}'
>>> pointer.field_items()
[('field',
  ArrayRelativePointer(index=Index(byte=0, bit=0,
                                   address=0, base_address=0,
                                   update=False),
                       alignment=Alignment(byte_size=4, bit_offset=0),
                       bit_size=32,
                       value='0xffffffff'))]
>>> pointer.to_list(nested=True)
[('ArrayRelativePointer.field', '0xffffffff')]
>>> pointer.to_dict(nested=True)
{'ArrayRelativePointer': {'field': '0xffffffff'}}

append() → None

Appends a new Array element to the Array.

insert(index: int) → None

Inserts a new Array element before the index of the Array.

Parameters:

index (int) – Array index.

resize(capacity: int) → None

Re-sizes the Array by appending new Array elements or removing Array elements from the end.

Parameters:

capacity (int) – new capacity of the Array in number of Array elements.

class konfoo.ArrayRelativePointer8(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little)

The ArrayRelativePointer8 field is an ArrayRelativePointer field with a Field size of one byte.

class konfoo.ArrayRelativePointer16(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The ArrayRelativePointer16 field is an ArrayRelativePointer field with a Field size of two bytes.

class konfoo.ArrayRelativePointer24(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The ArrayRelativePointer24 field is an ArrayRelativePointer field with a Field size of three bytes.

class konfoo.ArrayRelativePointer32(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The ArrayRelativePointer32 field is an ArrayRelativePointer field with a Field size of four bytes.

class konfoo.ArrayRelativePointer48(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The ArrayRelativePointer48 field is an ArrayRelativePointer field with a Field size of six bytes.

class konfoo.ArrayRelativePointer64(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The ArrayRelativePointer64 field is an ArrayRelativePointer field with a Field size of eight bytes.

Stream Relative Pointer

class konfoo.StreamRelativePointer(capacity: int = 0, address: int | None = None, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StreamRelativePointer field is a RelativePointer field which refers to a Stream field.

A StreamRelativePointer field is:

• containable: item in self returns True if item is part of the referenced Stream field.

• sized: len(self) returns the length of the referenced Stream field.

• indexable self[index] returns the byte at the index of the referenced Stream field.

• iterable iter(self) iterates over the bytes of the referenced Stream field.

Parameters:

• capacity (int) – is the capacity of the Stream field in bytes.

• address (int|None) – relative address of the data object referenced by the RelativePointer field.

• bit_size (int) – is the size of the RelativePointer field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the RelativePointer field to the number of bytes, can be between 1 and 8. If no field alignment is set the RelativePointer field aligns itself to the next matching byte size according to the size of the RelativePointer field.

• field_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the RelativePointer field.

Example:

>>> pointer = StreamRelativePointer()
>>> pointer.is_decimal()
True
>>> pointer.is_pointer()
True
>>> pointer.name
'Pointer32'
>>> pointer.alignment
Alignment(byte_size=4, bit_offset=0)
>>> pointer.byte_order
Byteorder.auto = 'auto'
>>> pointer.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> pointer.index_field()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.bit_size
32
>>> pointer.signed
False
>>> pointer.min()
0
>>> pointer.max()
4294967295
>>> pointer.base_address
0
>>> pointer.address
0
>>> pointer.is_null()
True
>>> pointer.data
Stream(index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
       alignment=Alignment(byte_size=0, bit_offset=0),
       bit_size=0,
       value='')
>>> pointer.data_size
0
>>> len(pointer)
0
>>> pointer.data_byte_order
Byteorder.little = 'little'
>>> pointer.bytestream
''
>>> pointer.value
'0x0'
>>> bytes(pointer)
b'\x00\x00\x00\x00'
>>> int(pointer)
0
>>> float(pointer)
0.0
>>> hex(pointer)
'0x0'
>>> bin(pointer)
'0b0'
>>> oct(pointer)
'0o0'
>>> bool(pointer)
False
>>> pointer.as_signed()
0
>>> pointer.as_unsigned()
0
>>> pointer.deserialize(bytes.fromhex('00c0'))
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.value
'0xc000'
>>> pointer.value = 0x4000
>>> pointer.value
'0x4000'
>>> pointer.value = -0x1
>>> pointer.value
'0x0'
>>> pointer.value = 0x100000000
>>> pointer.value
'0xffffffff'
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> pointer.serialize(bytestream)
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> bytestream.hex()
'ffffffff'
>>> pointer.resize(10)
>>> pointer.data_size
10
>>> len(pointer)
10
>>> pointer.bytestream = b'KonFoo is Fun'
>>> pointer.bytestream
'4b6f6e466f6f2069732046756e'
>>> pointer.serialize_data().hex()
'00000000000000000000'
>>> pointer.deserialize_data()
Index(byte=10, bit=0, address=4294967305, base_address=0, update=False)
>>> pointer.serialize_data()
b'KonFoo is '
>>> [byte for byte in pointer]  # converts to int
[75, 111, 110, 70, 111, 111, 32, 105, 115, 32]
>>> [hex(byte) for byte in pointer]
['0x4b', '0x6f', '0x6e', '0x46', '0x6f', '0x6f', '0x20', '0x69', '0x73', '0x20']
>>> pointer[5]  # converts to int
111
>>> 111 in pointer
True
>>> 0x0 in pointer
False
>>> pointer[:6]  # converts to bytes
b'KonFoo'
>>> pointer[3:6]  # converts to bytes
b'Foo'
>>> pointer.describe()  
{'address': 0,
 'alignment': [4, 0],
 'class': 'StreamRelativePointer',
 'index': [0, 0],
 'max': 4294967295,
 'min': 0,
 'name': 'StreamRelativePointer',
 'order': 'auto',
 'signed': False,
 'size': 32,
 'type': 'Pointer',
 'value': '0xffffffff',
 'member': [
    {'address': 4294967295,
     'alignment': [10, 0],
     'class': 'Stream10',
     'index': [0, 0],
     'name': 'data',
     'order': 'auto',
     'size': 80,
     'type': 'Field',
     'value': '4b6f6e466f6f20697320'}
 ]}
>>> pointer.index_fields()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.view_fields()
{'value': '0xffffffff', 'data': '4b6f6e466f6f20697320'}
>>> pointer.to_json()
'{"value": "0xffffffff", "data": "4b6f6e466f6f20697320"}'
>>> pointer.field_items()
[('field',
  StreamRelativePointer(index=Index(byte=0, bit=0,
                                    address=0, base_address=0,
                                    update=False),
                        alignment=Alignment(byte_size=4, bit_offset=0),
                        bit_size=32,
                        value='0xffffffff')),
 ('data',
  Stream(index=Index(byte=0, bit=0,
                     address=4294967295, base_address=0,
                     update=False),
         alignment=Alignment(byte_size=10, bit_offset=0),
         bit_size=80,
         value='4b6f6e466f6f20697320'))]
>>> pointer.to_list()
[('StreamRelativePointer.field', '0xffffffff'),
 ('StreamRelativePointer.data', '4b6f6e466f6f20697320')]
>>> pointer.to_dict()
{'StreamRelativePointer': {'field': '0xffffffff', 'data': '4b6f6e466f6f20697320'}}

resize(capacity: int) → None

Re-sizes the Stream field by appending zero bytes or removing bytes from the end.

Parameters:

capacity (int) – Stream capacity in number of bytes.

class konfoo.StreamRelativePointer8(capacity: int = 0, address: int | None = None)

The StreamRelativePointer8 field is a StreamRelativePointer field with a Field size of one byte.

class konfoo.StreamRelativePointer16(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StreamRelativePointer16 field is a StreamRelativePointer field with a Field size of two bytes.

class konfoo.StreamRelativePointer24(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StreamRelativePointer24 field is a StreamRelativePointer field with a Field size of three bytes.

class konfoo.StreamRelativePointer32(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StreamRelativePointer32 field is a StreamRelativePointer field with a Field size of four bytes.

class konfoo.StreamRelativePointer48(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StreamRelativePointer48 field is a StreamRelativePointer field with a Field size of six bytes.

class konfoo.StreamRelativePointer64(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StreamRelativePointer64 field is a StreamRelativePointer field with a Field size of eight bytes.

String Relative Pointer

class konfoo.StringRelativePointer(capacity: int = 0, address: int | None = None, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StringRelativePointer field is a StreamRelativePointer field which refers to a String field.

Parameters:

• capacity (int) – is the capacity of the String field in bytes.

• address (int|None) – relative address of the data object referenced by the RelativePointer field.

• bit_size (int) – is the size of the RelativePointer field in bits, can be between 1 and 64.

• align_to (int|None) – aligns the RelativePointer field to the number of bytes, can be between 1 and 8. If no field alignment is set the RelativePointer field aligns itself to the next matching byte size according to the size of the RelativePointer field.

• field_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the value of the RelativePointer field.

Example:

>>> pointer = StringRelativePointer()
>>> pointer.is_decimal()
True
>>> pointer.is_pointer()
True
>>> pointer.name
'Pointer32'
>>> pointer.alignment
Alignment(byte_size=4, bit_offset=0)
>>> pointer.byte_order
Byteorder.auto = 'auto'
>>> pointer.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)
>>> pointer.index_field()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.bit_size
32
>>> pointer.signed
False
>>> pointer.min()
0
>>> pointer.max()
4294967295
>>> pointer.base_address
0
>>> pointer.address
0
>>> pointer.is_null()
True
>>> pointer.as_signed()
0
>>> pointer.as_unsigned()
0
>>> pointer.data
String(index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
       alignment=Alignment(byte_size=0, bit_offset=0),
       bit_size=0,
       value='')
>>> pointer.data_size
0
>>> len(pointer)
0
>>> pointer.data_byte_order
Byteorder.little = 'little'
>>> pointer.bytestream
''
>>> pointer.value
'0x0'
>>> bytes(pointer)
b'\x00\x00\x00\x00'
>>> int(pointer)
0
>>> float(pointer)
0.0
>>> hex(pointer)
'0x0'
>>> bin(pointer)
'0b0'
>>> oct(pointer)
'0o0'
>>> bool(pointer)
False
>>> pointer.deserialize(bytes.fromhex('00c0'))
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.value
'0xc000'
>>> pointer.value = 0x4000
>>> pointer.value
'0x4000'
>>> pointer.value = -0x1
>>> pointer.value
'0x0'
>>> pointer.value = 0x100000000
>>> pointer.value
'0xffffffff'
>>> bytestream = bytearray()
>>> bytestream
bytearray(b'')
>>> pointer.serialize(bytestream)
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> bytestream.hex()
'ffffffff'
>>> pointer.resize(10)
>>> pointer.data_size
10
>>> len(pointer)
10
>>> pointer.bytestream = b'KonFoo is Fun'
>>> pointer.bytestream
'4b6f6e466f6f2069732046756e'
>>> pointer.serialize_data().hex()
'00000000000000000000'
>>> pointer.deserialize_data()
Index(byte=10, bit=0, address=4294967305, base_address=0, update=False)
>>> pointer.serialize_data()
b'KonFoo is '
>>> [byte for byte in pointer]  # converts to int
[75, 111, 110, 70, 111, 111, 32, 105, 115, 32]
>>> [chr(byte) for byte in pointer]  # converts to int
['K', 'o', 'n', 'F', 'o', 'o', ' ', 'i', 's', ' ']
>>> chr(pointer[5])  # converts to int -> chr
'o'
>>> ord(' ') in pointer
True
>>> 0x0 in pointer
False
>>> pointer[:6]  # converts to bytes
b'KonFoo'
>>> pointer[3:6]  # converts to bytes
b'Foo'
>>> pointer.describe()  
{'address': 0,
 'alignment': [4, 0],
 'class': 'StringRelativePointer',
 'index': [0, 0],
 'max': 4294967295,
 'min': 0,
 'name': 'StringRelativePointer',
 'order': 'auto',
 'signed': False,
 'size': 32,
 'type': 'Pointer',
 'value': '0xffffffff',
 'member': [
    {'address': 4294967295,
     'alignment': [10, 0],
     'class': 'String10',
     'index': [0, 0],
     'name': 'data',
     'order': 'auto',
     'size': 80,
     'type': 'Field',
     'value': 'KonFoo is '}
 ]}
>>> pointer.index_fields()
Index(byte=4, bit=0, address=4, base_address=0, update=False)
>>> pointer.view_fields()
{'value': '0xffffffff', 'data': 'KonFoo is '}
>>> pointer.to_json()
'{"value": "0xffffffff", "data": "KonFoo is "}'
>>> pointer.field_items()
[('field',
  StringRelativePointer(index=Index(byte=0, bit=0,
                                    address=0, base_address=0,
                                    update=False),
                        alignment=Alignment(byte_size=4, bit_offset=0),
                        bit_size=32,
                        value='0xffffffff')),
 ('data',
  String(index=Index(byte=0, bit=0,
                     address=4294967295, base_address=0,
                     update=False),
         alignment=Alignment(byte_size=10, bit_offset=0),
         bit_size=80,
         value='KonFoo is '))]
>>> pointer.to_list()
[('StringRelativePointer.field', '0xffffffff'),
 ('StringRelativePointer.data', 'KonFoo is ')]
>>> pointer.to_dict()
{'StringRelativePointer': {'field': '0xffffffff', 'data': 'KonFoo is '}}

class konfoo.StringRelativePointer8(capacity: int = 0, address: int | None = None)

The StringRelativePointer8 field is a StringRelativePointer field with a Field size of one byte.

class konfoo.StringRelativePointer16(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StringRelativePointer16 field is a StringRelativePointer field with a Field size of two bytes.

class konfoo.StringRelativePointer24(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StringRelativePointer24 field is a StringRelativePointer field with a Field size of three bytes.

class konfoo.StringRelativePointer32(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StringRelativePointer32 field is a StringRelativePointer field with a Field size of four bytes.

class konfoo.StringRelativePointer48(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StringRelativePointer48 field is a StringRelativePointer field with a Field size of six bytes.

class konfoo.StringRelativePointer64(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')

The StringRelativePointer64 field is a StringRelativePointer field with a Field size of eight bytes.

Byteorder

class konfoo.Byteorder(value)

Byte order categories.

auto: Byteorder = 'auto'

Byte order is defined by the de-/serializer.

big: Byteorder = 'big'

Byte order is big endian.

little: Byteorder = 'little'

Byte order is big little.

Field Index

class konfoo.Index(byte: int = 0, bit: int = 0, address: int = 0, base_address: int = 0, update: bool = False)

The Index class contains the relevant information of the location of a Field in a byte stream and in a data source. The byte stream is normally provided by a Pointer field. The data source is normally accessed via a data Provider by a Pointer field.

Parameters:

• byte (int) – byte offset of the Field in the byte stream.

• bit (int) – bit offset of the Field relative to its byte offset.

• address (int) – address of the Field in the data source.

• base_address (int) – start address of the byte stream in the data source.

• update (bool) – if True the byte stream needs to be updated.

Field Alignment

class konfoo.Alignment(byte_size: int = 0, bit_offset: int = 0)

The Alignment class contains the location of the Field within an aligned group of consecutive fields.

Parameters:

• byte_size (int) – size of the field group in bytes which the Field is aligned to.

• bit_offset (int) – bit offset of the Field within its aligned field group.

Memory Patch

class konfoo.Patch(buffer: bytes, address: int, byteorder: Byteorder, bit_size: int, bit_offset: int, inject: bool = False)

The Patch class contains the relevant information to patch a memory area of a data source accessed via a data Provider by a Pointer field.

Parameters:

• buffer (bytes) – byte stream for the memory area to patch within the data source. The byte stream contains the data of the patch item.

• address (int) – address of the memory area to patch in the data source.

• byteorder (Byteorder) – byte order of the memory area to patch in the data source.

• bit_size (int) – bit size of the patch item.

• bit_offset (int) – bit offset of the patch item within the memory area.

• inject (bool) – if True the patch item must be injected into the memory area.

Enumerations

class konfoo.Enumeration(value)

The Enumeration class is a subclass from the IntEnum class provided by the Python standard module enum, and extends its base class with methods

• to describe a specific Enumeration member by its name, value tuple

• to list the member names of an Enumeration

• to list the member values of an Enumeration

• to get the value of the Enumeration member by its name

• to get the name of the Enumeration member by its value

• to get the member of the Enumeration by its value

Example:

>>> class Color(Enumeration):
...     black = 0x000000
...     maroon = 0x080000
...     white = 0xffffff
>>> Color
<enum 'Color'>
>>> type(Color.maroon)
<enum 'Color'>
>>> isinstance(Color, Enumeration)
False
>>> issubclass(Color, Enumeration)
True
>>> isinstance(Color.maroon, Color)
True
>>> print(Color.maroon)
(maroon, 524288)
>>> str(Color.maroon)
'(maroon, 524288)'
>>> Color.maroon
Color.maroon = 524288
>>> repr(Color.maroon)
'Color.maroon = 524288'
>>> list(Color)
[Color.black = 0, Color.maroon = 524288, Color.white = 16777215]
>>> [color for color in Color]
[Color.black = 0, Color.maroon = 524288, Color.white = 16777215]
>>> Color.maroon.name
'maroon'
>>> Color.maroon.value
524288
>>> Color.maroon.describe()
('maroon', 524288)
>>> [member.name for member in Color]
['black', 'maroon', 'white']
>>> Color.names()
['black', 'maroon', 'white']
>>> [member.value for member in Color]
[0, 524288, 16777215]
>>> Color.values()
[0, 524288, 16777215]
>>> Color['maroon'].value
524288
>>> Color.get_value('maroon')
524288
>>> Color(0).name
'black'
>>> Color.get_name(0)
'black'
>>> Color.get_member(0)
Color.black = 0
>>> int(Color.black)
0
>>> 0 in Color.values()
True
>>> 'black' in Color.names()
True

describe() → tuple[str, int]

Returns the name, value tuple to describe a specific Enumeration member.

Example:

>>> class Color(Enumeration):
...     black = 0x000000
...     maroon = 0x080000
...     white = 0xffffff
>>> Color.maroon.describe()
('maroon', 524288)

classmethod names() → list[str]

Returns a list of the member names of an Enumeration.

Example:

>>> class Color(Enumeration):
...     black = 0x000000
...     maroon = 0x080000
...     white = 0xffffff
>>> Color.names()
['black', 'maroon', 'white']

classmethod values() → list[int]

Returns a list of the member values of an Enumeration.

Example:

>>> class Color(Enumeration):
...     black = 0x000000
...     maroon = 0x080000
...     white = 0xffffff
>>> Color.values()
[0, 524288, 16777215]

classmethod get_name(value: int) → str

Returns the name of the Enumeration member matches the value, or an empty string if no member match.

Example:

>>> class Color(Enumeration):
...     black = 0x000000
...     maroon = 0x080000
...     white = 0xffffff
>>> Color.get_name(0xffffff)
'white'
>>> Color.get_name(0x777777)
''

classmethod get_value(name: str) → int | None

Returns the value of the Enumeration member matches the name, or None if no member match.

Example:

>>> class Color(Enumeration):
...     black = 0x000000
...     maroon = 0x080000
...     white = 0xffffff
>>> Color.get_value('white')
16777215
>>> Color.get_value('red')

classmethod get_member(value: int, default: Enumeration | None = None) → Enumeration | None

Returns the first Enumeration member matches the value, or the specified default member if no member match.

Example:

>>> class Color(Enumeration):
...     black = 0x000000
...     maroon = 0x080000
...     white = 0xffffff
>>> Color.get_member(0)
Color.black = 0
>>> Color.get_member(0x777777, None)

Categories

class konfoo.Category(value)

The Category class is a is a subclass of the Enum class provided by the Python standard module enum, and extends its base class with methods

• to describe a specific Category member by its name, value tuple

• to list the member names of a Category

• to list the member values of a Category

• to get the value of the Category member by its name

• to get the name of the Category member by is value

• to get the member of the Category by its value

Example:

>>> class Format(Category):
...     hour = 'hh'
...     minute = 'mm'
...     second = 'ss'
>>> Format
<enum 'Format'>
>>> type(Format.hour)
<enum 'Format'>
>>> isinstance(Format, Category)
False
>>> issubclass(Format, Category)
True
>>> isinstance(Format.hour, Format)
True
>>> print(Format.hour)
(hour, hh)
>>> str(Format.hour)
'(hour, hh)'
>>> Format.hour
Format.hour = 'hh'
>>> repr(Format.hour)
"Format.hour = 'hh'"
>>> list(Format)
[Format.hour = 'hh', Format.minute = 'mm', Format.second = 'ss']
>>> [format for format in Format]
[Format.hour = 'hh', Format.minute = 'mm', Format.second = 'ss']
>>> Format.hour.name
'hour'
>>> Format.hour.value
'hh'
>>> Format.hour.describe()
('hour', 'hh')
>>> [member.name for member in Format]
['hour', 'minute', 'second']
>>> Format.names()
['hour', 'minute', 'second']
>>> [member.value for member in Format]
['hh', 'mm', 'ss']
>>> Format.values()
['hh', 'mm', 'ss']
>>> Format['hour'].value
'hh'
>>> Format.get_value('hour')
'hh'
>>> Format('hh').name
'hour'
>>> Format.get_name('hh')
'hour'
>>> Format.get_member('hh')
Format.hour = 'hh'
>>> 'hh' in Format.values()
True
>>> 'hour' in Format.names()
True

describe() → tuple[str, Any]

Returns the name, value tuple to describe a specific Category member.

Example:

>>> class Format(Category):
...     hour = 'hh'
...     minute = 'mm'
...     second = 'ss'
>>> Format.hour.describe()
('hour', 'hh')

classmethod names() → list[str]

Returns a list of the member names of a Category.

Example:

>>> class Format(Category):
...     hour = 'hh'
...     minute = 'mm'
...     second = 'ss'
>>> Format.names()
['hour', 'minute', 'second']

classmethod values() → list[Any]

Returns a list of the member values of a Category.

Example:

>>> class Format(Category):
...     hour = 'hh'
...     minute = 'mm'
...     second = 'ss'
>>> Format.values()
['hh', 'mm', 'ss']

classmethod get_name(value: Any) → str

Returns the name of the Category member matches the value, or an empty string if no member match.

Example:

>>> class Format(Category):
...     hour = 'hh'
...     minute = 'mm'
...     second = 'ss'
>>> Format.get_name('hh')
'hour'
>>> Format.get_name('dd')
''

classmethod get_value(name: str) → Any | None

Returns the value of the Category member matches the name, or None if no member match.

Example:

>>> class Format(Category):
...     hour = 'hh'
...     minute = 'mm'
...     second = 'ss'
>>> Format.get_value('hour')
'hh'
>>> Format.get_value('day')

classmethod get_member(value: Any, default: Category | None = None) → Category | None

Returns the first Category member matches the value, or the specified default member if no member match.

Example:

>>> class Format(Category):
...     hour = 'hh'
...     minute = 'mm'
...     second = 'ss'
>>> Format.get_member('hh')
Format.hour = 'hh'
>>> Format.get_member('day', None)

Exceptions

exception konfoo.ByteOrderTypeError(field: Field, byte_order: Any)

Raised if an inappropriate byte order type is assigned to a field class.

exception konfoo.EnumTypeError(field: Field, enumeration: Type[Any])

Raised if an inappropriate enum type is assigned to a field class.

exception konfoo.FactoryTypeError(field: Field | Structure | Sequence, factory, item: Field | Structure | Sequence, member: None = None, index: Index | None = None)

Raised if an inappropriate member type is produced by a factory class.

exception konfoo.MemberTypeError(field: Structure | Sequence | Pointer, item: Any, member: str | int | None = None, index: Index | None = None)

Raised if an inappropriate member type is assigned to any container class.

exception konfoo.ProviderTypeError(field: Field, provider: Any)

Raised if an inappropriate data provider type is assigned to a pointer class.

exception konfoo.ContainerLengthError(field: Structure | Sequence | Pointer, length: tuple[int, int])

Raised if a container class has an inappropriate field length.

exception konfoo.FieldAddressError(field: Field, index: Index, address: int)

Raised if an inappropriate address is assigned to a field class.

exception konfoo.FieldAlignmentError(field: Field, index: Index, alignment: Alignment)

Raised if an inappropriate alignment value is assigned to a field class.

exception konfoo.FieldByteOrderError(field: Field, index: Index, byte_order: Byteorder)

Raised if an inappropriate byte order value is assigned to a field class.

exception konfoo.FieldIndexError(field: Field, index: Index)

Raised if an inappropriate index value is assigned to a field class.

exception konfoo.FieldSizeError(field: Field, index: Index, size: int)

Raised if an inappropriate bit size value is assigned to a field class.

exception konfoo.FieldTypeError(field: Field, index: Index, value: Any)

Raised if an inappropriate argument type is assigned to a field class.

exception konfoo.FieldValueError(field: Field, index: Index, value)

Raised if an inappropriate argument value is assigned to a field class.

exception konfoo.FieldValueEncodingError(field: Field, index: Index, encoding: Any)

Raised if an inappropriate value encoding is assigned to a field class.

exception konfoo.FieldGroupByteOrderError(field: Field, index: Index, byte_order: Byteorder)

Raised if the byte order of a field contradicts its aligned field group.

exception konfoo.FieldGroupOffsetError(field: Field, index: Index, alignment: Alignment)

Raised if the alignment offset of a field does not match with its field group.

exception konfoo.FieldGroupSizeError(field: Field, index: Index, alignment: Alignment)

Raised if the alignment size of a field does not match with its field group.

Utilities

Metadata Converter

konfoo.d3flare_json(metadata: dict[str, Any], file=None, **options: Any) → str | None

Converts the metadata dictionary of a container or field into a flare.json formatted string or formatted stream written to the file

The flare.json format is defined by the d3.js graphic library.

The flare.json format looks like this:

{
    "class": "class of the field or container",
    "name":  "name of the field or container",
    "size":  "bit size of the field",
    "value": "value of the field",
    "children": []
}

Parameters:

• metadata (dict) – metadata generated from a Structure, Sequence, Array or any Field instance.

• file – optional file-like object to write to

Hexadecimal Viewer

class konfoo.HexViewer(columns: int = 16)

The HexViewer class writes or prints a source file or a byte stream as a hexadecimal dump to a output file or the console.

Parameters:

columns (int) – number of output columns. Allowed values are 8, 16 or 32.

Example:

>>> viewer = HexViewer()
>>> viewer.dump(b'KonF`00` is Fun.')
         | 00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 |
---------+-------------------------------------------------+-----------------
00000000 | 4B 6F 6E 46 60 30 30 60 20 69 73 20 46 75 6E 2E | KonF`00` is Fun.

property columns: int

Number of output columns.

file_dump(source: str, index: int = 0, count: int = 0, output: str = '') → None

Dumps the content of the source file to the console or to the optional given output file.

Parameters:

• source (str) – location and name of the source file.

• index (int) – optional start index of the viewing area in bytes. Default is from the begin of the file.

• count (int) – optional number of bytes to view. Default is to the end of the file.

• output (str) – location and name for the optional output file.

dump(stream: bytes, index: int = 0, count: int = 0, output: str = '') → None

Dumps the content of the byte stream to the console or to the optional given output file.

Parameters:

• stream (bytes) – byte stream to view.

• index (int) – optional start index of the viewing area in bytes. Default is the beginning of the stream.

• count (int) – optional number of bytes to view. Default is to the end of the stream.

• output (str) – location and name for the optional output file.