API¶

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

Provider¶

class konfoo.Provider[source]¶

A 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 meta class. A derived class must implement the two methods read() and write() for reading and writing byte streams from and back to the data source.

read(address=0, count=0)[source]¶

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

Parameters:	address (int) – start address. count (int) – number of bytes to read from a data source.

Note

This abstract method must be implemented by a derived class.

write(buffer=b'', address=0, count=0)[source]¶

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

Parameters:	buffer (bytes) – content to write. address (int) – start address. 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)[source]¶

A 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 = None¶: File path.

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

read(address=0, count=0)[source]¶

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=b'', address=0, count=0)[source]¶

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

Parameters:	buffer (bytes) – content to write. address (int) – start address. count (int) – number of bytes to write to the cache.

flush(file='')[source]¶

Flushes the updated file content to the given file.

Note

Overwrites an existing file.

Parameters:	file (str) – name and location of the file. Default is the original file.

Container¶

class konfoo.Container[source]¶

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.

view_fields(*attributes, **options)[source]¶

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) – 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.

to_json(*attributes, **options)[source]¶

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) – 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).

field_items(path='', **options)[source]¶

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, **options)[source]¶

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, **options)[source]¶

Returns a flatten ordered dictionary 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).

to_csv(*attributes, **options)[source]¶

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) – 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, *attributes, **options)[source]¶

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) – 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).

save(file, *attributes, **options)[source]¶

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, **options)[source]¶

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 lookup 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 valus 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}}'

Structure¶

class konfoo.Structure(*args, **kwargs)[source]¶

A Structure is an ordered dictionary 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 ordered dictionary with the Container interface and attribute getter and setter for the {'key': value} pairs 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 flatten list via field_items().
Get the metadata of the Structure via describe().

read_from(provider, **options)[source]¶

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=b'', index=Index(byte=0, bit=0, address=0, base_address=0, update=False), **options)[source]¶

De-serializes the Structure from the byte buffer starting at the begin 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.
index (Index) – current read Index within the buffer.
byte_order (Byteorder, str) – 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(b''), index=Index(byte=0, bit=0, address=0, base_address=0, update=False), **options)[source]¶

Serializes the Structure to the byte buffer starting at begin 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.
index (Index) – current write Index within the buffer.
byte_order (Byteorder, str) – 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(byte=0, bit=0, address=0, base_address=0, update=False), **options)[source]¶

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()[source]¶: 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()[source]¶: Returns the first Field in the Structure or None for an empty Structure.

initialize_fields(content)[source]¶

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

Parameters:	content (dict) – a dictionary contains the `Field` values for each member in the Structure.

view_fields(*attributes, **options)[source]¶

Returns an ordered dictionary which contains the {'member name': field attribute} or the {'member name': dict(field attributes)} pairs 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) – 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='', **options)[source]¶

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='', **options)[source]¶

Returns the metadata of the Structure as an ordered dictionary.

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=None)[source]¶

A 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 flatten list via field_items().
Get the metadata of the Sequence via describe().

Parameters:	iterable – 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)[source]¶

Appends the item to the end of the Sequence.

Parameters:	item – any `Structure`, `Sequence`, `Array` or `Field` instance.

insert(index, item)[source]¶

Inserts the item before the index into the Sequence.

Parameters:	index (int) – Sequence index. item – any `Structure`, `Sequence`, `Array` or `Field` instance.

pop(index=-1)[source]¶

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

Parameters:	index (int) – Sequence index.

clear()[source]¶: Remove all items from the Sequence.

remove(item)[source]¶

Removes the first occurrence of an item from the Sequence.

Parameters:	item – any `Structure`, `Sequence`, `Array` or `Field` instance.

reverse()[source]¶: In place reversing of the Sequence items.

extend(iterable)[source]¶

Extends the Sequence by appending items from the iterable.

Parameters:	iterable – 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, **options)[source]¶

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=b'', index=Index(byte=0, bit=0, address=0, base_address=0, update=False), **options)[source]¶

De-serializes the Sequence from the byte buffer starting at the begin 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.
index (Index) – current read Index within the buffer.
byte_order (Byteorder, str) – 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(b''), index=Index(byte=0, bit=0, address=0, base_address=0, update=False), **options)[source]¶

Serializes the Sequence to the byte buffer starting at begin 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.
index (Index) – current write Index within the buffer.
byte_order (Byteorder, str) – 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(byte=0, bit=0, address=0, base_address=0, update=False), **options)[source]¶

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()[source]¶: 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()[source]¶: Returns the first Field in the Sequence or None for an empty Sequence.

initialize_fields(content)[source]¶

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

Parameters:	content (list) – a list contains the `Field` values for each item in the Sequence.

view_fields(*attributes, **options)[source]¶

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) – 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='', **options)[source]¶

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='', **options)[source]¶

Returns the metadata of the Sequence as an ordered dictionary.

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, capacity=0)[source]¶

An 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()[source]¶: Appends a new array element to the Array.

insert(index)[source]¶

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

Parameters:	index (int) – Array index.

resize(capacity)[source]¶

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)[source]¶

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) – 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=0, align_to=0, byte_order='auto')[source]¶

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`, `str`) – byte order used to unpack and pack the `value` of the Field. Default is `auto`.

alignment¶: Returns the Alignment of the Field (read-only).

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

byte_order¶: Byteorder used to decode and encode the value of the Field.

index¶: Index of the Field.

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

value¶: Field value.

static is_bit()[source]¶: Returns False.

static is_bool()[source]¶: Returns False.

static is_decimal()[source]¶: Returns False.

static is_float()[source]¶: Returns False.

static is_pointer()[source]¶: Returns False.

static is_stream()[source]¶: Returns False.

static is_string()[source]¶: Returns False.

unpack(buffer=b'', index=Index(byte=0, bit=0, address=0, base_address=0, update=False), **options)[source]¶

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. index (Index) – current read `Index` within the buffer. byte_order (`Byteorder`, `str`) – decoding byte order for the de-serialization.

Note

This abstract method must be implemented by a derived class.

pack(buffer=bytearray(b''), **options)[source]¶

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. byte_order (`Byteorder`, `str`) – encoding byte order for the serialization.

Note

This abstract method must be implemented by a derived class.

deserialize(buffer=b'', index=Index(byte=0, bit=0, address=0, base_address=0, update=False), **options)[source]¶

De-serializes the Field from the byte buffer starting at the begin 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.
index (Index) – current read Index within the buffer.
byte_order (Byteorder, str) – 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(b''), index=Index(byte=0, bit=0, address=0, base_address=0, update=False), **options)[source]¶

Serializes the Field to the byte buffer starting at the begin 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.
index (Index) – current write Index of the buffer.
byte_order (Byteorder, str) – 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(byte=0, bit=0, address=0, base_address=0, update=False))[source]¶

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

Parameters:	index (Index) – start `Index` for the Field.

describe(name='', **options)[source]¶

Returns the metadata of a Field as an ordered dictionary.

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(size=0)[source]¶

A 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:	size (int) – is the size 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
>>> hexlify(stream[5:])  # converts to bytes
b'060708090a'
>>> stream.describe()
OrderedDict([('address', 0),
             ('alignment', [10, 0]),
             ('class', 'Stream10'),
             ('index', [0, 0]),
             ('name', 'Stream10'),
             ('order', 'auto'),
             ('size', 80),
             ('type', 'Field'),
             ('value', '0102030405060708090a')])

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

value¶: Field value as a lowercase hexadecimal encoded string.

hex()[source]¶: Returns a string containing two hexadecimal digits for each byte in the value of the Stream field.

static is_stream()[source]¶: Returns True.

unpack(buffer=b'', index=Index(byte=0, bit=0, address=0, base_address=0, update=False), **options)[source]¶

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. index (Index) – current read `Index` within the buffer. byte_order (`Byteorder`, `str`) – decoding byte order for the de-serialization.

Note

This abstract method must be implemented by a derived class.

pack(buffer=bytearray(b''), **options)[source]¶

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. byte_order (`Byteorder`, `str`) – encoding byte order for the serialization.

Note

This abstract method must be implemented by a derived class.

resize(size)[source]¶

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

Parameters:	size (int) – Stream size in number of bytes.

String¶

class konfoo.String(size=0)[source]¶

A 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:	size (int) – is the size 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()
OrderedDict([('address', 0),
             ('alignment', [10, 0]),
             ('class', 'String10'),
             ('index', [0, 0]),
             ('name', 'String10'),
             ('order', 'auto'),
             ('size', 80),
             ('type', 'Field'),
             ('value', 'KonFoo is ')])

value¶: Field value as an ascii encoded string.

static is_string()[source]¶: Returns True.

is_terminated()[source]¶: Returns True if the String field is zero-terminated.

Float¶

class konfoo.Float(byte_order='auto')[source]¶

A 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`, `str`) – 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()
OrderedDict([('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)])

value¶: Field value as a single precision floating point number.

static is_float()[source]¶: Returns True.

static smallest()[source]¶: Returns the smallest normalized field value of the Float field.

static max()[source]¶: Returns the maximal possible field value of the Float field.

static min()[source]¶: Returns the minimal possible field value of the Float field.

unpack(buffer=b'', index=Index(byte=0, bit=0, address=0, base_address=0, update=False), **options)[source]¶

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. index (Index) – current read `Index` within the buffer. byte_order (`Byteorder`, `str`) – decoding byte order for the de-serialization.

Note

This abstract method must be implemented by a derived class.

pack(buffer=bytearray(b''), **options)[source]¶

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. byte_order (`Byteorder`, `str`) – encoding byte order for the serialization.

Note

This abstract method must be implemented by a derived class.

describe(name='', **options)[source]¶

Returns the metadata of a Field as an ordered dictionary.

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`.

Double¶

class konfoo.Double(byte_order='auto')[source]¶

A 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`, `str`) – 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()
OrderedDict([('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)])

value¶: Field value as a double precision floating point number.

static is_float()[source]¶: Returns True.

static smallest()[source]¶: Returns the smallest normalized field value of the Double field.

static max()[source]¶: Returns the maximal possible field value of the Double field.

static min()[source]¶: Returns the minimal possible field value of the Double field.

unpack(buffer=b'', index=Index(byte=0, bit=0, address=0, base_address=0, update=False), **options)[source]¶

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. index (Index) – current read `Index` within the buffer. byte_order (`Byteorder`, `str`) – decoding byte order for the de-serialization.

Note

This abstract method must be implemented by a derived class.

pack(buffer=bytearray(b''), **options)[source]¶

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. byte_order (`Byteorder`, `str`) – encoding byte order for the serialization.

Note

This abstract method must be implemented by a derived class.

describe(name='', **options)[source]¶

Returns the metadata of a Field as an ordered dictionary.

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`.

Decimal¶

class konfoo.Decimal(bit_size, align_to=None, signed=False, byte_order='auto')[source]¶

A 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) – 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, str) – 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)
>>> hexlify(bytestream)
b'ffff'
>>> unsigned.describe()
OrderedDict([('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)
>>> hexlify(bytestream)
b'ff7f'
>>> signed.describe()
OrderedDict([('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)])

value¶: Field value as a decimal number.

signed¶: Returns True if the Decimal field is signed.

static is_decimal()[source]¶: Returns True.

max()[source]¶: Returns the maximal possible field value of the Decimal field.

min()[source]¶: Returns the minimal possible field value of the Decimal field.

as_unsigned()[source]¶: Returns the field value of the Decimal field as an unsigned integer.

as_signed()[source]¶: Returns the field value of the Decimal field as a signed integer.

unpack(buffer=b'', index=Index(byte=0, bit=0, address=0, base_address=0, update=False), **options)[source]¶

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. index (Index) – current read `Index` within the buffer. byte_order (`Byteorder`, `str`) – decoding byte order for the de-serialization.

Note

This abstract method must be implemented by a derived class.

pack(buffer=bytearray(b''), **options)[source]¶

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. byte_order (`Byteorder`, `str`) – encoding byte order for the serialization.

Note

This abstract method must be implemented by a derived class.

describe(name=None, **options)[source]¶

Returns the metadata of a Field as an ordered dictionary.

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`.

class konfoo.Decimal8(signed=False, byte_order='auto')[source]¶: A Decimal8 field is a Decimal field with a size of one byte and is by default unsigned.

class konfoo.Decimal16(signed=False, byte_order='auto')[source]¶: A Decimal16 field is a Decimal field with a size of two bytes and is by default unsigned.

class konfoo.Decimal24(signed=False, byte_order='auto')[source]¶: A Decimal24 field is a Decimal field with a size of three bytes and is by default unsigned.

class konfoo.Decimal32(signed=False, byte_order='auto')[source]¶: A Decimal32 field is a Decimal field with a size of four bytes and is by default unsigned.

class konfoo.Decimal64(signed=False, byte_order='auto')[source]¶: A Decimal64 field is a Decimal field with a size of eight bytes and is by default unsigned.

Bit¶

class konfoo.Bit(number, align_to=None)[source]¶

A 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) – 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)
>>> hexlify(bytestream)
b'01'
>>> bit.describe()
OrderedDict([('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)])

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

static is_bit()[source]¶: Returns True.

Byte¶

class konfoo.Byte(align_to=None)[source]¶

A 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) – 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)
>>> hexlify(bytestream)
b'ff'
>>> byte.describe()
OrderedDict([('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')])

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

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

Char¶

class konfoo.Char(align_to=None)[source]¶

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

Parameters:	align_to (int) – 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)
>>> hexlify(bytestream)
b'46'
>>> char.describe()
OrderedDict([('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')])

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

value¶: Field value as an unicode string character.

Signed¶

class konfoo.Signed(bit_size, align_to=None, byte_order='auto')[source]¶

A 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) – 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, str) – 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)
>>> hexlify(bytestream)
b'ff7f'
>>> signed.describe()
OrderedDict([('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='auto')[source]¶: A Signed8 field is a Signed field with a size of one byte.

class konfoo.Signed16(byte_order='auto')[source]¶: A Signed16 field is a Signed field with a size of two bytes.

class konfoo.Signed24(byte_order='auto')[source]¶: A Signed24 field is a Signed field with a size of three bytes.

class konfoo.Signed32(byte_order='auto')[source]¶: A Signed32 field is a Signed field with a size of four bytes.

class konfoo.Signed64(byte_order='auto')[source]¶: A Signed64 field is a Signed field with a size of eight bytes.

Unsigned¶

class konfoo.Unsigned(bit_size, align_to=None, byte_order='auto')[source]¶

A 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) – 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, str) – 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)
>>> hexlify(bytestream)
b'ffff'
>>> unsigned.describe()
OrderedDict([('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')])

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

class konfoo.Unsigned8(byte_order='auto')[source]¶: A Unsigned8 field is an Unsigned field with a size of one byte.

class konfoo.Unsigned16(byte_order='auto')[source]¶: A Unsigned16 field is an Unsigned field with a size of two bytes.

class konfoo.Unsigned24(byte_order='auto')[source]¶: A Unsigned24 field is an Unsigned field with a size of three bytes.

class konfoo.Unsigned32(byte_order='auto')[source]¶: A Unsigned32 field is an Unsigned field with a size of four bytes.

class konfoo.Unsigned64(byte_order='auto')[source]¶: A Unsigned64 field is an Unsigned field with a size of eight bytes.

Bitset¶

class konfoo.Bitset(bit_size, align_to=None, byte_order='auto')[source]¶

A 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) – 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, str) – 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)
>>> hexlify(bytestream)
b'ffff'
>>> bitset.describe()
OrderedDict([('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')])

value¶: Field value as a binary string prefixed with 0b.

class konfoo.Bitset8(byte_order='auto')[source]¶: A Bitset8 field is a Bitset field with a size of one byte.

class konfoo.Bitset16(byte_order='auto')[source]¶: A Bitset16 field is a Bitset field with a size of two bytes.

class konfoo.Bitset24(byte_order='auto')[source]¶: A Bitset24 field is a Bitset field with a size of three bytes.

class konfoo.Bitset32(byte_order='auto')[source]¶: A Bitset32 field is a Bitset field with a size of four bytes.

class konfoo.Bitset64(byte_order='auto')[source]¶: A Bitset64 field is a Bitset field with a size of eight bytes.

Bool¶

class konfoo.Bool(bit_size, align_to=None, byte_order='auto')[source]¶

A 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) – 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, str) – 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)
>>> hexlify(bytestream)
b'ffff'
>>> boolean.describe()
OrderedDict([('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)])

value¶: Field value as a boolean value, True or False.

static is_bool()[source]¶: Returns True.

class konfoo.Bool8(byte_order='auto')[source]¶: A Bool8 field is a Bool field with a size of one byte.

class konfoo.Bool16(byte_order='auto')[source]¶: A Bool16 field is a Bool field with a size of two bytes.

class konfoo.Bool24(byte_order='auto')[source]¶: A Bool24 field is a Bool field with a size of three bytes.

class konfoo.Bool32(byte_order='auto')[source]¶: A Bool32 field is a Bool field with a size of four bytes.

class konfoo.Bool64(byte_order='auto')[source]¶: A Bool64 field is a Bool field with a size of eight bytes.

Enum¶

class konfoo.Enum(bit_size, align_to=None, enumeration=None, byte_order='auto')[source]¶

A 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) – 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 – Enumeration definition of the Enum field.
byte_order (Byteorder, str) – 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)
>>> hexlify(bytestream)
b'ffff'
>>> enum.describe()
OrderedDict([('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)])

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

class konfoo.Antivalent(align_to=None, byte_order='auto')[source]¶

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

class Validity[source]¶: An enumeration.

class konfoo.Enum4(align_to=None, enumeration=None, byte_order='auto')[source]¶: An Enum4 field is an Enum field with a size of four bits.

class konfoo.Enum8(enumeration=None, byte_order='auto')[source]¶: An Enum8 field is an Enum field with a size of one byte.

class konfoo.Enum16(enumeration=None, byte_order='auto')[source]¶: An Enum16 field is an Enum field with a size of two bytes.

class konfoo.Enum24(enumeration=None, byte_order='auto')[source]¶: An Enum24 field is an Enum field with a size of three bytes.

class konfoo.Enum32(enumeration=None, byte_order='auto')[source]¶: An Enum32 field is an Enum field with a size of four bytes.

class konfoo.Enum64(enumeration=None, byte_order='auto')[source]¶: An Enum64 field is an Enum field with a size of eight bytes.

Scaled¶

class konfoo.Scaled(scale, bit_size, align_to=None, byte_order='auto')[source]¶

A 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) – 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) – 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, str) – 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)
>>> hexlify(bytestream)
b'ff7f'
>>> scaled.describe()
OrderedDict([('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)])

value¶: Field value as a floating point number.

scale¶: Scaling factor of the Scaled field.

scaling_base()[source]¶: Returns the scaling base of the Scaled field.

describe(name=None, **options)[source]¶

Returns the metadata of a Field as an ordered dictionary.

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`.

class konfoo.Scaled8(scale, byte_order='auto')[source]¶: A Scaled8 field is a Scaled field with a size of one byte.

class konfoo.Scaled16(scale, byte_order='auto')[source]¶: A Scaled16 field is a Scaled field with a size of two bytes.

class konfoo.Scaled24(scale, byte_order='auto')[source]¶: A Scaled24 field is a Scaled field with a size of three bytes.

class konfoo.Scaled32(scale, byte_order='auto')[source]¶: A Scaled32 field is a Scaled field with a size of four bytes.

class konfoo.Scaled64(scale, byte_order='auto')[source]¶: A Scaled64 field is a Scaled field with a size of eight bytes.

Fraction¶

class konfoo.Fraction(bits_integer, bit_size, align_to=None, signed=False, byte_order='auto')[source]¶

A 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) – 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, str) – 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)
>>> hexlify(bytestream)
b'ffff'
>>> unipolar.describe()
OrderedDict([('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)
>>> hexlify(bytestream)
b'ff7f'
>>> bipolar.describe()
OrderedDict([('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)])

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

value¶: Field value as a floating point number.

describe(name=None, **options)[source]¶

Returns the metadata of a Field as an ordered dictionary.

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`.

Bipolar¶

class konfoo.Bipolar(bits_integer, bit_size, align_to=None, byte_order='auto')[source]¶

A 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) – 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, str) – 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)
>>> hexlify(bytestream)
b'ff7f'
>>> bipolar.describe()
OrderedDict([('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='auto')[source]¶: A Bipolar2 field is a Bipolar field with a size of two bytes and an integer part of two bits.

class konfoo.Bipolar4(byte_order='auto')[source]¶: A 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, bit_size, align_to=None, byte_order='auto')[source]¶

An 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) – 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, str) – 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)
>>> hexlify(bytestream)
b'ffff'
>>> unipolar.describe()
OrderedDict([('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='auto')[source]¶: An 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='auto')[source]¶

A 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`, `str`) – 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)
>>> hexlify(bytestream)
b'ffffffff'
>>> datetime.describe()
OrderedDict([('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')])

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

IPv4Address¶

class konfoo.IPv4Address(byte_order='auto')[source]¶

An 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`, `str`) – 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)
>>> hexlify(bytestream)
b'ffffffff'
>>> ipv4.describe()
OrderedDict([('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')])

value¶: Field value as an IPv4 address formatted string.

Pointer¶

class konfoo.Pointer(template=None, address=None, data_order=Byteorder.little = 'little', bit_size=32, align_to=None, field_order='auto')[source]¶

A 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 flatten list via field_items().
Get the metadata of the Pointer field via describe().

Parameters:

template – template for the data object referenced by the Pointer field.
address (int) – absolute address of the data object referenced by the Pointer field.
data_order (Byteorder, str) – 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) – 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, str) – 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)
>>> hexlify(bytestream)
b'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()
OrderedDict([('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()
OrderedDict([('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()
OrderedDict([('Pointer', OrderedDict([('field', '0xffffffff')]))])

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

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

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

data¶: Data object referenced by the Pointer field.

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

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

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

static is_pointer()[source]¶: Returns True.

is_null()[source]¶: Returns True if the Pointer field points to zero.

deserialize_data(buffer=b'', byte_order=None)[source]¶

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`, `str`) – decoding byte order for the de-serialization. Default is the `data_byte_order` of the Pointer field.

serialize_data(byte_order=None)[source]¶

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`, `str`) – encoding byte order for the serialization. Default is the `data_byte_order` of the Pointer field.

index_data()[source]¶: Indexes each Field in the data object referenced by the Pointer field.

read_from(provider, null_allowed=False, **options)[source]¶

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, byte_order=Byteorder.little = 'little')[source]¶

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

Parameters:	item – item to patch. byte_order (`Byteorder`, `str`) – encoding `Byteorder` for the item.

write_to(provider, item, byte_order=Byteorder.little = 'little')[source]¶

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

Parameters:	provider (Provider) – data `Provider`. item – item to write. byte_order (`Byteorder`, `str`) – encoding `Byteorder`.

deserialize(buffer=b'', index=Index(byte=0, bit=0, address=0, base_address=0, update=False), **options)[source]¶

De-serializes the Pointer field from the byte buffer starting at the begin 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.
index (Index) – current read Index within the buffer.
byte_order (Byteorder, str) – 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(b''), index=Index(byte=0, bit=0, address=0, base_address=0, update=False), **options)[source]¶

Serializes the Pointer field to the byte buffer starting at the begin 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 Poiner 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.
index (Index) – current write Index within the buffer.
byte_order (Byteorder, str) – 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)[source]¶

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) – 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(byte=0, bit=0, address=0, base_address=0, update=False), **options)[source]¶

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, **options)[source]¶

Returns an ordered dictionary 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) – 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='', **options)[source]¶

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='', **options)[source]¶

Returns the metadata of a Pointer as an ordered dictionary.

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=None, address=None, data_order=Byteorder.little = 'little')[source]¶: A Pointer8 field is a Pointer field with a Field size of one byte.

class konfoo.Pointer16(template=None, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: A Pointer16 field is a Pointer field with a Field size of two bytes.

class konfoo.Pointer24(template=None, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: A Pointer24 field is a Pointer field with a Field size of three bytes.

class konfoo.Pointer32(template=None, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: A Pointer32 field is a Pointer field with a Field size of four bytes.

class konfoo.Pointer48(template=None, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: A Pointer48 field is a Pointer field with a Field size of six bytes.

class konfoo.Pointer64(template=None, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: A Pointer64 field is a Pointer field with a Field size of eight bytes.

Structure Pointer¶

class konfoo.StructurePointer(template=None, address=None, data_order=Byteorder.little = 'little', bit_size=32, align_to=None, field_order='auto')[source]¶

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

Parameters:

template – template for the data object referenced by the Pointer field. The template must be a Structure instance.
address (int) – absolute address of the data object referenced by the Pointer field.
data_order (Byteorder, str) – 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) – 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, str) – 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
Structure()
>>> 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()
OrderedDict([('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',
              [OrderedDict([('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()
OrderedDict([('value', '0xffffffff'), ('data', OrderedDict())])
>>> 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)
OrderedDict([('StructurePointer', OrderedDict([('field', '0xffffffff')]))])

class konfoo.StructurePointer8(template=None, address=None, data_order=Byteorder.little = 'little')[source]¶: A StructurePointer8 field is a StructurePointer field with a Field size of one byte.

class konfoo.StructurePointer16(template=None, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: A StructurePointer16 field is a StructurePointer field with a Field size of two bytes.

class konfoo.StructurePointer24(template=None, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: A StructurePointer24 field is a StructurePointer field with a Field size of three bytes.

class konfoo.StructurePointer32(template=None, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: A StructurePointer32 field is a StructurePointer field with a Field size of four bytes.

class konfoo.StructurePointer48(template=None, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: A StructurePointer48 field is a StructurePointer field with a Field size of six bytes.

class konfoo.StructurePointer64(template=None, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: A StructurePointer64 field is a StructurePointer field with a Field size of eight bytes.

Sequence Pointer¶

class konfoo.SequencePointer(iterable=None, address=None, data_order=Byteorder.little = 'little', bit_size=32, align_to=None, field_order='auto')[source]¶

A 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 – 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) – absolute address of the data object referenced by the Pointer field.
data_order (Byteorder, str) – 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) – 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, str) – 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'
>>> hexlify(bytes(pointer))
b'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()
OrderedDict([('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',
              [OrderedDict([('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()
OrderedDict([('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)
OrderedDict([('SequencePointer', OrderedDict([('field', '0xffffffff')]))])

append(item)[source]¶

Appends the item to the end of the Sequence.

Parameters:	item – any `Structure`, `Sequence`, `Array` or `Field` instance.

insert(index, item)[source]¶

Inserts the item before the index into the Sequence.

Parameters:	index (int) – `Sequence` index. item – any `Structure`, `Sequence`, `Array` or `Field` instance.

pop(index=-1)[source]¶

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

Parameters:	index (int) – `Sequence` index.

clear()[source]¶: Remove all items from the Sequence.

remove(item)[source]¶

Removes the first occurrence of an item from the Sequence.

Parameters:	item – any `Structure`, `Sequence`, `Array` or `Field` instance.

reverse()[source]¶: In place reversing of the Sequence items.

extend(iterable)[source]¶

Extends the Sequence by appending items from the iterable.

Parameters:	iterable – 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, size=0, address=None, data_order=Byteorder.little = 'little', bit_size=32, align_to=None, field_order='auto')[source]¶

An 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 – 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.
size (int) – is the size of the Array in number of Array elements.
address (int) – absolute address of the data object referenced by the Pointer field.
data_order (Byteorder, str) – 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) – 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, str) – 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()
OrderedDict([('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',
              [OrderedDict([('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()
OrderedDict([('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)
OrderedDict([('ArrayPointer', OrderedDict([('field', '0xffffffff')]))])

append()[source]¶: Appends a new Array element to the Array.

insert(index)[source]¶

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

Parameters:	index (int) – `Array` index.

resize(size)[source]¶

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

Parameters:	size (int) – new size of the `Array` in number of `Array` elements.

class konfoo.ArrayPointer8(template, address=None, data_order=Byteorder.little = 'little')[source]¶: An ArrayPointer8 field is an ArrayPointer field with a Field size of one byte.

class konfoo.ArrayPointer16(template, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: An ArrayPointer16 field is an ArrayPointer field with a Field size of two bytes.

class konfoo.ArrayPointer24(template, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: An ArrayPointer24 field is an ArrayPointer field with a Field size of three bytes.

class konfoo.ArrayPointer32(template, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: An ArrayPointer32 field is an ArrayPointer field with a Field size of four bytes.

class konfoo.ArrayPointer48(template, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: An ArrayPointer48 field is an ArrayPointer field with a Field size of six bytes.

class konfoo.ArrayPointer64(template, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: An ArrayPointer64 field is an ArrayPointer field with a Field size of eight bytes.

Stream Pointer¶

class konfoo.StreamPointer(size=0, address=None, bit_size=32, align_to=None, field_order='auto')[source]¶

A 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:

size (int) – is the size of the Stream field in bytes.
address (int) – 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) – 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, str) – 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)
>>> hexlify(bytestream)
b'ffffffff'
>>> pointer.resize(10)
>>> pointer.data_size
10
>>> len(pointer)
10
>>> pointer.bytestream = b'KonFoo is Fun'
>>> pointer.bytestream
'4b6f6e466f6f2069732046756e'
>>> hexlify(pointer.serialize_data())
b'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
>>> pointer[:6]  # converts to bytes
b'KonFoo'
>>> pointer[3:6]  # converts to bytes
b'Foo'
>>> pointer.describe()
OrderedDict([('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',
              [OrderedDict([('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()
OrderedDict([('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()
OrderedDict([('StreamPointer',
              OrderedDict([('field', '0xffffffff'),
                           ('data', '4b6f6e466f6f20697320')]))])

resize(size)[source]¶

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

Parameters:	size (int) – `Stream` size in number of bytes.

class konfoo.StreamPointer8(size=0, address=None)[source]¶: A StreamPointer8 field is a StreamPointer field with a Field size of one byte.

class konfoo.StreamPointer16(size=0, address=None, field_order='auto')[source]¶: A StreamPointer16 field is a StreamPointer field with a Field size of two bytes.

class konfoo.StreamPointer24(size=0, address=None, field_order='auto')[source]¶: A StreamPointer24 field is a StreamPointer field with a Field size of three bytes.

class konfoo.StreamPointer32(size=0, address=None, field_order='auto')[source]¶: A StreamPointer32 field is a StreamPointer field with a Field size of four bytes.

class konfoo.StreamPointer48(size=0, address=None, field_order='auto')[source]¶: A StreamPointer48 field is a StreamPointer field with a Field size of six bytes.

class konfoo.StreamPointer64(size=0, address=None, field_order='auto')[source]¶: A StreamPointer64 field is a StreamPointer field with a Field size of eight bytes.

String Pointer¶

class konfoo.StringPointer(size=0, address=None, bit_size=32, align_to=None, field_order='auto')[source]¶

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

Parameters:

size (int) – is the size of the String field in bytes.
address (int) – 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) – 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, str) – 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)
>>> hexlify(bytestream)
b'ffffffff'
>>> pointer.resize(10)
>>> pointer.data_size
10
>>> len(pointer)
10
>>> pointer.bytestream = b'KonFoo is Fun'
>>> pointer.bytestream
'4b6f6e466f6f2069732046756e'
>>> hexlify(pointer.serialize_data())
b'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()
OrderedDict([('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',
              [OrderedDict([('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()
OrderedDict([('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()
OrderedDict([('StringPointer',
              OrderedDict([('field', '0xffffffff'), ('data', 'KonFoo is ')]))])

class konfoo.StringPointer8(size=0, address=None)[source]¶: A StringPointer8 field is a StringPointer field with a Field size of one byte.

class konfoo.StringPointer16(size=0, address=None, field_order='auto')[source]¶: A StringPointer16 field is a StringPointer field with a Field size of two bytes.

class konfoo.StringPointer24(size=0, address=None, field_order='auto')[source]¶: A StringPointer24 field is a StringPointer field with a Field size of three bytes.

class konfoo.StringPointer32(size=0, address=None, field_order='auto')[source]¶: A StringPointer32 field is a StringPointer field with a Field size of four bytes.

class konfoo.StringPointer48(size=0, address=None, field_order='auto')[source]¶: A StringPointer48 field is a StringPointer field with a Field size of six bytes.

class konfoo.StringPointer64(size=0, address=None, field_order='auto')[source]¶: A StringPointer64 field is a StringPointer field with a Field size of eight bytes.

Auto String Pointer¶

class konfoo.AutoStringPointer(address=None, bit_size=32, align_to=None, field_order='auto')[source]¶

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

Parameters:

address (int) – 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) – 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, str) – 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)
>>> hexlify(bytestream)
b'ffffffff'
>>> pointer.resize(10)
>>> pointer.data_size
10
>>> len(pointer)
10
>>> pointer.bytestream = b'KonFoo is Fun'
>>> pointer.bytestream
'4b6f6e466f6f2069732046756e'
>>> hexlify(pointer.serialize_data())
b'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()
OrderedDict([('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',
              [OrderedDict([('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()
OrderedDict([('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()
OrderedDict([('AutoStringPointer',
              OrderedDict([('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.

read_from(provider, null_allowed=False, **options)[source]¶

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`.

Relative Pointer¶

class konfoo.RelativePointer(template=None, address=None, data_order=Byteorder.little = 'little', bit_size=32, align_to=None, field_order='auto')[source]¶

A 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 – template for the data object referenced by the RelativePointer field.
address (int) – relative address of the data object referenced by the RelativePointer field.
data_order (Byteorder, str) – 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) – 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, str) – 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)
>>> hexlify(bytestream)
b'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()
OrderedDict([('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()
OrderedDict([('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()
OrderedDict([('RelativePointer', OrderedDict([('field', '0xffffffff')]))])

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

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

class konfoo.RelativePointer8(template=None, address=None, data_order=Byteorder.little = 'little')[source]¶: A RelativePointer8 field is a RelativePointer field with a Field size of one byte.

class konfoo.RelativePointer16(template=None, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: A RelativePointer16 field is a RelativePointer field with a Field size of two bytes.

class konfoo.RelativePointer24(template=None, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: A RelativePointer24 field is a RelativePointer field with a Field size of three bytes.

class konfoo.RelativePointer32(template=None, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: A RelativePointer32 field is a RelativePointer field with a Field size of four bytes.

class konfoo.RelativePointer48(template=None, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: A RelativePointer48 field is a RelativePointer field with a Field size of six bytes.

class konfoo.RelativePointer64(template=None, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: A RelativePointer64 field is a RelativePointer field with a Field size of eight bytes.

Structure Relative Pointer¶

class konfoo.StructureRelativePointer(template=None, address=None, data_order=Byteorder.little = 'little', bit_size=32, align_to=None, field_order='auto')[source]¶

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

Parameters:

template – template for the data object referenced by the RelativePointer field. The template must be a Structure instance.
address (int) – relative address of the data object referenced by the RelativePointer field.
data_order (Byteorder, str) – 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) – 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, str) – 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
Structure()
>>> 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()
OrderedDict([('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',
              [OrderedDict([('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()
OrderedDict([('value', '0xffffffff'), ('data', OrderedDict())])
>>> 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)
OrderedDict([('StructureRelativePointer',
              OrderedDict([('field', '0xffffffff')]))])

class konfoo.StructureRelativePointer8(template=None, address=None, data_order=Byteorder.little = 'little')[source]¶: A StructureRelativePointer8 field is a StructureRelativePointer field with a Field size of one byte.

class konfoo.StructureRelativePointer16(template=None, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: A StructureRelativePointer16 field is a StructureRelativePointer field with a Field size of two bytes.

class konfoo.StructureRelativePointer24(template=None, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶

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

Members:

class konfoo.StructureRelativePointer32(template=None, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: A StructureRelativePointer32 field is a StructureRelativePointer field with a Field size of four bytes.

class konfoo.StructureRelativePointer48(template=None, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: A StructureRelativePointer48 field is a StructureRelativePointer field with a Field size of six bytes.

class konfoo.StructureRelativePointer64(template=None, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: A StructureRelativePointer64 field is a StructureRelativePointer field with a Field size of eight bytes.

Sequence Relative Pointer¶

class konfoo.SequenceRelativePointer(iterable=None, address=None, data_order=Byteorder.little = 'little', bit_size=32, align_to=None, field_order='auto')[source]¶

A 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 – 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) – relative address of the data object referenced by the RelativePointer field.
data_order (Byteorder, str) – 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) – 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, str) – 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()
OrderedDict([('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',
              [OrderedDict([('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()
OrderedDict([('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)
OrderedDict([('SequenceRelativePointer',
              OrderedDict([('field', '0xffffffff')]))])

append(item)[source]¶

Appends the item to the end of the Sequence.

Parameters:	item – any `Structure`, `Sequence`, `Array` or `Field` instance.

insert(index, item)[source]¶

Inserts the item before the index into the Sequence.

Parameters:	index (int) – `Sequence` index. item – any `Structure`, `Sequence`, `Array` or `Field` instance.

pop(index=-1)[source]¶

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

Parameters:	index (int) – `Sequence` index

clear()[source]¶: Remove all items from the Sequence.

remove(item)[source]¶

Removes the first occurrence of an item from the Sequence.

Parameters:	item – any `Structure`, `Sequence`, `Array` or `Field` instance.

reverse()[source]¶: In place reversing of the Sequence items.

extend(iterable)[source]¶

Extends the Sequence by appending items from the iterable.

Parameters:	iterable – 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, size=0, address=None, data_order=Byteorder.little = 'little', bit_size=32, align_to=None, field_order='auto')[source]¶

An 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.
size (int) – is the size of the Array in number of Array elements.
address (int) – relative address of the data object referenced by the RelativePointer field.
data_order (Byteorder, str) – 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) – 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, str) – 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()
OrderedDict([('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',
              [OrderedDict([('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()
OrderedDict([('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)
OrderedDict([('ArrayRelativePointer', OrderedDict([('field', '0xffffffff')]))])

append()[source]¶: Appends a new Array element to the Array.

insert(index)[source]¶

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

Parameters:	index (int) – `Array` index.

resize(size)[source]¶

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

Parameters:	size (int) – new size of the `Array` in number of `Array` elements.

class konfoo.ArrayRelativePointer8(template, address=None, data_order=Byteorder.little = 'little')[source]¶: An ArrayRelativePointer8 field is an ArrayRelativePointer field with a Field size of one byte.

class konfoo.ArrayRelativePointer16(template, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: An ArrayRelativePointer16 field is an ArrayRelativePointer field with a Field size of two bytes.

class konfoo.ArrayRelativePointer24(template, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: An ArrayRelativePointer24 field is an ArrayRelativePointer field with a Field size of three bytes.

class konfoo.ArrayRelativePointer32(template, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: An ArrayRelativePointer32 field is an ArrayRelativePointer field with a Field size of four bytes.

class konfoo.ArrayRelativePointer48(template, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: An ArrayRelativePointer48 field is an ArrayRelativePointer field with a Field size of six bytes.

class konfoo.ArrayRelativePointer64(template, address=None, data_order=Byteorder.little = 'little', field_order='auto')[source]¶: An ArrayRelativePointer64 field is an ArrayRelativePointer field with a Field size of eight bytes.

Stream Relative Pointer¶

class konfoo.StreamRelativePointer(size=0, address=None, bit_size=32, align_to=None, field_order='auto')[source]¶

A 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:

size (int) – is the size of the Stream field in bytes.
address (int) – 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) – 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, str) – 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)
>>> hexlify(bytestream)
b'ffffffff'
>>> pointer.resize(10)
>>> pointer.data_size
10
>>> len(pointer)
10
>>> pointer.bytestream = b'KonFoo is Fun'
>>> pointer.bytestream
'4b6f6e466f6f2069732046756e'
>>> hexlify(pointer.serialize_data())
b'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()
OrderedDict([('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',
              [OrderedDict([('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()
OrderedDict([('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()
OrderedDict([('StreamRelativePointer',
              OrderedDict([('field', '0xffffffff'),
                           ('data', '4b6f6e466f6f20697320')]))])

resize(size)[source]¶

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

Parameters:	size (int) – `Stream` size in number of bytes.

class konfoo.StreamRelativePointer8(size=0, address=None)[source]¶: A StreamRelativePointer8 field is a StreamRelativePointer field with a Field size of one byte.

class konfoo.StreamRelativePointer16(size=0, address=None, field_order='auto')[source]¶: A StreamRelativePointer16 field is a StreamRelativePointer field with a Field size of two bytes.

class konfoo.StreamRelativePointer24(size=0, address=None, field_order='auto')[source]¶: A StreamRelativePointer24 field is a StreamRelativePointer field with a Field size of three bytes.

class konfoo.StreamRelativePointer32(size=0, address=None, field_order='auto')[source]¶: A StreamRelativePointer32 field is a StreamRelativePointer field with a Field size of four bytes.

class konfoo.StreamRelativePointer48(size=0, address=None, field_order='auto')[source]¶: A StreamRelativePointer48 field is a StreamRelativePointer field with a Field size of six bytes.

class konfoo.StreamRelativePointer64(size=0, address=None, field_order='auto')[source]¶: A StreamRelativePointer64 field is a StreamRelativePointer field with a Field size of eight bytes.

String Relative Pointer¶

class konfoo.StringRelativePointer(size=0, address=None, bit_size=32, align_to=None, field_order='auto')[source]¶

A StringRelativePointer field is a StreamRelativePointer which refers to a String field.

Parameters:

size (int) – is the size of the String field in bytes.
address (int) – 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) – 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, str) – 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)
>>> hexlify(bytestream)
b'ffffffff'
>>> pointer.resize(10)
>>> pointer.data_size
10
>>> len(pointer)
10
>>> pointer.bytestream = b'KonFoo is Fun'
>>> pointer.bytestream
'4b6f6e466f6f2069732046756e'
>>> hexlify(pointer.serialize_data())
b'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()
OrderedDict([('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',
              [OrderedDict([('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()
OrderedDict([('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()
OrderedDict([('StringRelativePointer',
              OrderedDict([('field', '0xffffffff'), ('data', 'KonFoo is ')]))])

class konfoo.StringRelativePointer8(size=0, address=None)[source]¶: A StringRelativePointer8 field is a StringRelativePointer field with a Field size of one byte.

class konfoo.StringRelativePointer16(size=0, address=None, field_order='auto')[source]¶: A StringRelativePointer16 field is a StringRelativePointer field with a Field size of two bytes.

class konfoo.StringRelativePointer24(size=0, address=None, field_order='auto')[source]¶: A StringRelativePointer24 field is a StringRelativePointer field with a Field size of three bytes.

class konfoo.StringRelativePointer32(size=0, address=None, field_order='auto')[source]¶: A StringRelativePointer32 field is a StringRelativePointer field with a Field size of four bytes.

class konfoo.StringRelativePointer48(size=0, address=None, field_order='auto')[source]¶: A StringRelativePointer48 field is a StringRelativePointer field with a Field size of six bytes.

class konfoo.StringRelativePointer64(size=0, address=None, field_order='auto')[source]¶: A StringRelativePointer64 field is a StringRelativePointer field with a Field size of eight bytes.

Byteorder¶

class konfoo.Byteorder[source]¶

Byte order categories.

auto = 'auto'¶

little = 'little'¶

big = 'big'¶

Field Index¶

class konfoo.Index(byte, bit, address, base_address, update)¶

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, bit_offset)¶

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, address, byteorder, bit_size, bit_offset, inject)¶

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 in 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 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 of the data source.

Enumerations¶

class konfoo.Enumeration[source]¶

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 pair
to list the member names of an Enumeration
to list the member values of an Enumeration
to get the value of the Enumeration member with the matching name
to get the name of the Enumeration member with the matching value
to get the member of the Enumeration with the matching 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)
>>> [color.name for color in Color]
['black', 'maroon', 'white']
>>> Color.names()
['black', 'maroon', 'white']
>>> [color.value for color 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()[source]¶

Returns the name, value pair to describe a specific Enumeration member.

Example:

>>> class Color(Enumeration):
...     black = 0x000000
...     maroon = 0x080000
...     white = 0xffffff
>>> Color.maroon.describe()
('maroon', 524288)

Categories¶

class konfoo.Category[source]¶

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 pair
to list the member names of a Category
to list the member values of a Category
to get the value of the Category member with the matching name
to get the name of the Category member with the matching value
to get the member of the Category with the matching 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')
>>> [format.name for format in Format]
['hour', 'minute', 'second']
>>> Format.names()
['hour', 'minute', 'second']
>>> [format.value for format 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()[source]¶

Returns the name, value pair to describe a specific Category member.

Example:

>>> class Format(Category):
...     hour = 'hh'
...     minute = 'mm'
...     second = 'ss'
>>> Format.hour.describe()
('hour', 'hh')

Exceptions¶

exception konfoo.ByteOrderTypeError(field, byte_order)[source]¶: Raised if an inappropriate byte order type is assigned to a field class.

exception konfoo.EnumTypeError(field, enumeration)[source]¶: Raised if an inappropriate enum type is assigned to a field class.

exception konfoo.FactoryTypeError(field, factory, item, member=None, index=None)[source]¶: Raised if an inappropriate member type is produced by a factory class.

exception konfoo.MemberTypeError(field, item, member=None, index=None)[source]¶: Raised if an inappropriate member type is assigned to any container class.

exception konfoo.ProviderTypeError(field, provider)[source]¶: Raised if an inappropriate data provider type is assigned to a pointer class.

exception konfoo.ContainerLengthError(field, length)[source]¶: Raised if a container class has an inappropriate field length.

exception konfoo.FieldAddressError(field, index, address)[source]¶: Raised if an inappropriate address is assigned to a field class.

exception konfoo.FieldAlignmentError(field, index, alignment)[source]¶: Raised if an inappropriate alignment value is assigned to a field class.

exception konfoo.FieldByteOrderError(field, index, byte_order)[source]¶: Raised if an inappropriate byte order value is assigned to a field class.

exception konfoo.FieldIndexError(field, index)[source]¶: Raised if an inappropriate index value is assigned to a field class.

exception konfoo.FieldSizeError(field, index, size)[source]¶: Raised if an inappropriate bit size value is assigned to a field class.

exception konfoo.FieldTypeError(field, index, value)[source]¶: Raised if an inappropriate argument type is assigned to a field class.

exception konfoo.FieldValueError(field, index, value)[source]¶: Raised if an inappropriate argument value is assigned to a field class.

exception konfoo.FieldValueEncodingError(field, index, encoding)[source]¶: Raised if an inappropriate value encoding is assigned to a field class.

exception konfoo.FieldGroupByteOrderError(field, index, byte_order)[source]¶: Raised if the byte order of a field contradicts its aligned field group.

exception konfoo.FieldGroupOffsetError(field, index, alignment)[source]¶: Raised if the alignment offset of a field does not match with its field group.

exception konfoo.FieldGroupSizeError(field, index, alignment)[source]¶: Raised if the alignment size of a field does not match with its field group.

Utilities¶

Metadata Converter¶

konfoo.d3flare_json(metadata, file=None, **options)[source]¶

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 (file) – file-like object.

Hexadecimal Viewer¶

class konfoo.HexViewer(columns=16)[source]¶

A HexViewer 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.

columns¶: Number of output columns.

file_dump(source, index=0, count=0, output='')[source]¶

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, index=0, count=0, output='')[source]¶

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 begin 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.