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 methodsread()
andwrite()
for reading and writing byte streams from and back to the data source.- abstract read(address=0, count=0)[source]#
Returns a number of bytes read from a data source beginning at the start address.
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 acache
. Theread()
andwrite()
methods only operate on the internalcache
.Call
flush()
to store the updated file content to the same or a new file.- path#
File path.
- property 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.
Container#
- class konfoo.Container[source]#
The Container class is an abstract interface for all classes which can contain
Field
items. Container classes areStructures
,Sequences
,Arrays
andPointers
.The Container class provides core features to view, save and load the attributes of the
Field
items in the Container.- abstract 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 fieldvalue
.fieldnames (tuple) – sequence of dictionary keys for the selected field attributes. Defaults to
(*attributes)
.nested (bool) – if
True
allPointer
fields in the Container views their referenceddata
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 fieldvalue
.fieldnames (tuple) – sequence of dictionary keys for the selected field attributes. Defaults to
(*attributes)
.nested (bool) – if
True
allPointer
fields in the Container views their referenceddata
object field attributes as well (chained method call).
- abstract field_items(path='', **options)[source]#
Returns a flatten list of
('field path', field item)
tuples for eachField
nested in the Container.- Parameters
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 eachField
nested in the Container.- Parameters
attributes (str) – selected
Field
attributes. Fallback is the fieldvalue
.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 toFalse
.nested (bool) – if
True
allPointer
fields in the Container lists their referenceddata
object field attributes as well (chained method call).
- to_dict(*attributes, **options)[source]#
Returns a flatten
dict
of{'field path': attribute}
or{'field path': tuple(attributes)}
pairs for eachField
nested in the Container.- Parameters
- 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 fieldvalue
.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
allPointer
fields in the Container lists their referenceddata
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 fieldvalue
.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
allPointer
fields in the Container lists their referenceddata
object field attributes as well (chained method call).
- write_json(file, *attributes, **options)[source]#
Writes the selected field attributes for each
Field
nested in the Container to a.json
file.- Parameters
file (str) – name and location of the
.json
file.attributes (str) – selected
Field
attributes. Fallback is the fieldvalue
.fieldnames (tuple) – sequence of dictionary keys for the selected field attributes. Defaults to
(*attributes)
.nested (bool) – if
True
allPointer
fields in the Container lists their referenceddata
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 fieldvalue
.section (str) – section in the
.ini
file to look for theField
values of the Container. If no section is specified the class name of the instance is used.nested (bool) – if
True
allPointer
fields in the Container saves their referenceddata
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 eachField
in the Container. If no section is specified the class name of the instance is used.nested (bool) – if
True
allPointer
fields in the Container load their referenceddata
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 a
dict
whereby the dictionary key describes the name of a member of the Structure and the value of the dictionary key describes the type of the member. Allowed members areStructure
,Sequence
,Array
orField
instances.The Structure class extends the
dict
with theContainer
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 eachdata
object referenced by thePointer
fields in the Structure viaread_from()
.Deserialize the
value
for eachField
in the Structure from a byte stream viadeserialize()
.Serialize the
value
for eachField
in the Structure to a byte stream viaserialize()
.Indexes all fields in the Structure via
index_fields()
.Get the first
Field
in the Structure viafirst_field()
.Get the accumulated size of all fields in the Structure via
container_size()
.View the selected attributes for each
Field
in the Structure viaview_fields()
.List the path to the field and the field item itself for each
Field
in the Structure as a flatten list viafield_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 dataProvider
for their referenceddata
object. Null pointer are ignored.- Parameters
- 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 eachField
in the Structure in accordance with the decoding byte order for the de-serialization and the decodingbyte_order
of eachField
in the Structure.A specific decoding
byte_order
of aField
overrules the decoding byte order for the de-serialization.Returns the
Index
of the buffer after the last de-serializedField
in the Structure.Optional the de-serialization of the referenced
data
objects of allPointer
fields in the Structure can be enabled.- Parameters
buffer (bytes) – byte stream.
byte_order (
Byteorder
,str
) – decoding byte order for the de-serialization.nested (bool) – if
True
allPointer
fields of a Structure de-serialize their referenceddata
object as well (chained method call). EachPointer
field uses for the de-serialization of its referenceddata
object its ownbytestream
.
- 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 eachField
in the Structure to the byte buffer in accordance with the encoding byte order for the serialization and the encodingbyte_order
of eachField
in the Structure.A specific encoding
byte_order
of aField
overrules the encoding byte order for the serialization.Returns the
Index
of the buffer after the last serializedField
in the Structure.Optional the serialization of the referenced
data
objects of allPointer
fields in the Structure can be enabled.- Parameters
buffer (bytearray) – byte stream.
byte_order (
Byteorder
,str
) – encoding byte order for the serialization.nested (bool) – if
True
allPointer
fields of a Structure serialize their referenceddata
object as well (chained method call). EachPointer
field uses for the serialization of its referenceddata
object its ownbytestream
.
- 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 lastField
in the Structure.
- 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)
.
- initialize_fields(content)[source]#
Initializes the
Field
members in the Structure with the values in the content dictionary.
- view_fields(*attributes, **options)[source]#
Returns an
dict
which contains the{'member name': field attribute}
or the{'member name': dict(field attributes)}
pairs for eachField
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 fieldvalue
.fieldnames (tuple) – sequence of dictionary keys for the selected field attributes. Defaults to
(*attributes)
.nested (bool) – if
True
allPointer
fields nested in the Structure views their referenceddata
object field attributes as well (chained method call).
- field_items(path='', **options)[source]#
Returns a flatten list of
('field path', field item)
tuples for eachField
nested in the Structure.
- describe(name='', **options)[source]#
Returns the metadata of the Structure as a
dict
.metadata = { 'class': self.__class__.__name__, 'name': name if name else self.__class__.__name__, 'size': len(self), 'type': Structure.item_type.name 'member': [ item.describe(member) for member, item in self.items() ] }
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 areStructure
,Sequence
,Array
orField
instances.A Sequence is:
containable:
item
inself
returnsTrue
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 eachdata
object referenced by thePointer
fields in the Sequence viaread_from()
.Deserialize the
value
for eachField
in the Sequence from a byte stream viadeserialize()
.Serialize the
value
for eachField
in the Sequence to a byte stream viaserialize()
.Indexes all fields in the Sequence via
index_fields()
.Get the first
Field
in the Sequence viafirst_field()
.Get the accumulated size of all fields in the Sequence via
container_size()
.View the selected attributes for each
Field
in the Sequence viaview_fields()
.List the path to the field and the field item itself for each
Field
in the Sequence as a flatten list viafield_items()
.Get the metadata of the Sequence via
describe()
.
- Parameters
iterable – any iterable that contains items of
Structure
,Sequence
,Array
orField
instances. If the iterable is one of these instances itself then the iterable itself is appended to the Sequence.
- pop(index=- 1)[source]#
Removes and returns the item at the index from the Sequence.
- Parameters
index (int) – Sequence index.
- read_from(provider, **options)[source]#
All
Pointer
fields in the Sequence read the necessary number of bytes from the dataProvider
for their referenceddata
object. Null pointer are ignored.- Parameters
- 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 eachField
in the Sequence in accordance with the decoding byte order for the de-serialization and the decodingbyte_order
of eachField
in the Sequence.A specific decoding
byte_order
of aField
overrules the decoding byte order for the de-serialization.Returns the
Index
of the buffer after the last de-serializedField
in the Sequence.Optional the de-serialization of the referenced
data
objects of allPointer
fields in the Sequence can be enabled.- Parameters
buffer (bytes) – byte stream.
byte_order (
Byteorder
,str
) – decoding byte order for the de-serialization.nested (bool) – if
True
allPointer
fields of a Sequence de-serialize their referenceddata
object as well (chained method call). EachPointer
field uses for the de-serialization of its referenceddata
object its ownbytestream
.
- 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 eachField
in the Sequence to the byte buffer in accordance with the encoding byte order for the serialization and the encodingbyte_order
of eachField
in the Sequence.A specific encoding
byte_order
of aField
overrules the encoding byte order for the serialization.Returns the
Index
of the buffer after the last serializedField
in the Sequence.Optional the serialization of the referenced
data
objects of allPointer
fields in the Sequence can be enabled.- Parameters
buffer (bytearray) – byte stream.
byte_order (
Byteorder
,str
) – encoding byte order for the serialization.nested (bool) – if
True
allPointer
fields of a Sequence serialize their referenceddata
object as well (chained method call). EachPointer
field uses for the serialization of its referenceddata
object its ownbytestream
.
- 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 lastField
in the Sequence.
- 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)
.
- initialize_fields(content)[source]#
Initializes the
Field
items in the Sequence with the values in the content list.
- 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 fieldvalue
.fieldnames (tuple) – sequence of dictionary keys for the selected field attributes. Defaults to
(*attributes)
.nested (bool) – if
True
allPointer
fields nested in the Sequence views their referenceddata
object field attributes as well (chained method call).
- field_items(path='', **options)[source]#
Returns a flatten list of
('field path', field item)
tuples for eachField
nested in the Sequence.
- describe(name='', **options)[source]#
Returns the metadata of the Sequence as a
dict
.metadata = { 'class': self.__class__.__name__, 'name': name if name else self.__class__.__name__, 'size': len(self), 'type': Sequence.item_type.name 'member': [ item.describe('name[idx]') for idx, item in enumerate(self) ] }
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 anyField
instance or a callable (factory) which returns aStructure
,Sequence
,Array
or anyField
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 aPointer
field instance directly as the array element template to ensure that the referenceddata
object of aPointer
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 themetadata
of aSequence
with its own item type.- Parameters
- 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.
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
- property bit_size#
Returns the size of the Field in bits (read-only).
- property name#
Returns the type name of the Field (read-only).
- property value#
Field value.
- abstract 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 thebyte_order
andalignment
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
Note
This abstract method must be implemented by a derived class.
- abstract 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 thebyte_order
andalignment
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 fieldvalue
.- Parameters
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 decodingbyte_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 aPointer
field can be enabled.- Parameters
buffer (bytes) – byte stream.
byte_order (
Byteorder
,str
) – decoding byte order for the de-serialization.nested (bool) – if
True
aPointer
field de-serialize its referenceddata
object as well (chained method call). EachPointer
field uses for the de-serialization of its referenceddata
object its ownbytestream
.
- 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 encodingbyte_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 aPointer
field can be enabled.- Parameters
buffer (bytearray) – byte stream.
byte_order (
Byteorder
,str
) – encoding byte order for the serialization.nested (bool) – if
True
aPointer
field serializes its referenceddata
object as well (chained method call). EachPointer
field uses for the encoding of its referenceddata
object its ownbytestream
.
- 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.
- describe(name='', **options)[source]#
Returns the metadata of a Field as a
dict
.metadata = { 'address': self.index.address, 'alignment': [self.alignment.byte_size, self.alignment.bit_offset], 'class': self.name, 'index': [self.index.byte, self.index.bit], 'name': name if name else self.name, 'order': self.byte_order.value, 'size': self.bit_size, 'type': Field.item_type.name, 'value': self.value }
Stream#
- class konfoo.Stream(size=0)[source]#
A Stream field is a
Field
with a variable size and returns its fieldvalue
as a hexadecimal string.Internally a Stream field uses a
bytes
class to store the data of its fieldvalue
.A Stream field is:
containable:
item
inself
returnsTrue
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 >>> stream[5:].hex() # converts to bytes '060708090a' >>> stream.describe() {'address': 0, 'alignment': [10, 0], 'class': 'Stream10', 'index': [0, 0], 'name': 'Stream10', 'order': 'auto', 'size': 80, 'type': 'Field', 'value': '0102030405060708090a'}
- property name#
Returns the type name of the Stream field (read-only).
- property 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.
- 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 thebyte_order
andalignment
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
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 thebyte_order
andalignment
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 fieldvalue
.- Parameters
Note
This abstract method must be implemented by a derived class.
String#
- class konfoo.String(size=0)[source]#
A String field is a
Stream
field with a variable size and returns its fieldvalue
as a zero-terminated ASCII string.A String field is:
containable:
item
inself
returnsTrue
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() {'address': 0, 'alignment': [10, 0], 'class': 'String10', 'index': [0, 0], 'name': 'String10', 'order': 'auto', 'size': 80, 'type': 'Field', 'value': 'KonFoo is '}
- property value#
Field value as an ascii encoded string.
Float#
- class konfoo.Float(byte_order='auto')[source]#
A Float field is a
Field
with a fix size of four bytes and returns its fieldvalue
as a single precision float.Internally a Float field uses a
float
class to store the data of its fieldvalue
.A Float field extends the
metadata
of aField
with a'max'
and'min'
key for its maximum and minimum possible fieldvalue
.- Parameters
byte_order (
Byteorder
,str
) – byte order used to unpack and pack thevalue
of the Float field.
Example:
>>> real = Float() >>> real.is_float() True >>> real.name 'Float32' >>> real.alignment Alignment(byte_size=4, bit_offset=0) >>> real.byte_order Byteorder.auto = 'auto' >>> real.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> real.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> real.bit_size 32 >>> real.min() -3.4028234663852886e+38 >>> real.max() 3.4028234663852886e+38 >>> real.smallest() 1.1754943508222875e-38 >>> real.epsilon() 5.960464477539063e-08 >>> real.value 0.0 >>> bytes(real) b'\x00\x00\x00\x00' >>> int(real) 0 >>> float(real) 0.0 >>> bool(real) False >>> real.value = 0x10 >>> real.value 16.0 >>> real.value = -3.4028234663852887e+38 >>> real.value -3.4028234663852886e+38 >>> real.value = 3.4028234663852887e+38 >>> real.value 3.4028234663852886e+38 >>> real.describe() {'address': 0, 'alignment': [4, 0], 'class': 'Float32', 'index': [0, 0], 'max': 3.4028234663852886e+38, 'min': -3.4028234663852886e+38, 'name': 'Float32', 'order': 'auto', 'size': 32, 'type': 'Field', 'value': 3.4028234663852886e+38}
- property value#
Field value as a single precision floating point number.
- 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 thebyte_order
andalignment
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
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 thebyte_order
andalignment
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 fieldvalue
.- Parameters
Note
This abstract method must be implemented by a derived class.
- describe(name='', **options)[source]#
Returns the metadata of a Field as a
dict
.metadata = { 'address': self.index.address, 'alignment': [self.alignment.byte_size, self.alignment.bit_offset], 'class': self.name, 'index': [self.index.byte, self.index.bit], 'name': name if name else self.name, 'order': self.byte_order.value, 'size': self.bit_size, 'type': Field.item_type.name, 'value': self.value }
Double#
- class konfoo.Double(byte_order='auto')[source]#
A Double field is a
Field
with a fix size of eight bytes and returns its fieldvalue
as a double precision float.Internally a Double field uses a
float
class to store the data of its fieldvalue
.A Double field extends the
metadata
of aField
with a'max'
and'min'
key for its maximum and minimum possible fieldvalue
.- Parameters
byte_order (
Byteorder
,str
) – byte order used to unpack and pack thevalue
of the Double field.
Example:
>>> double = Double() >>> double.is_float() True >>> double.name 'Double64' >>> double.alignment Alignment(byte_size=8, bit_offset=0) >>> double.byte_order Byteorder.auto = 'auto' >>> double.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> double.index_field() Index(byte=8, bit=0, address=8, base_address=0, update=False) >>> double.bit_size 64 >>> double.min() -1.7976931348623157e+308 >>> double.max() 1.7976931348623157e+308 >>> double.smallest() 2.2250738585072014e-308 >>> double.epsilon() 1.1102230246251565e-16 >>> double.value 0.0 >>> bytes(double) b'\x00\x00\x00\x00\x00\x00\x00\x00' >>> int(double) 0 >>> float(double) 0.0 >>> bool(double) False >>> double.value = 0x10 >>> double.value 16.0 >>> double.value = -1.7976931348623158e+308 >>> double.value -1.7976931348623157e+308 >>> double.value = 1.7976931348623158e+308 >>> double.value 1.7976931348623157e+308 >>> double.describe() {'address': 0, 'alignment': [8, 0], 'class': 'Double64', 'index': [0, 0], 'max': 1.7976931348623157e+308, 'min': -1.7976931348623157e+308, 'name': 'Double64', 'order': 'auto', 'size': 64, 'type': 'Field', 'value': 1.7976931348623157e+308}
- property value#
Field value as a double precision floating point number.
- 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 thebyte_order
andalignment
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
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 thebyte_order
andalignment
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 fieldvalue
.- Parameters
Note
This abstract method must be implemented by a derived class.
- describe(name='', **options)[source]#
Returns the metadata of a Field as a
dict
.metadata = { 'address': self.index.address, 'alignment': [self.alignment.byte_size, self.alignment.bit_offset], 'class': self.name, 'index': [self.index.byte, self.index.bit], 'name': name if name else self.name, 'order': self.byte_order.value, 'size': self.bit_size, 'type': Field.item_type.name, 'value': self.value }
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 fieldvalue
as a decimal number.Internally a Decimal field uses an
int
class to store the data of its fieldvalue
.A Decimal field extends the
metadata
of aField
with a'max'
and'min'
key for its maximum and minimum possible fieldvalue
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
and64
.align_to (int) – aligns the Decimal field to the number of bytes, can be between
1
and8
. 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 thevalue
of the Decimal field.
Example:
>>> unsigned = Decimal(16) >>> unsigned.is_decimal() True >>> unsigned.name 'Decimal16' >>> unsigned.alignment Alignment(byte_size=2, bit_offset=0) >>> unsigned.byte_order Byteorder.auto = 'auto' >>> unsigned.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> unsigned.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> unsigned.bit_size 16 >>> unsigned.signed False >>> unsigned.min() 0 >>> unsigned.max() 65535 >>> unsigned.value 0 >>> bytes(unsigned) b'\x00\x00' >>> int(unsigned) 0 >>> float(unsigned) 0.0 >>> hex(unsigned) '0x0' >>> bin(unsigned) '0b0' >>> oct(unsigned) '0o0' >>> bool(unsigned) False >>> unsigned.as_signed() 0 >>> unsigned.as_unsigned() 0 >>> unsigned.deserialize(bytes.fromhex('0080')) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> unsigned.value 32768 >>> unsigned.value = 0x4000 >>> unsigned.value 16384 >>> unsigned.value = -1 >>> unsigned.value 0 >>> unsigned.value = 65536 >>> unsigned.value 65535 >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> unsigned.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ffff' >>> unsigned.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Decimal16', 'index': [0, 0], 'max': 65535, 'min': 0, 'name': 'Decimal16', 'order': 'auto', 'signed': False, 'size': 16, 'type': 'Field', 'value': 65535}
Example:
>>> signed = Decimal(16, signed=True) >>> signed.is_decimal() True >>> signed.name 'Decimal16' >>> signed.alignment Alignment(byte_size=2, bit_offset=0) >>> signed.byte_order Byteorder.auto = 'auto' >>> signed.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> signed.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> signed.bit_size 16 >>> signed.signed True >>> signed.min() -32768 >>> signed.max() 32767 >>> signed.value 0 >>> bytes(signed) b'\x00\x00' >>> int(signed) 0 >>> float(signed) 0.0 >>> hex(signed) '0x0' >>> bin(signed) '0b0' >>> oct(signed) '0o0' >>> bool(signed) False >>> signed.deserialize(bytes.fromhex('00c0')) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> signed.value -16384 >>> signed.value = -0x4000 >>> signed.value -16384 >>> signed.value = -32769 >>> signed.value -32768 >>> signed.value = 32768 >>> signed.value 32767 >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> signed.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ff7f' >>> signed.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Decimal16', 'index': [0, 0], 'max': 32767, 'min': -32768, 'name': 'Decimal16', 'order': 'auto', 'signed': True, 'size': 16, 'type': 'Field', 'value': 32767}
- property value#
Field value as a decimal number.
- property signed#
Returns
True
if the Decimal field is signed.
- 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 thebyte_order
andalignment
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
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 thebyte_order
andalignment
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 fieldvalue
.- Parameters
Note
This abstract method must be implemented by a derived class.
- describe(name=None, **options)[source]#
Returns the metadata of a Field as a
dict
.metadata = { 'address': self.index.address, 'alignment': [self.alignment.byte_size, self.alignment.bit_offset], 'class': self.name, 'index': [self.index.byte, self.index.bit], 'name': name if name else self.name, 'order': self.byte_order.value, 'size': self.bit_size, 'type': Field.item_type.name, 'value': self.value }
- 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 fieldvalue
as an unsigned integer number.- Parameters
Example:
>>> bit = Bit(0) >>> bit.is_decimal() True >>> bit.is_bit() True >>> bit.name 'Bit' >>> bit.alignment Alignment(byte_size=1, bit_offset=0) >>> bit.byte_order Byteorder.auto = 'auto' >>> bit.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> bit.index_field() Index(byte=0, bit=1, address=0, base_address=0, update=False) >>> bit.bit_size 1 >>> bit.signed False >>> bit.min() 0 >>> bit.max() 1 >>> bit.value 0 >>> bit.signed False >>> bit.value 0 >>> bytes(bit) b'\x00' >>> int(bit) 0 >>> float(bit) 0.0 >>> hex(bit) '0x0' >>> bin(bit) '0b0' >>> oct(bit) '0o0' >>> bool(bit) False >>> bit.as_signed() 0 >>> bit.as_unsigned() 0 >>> bit.deserialize(bytes.fromhex('01')) Index(byte=0, bit=1, address=0, base_address=0, update=False) >>> bit.value 1 >>> bit.value = 0 >>> bit.value 0 >>> bit.value = False >>> bit.value 0 >>> bit.value = True >>> bit.value 1 >>> bit.value = -1 >>> bit.value 0 >>> bit.value = 2 >>> bit.value 1 >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> bit.serialize(bytestream) Index(byte=0, bit=1, address=0, base_address=0, update=False) >>> bytestream.hex() '01' >>> bit.describe() {'address': 0, 'alignment': [1, 0], 'class': 'Bit', 'index': [0, 0], 'max': 1, 'min': 0, 'name': 'Bit', 'order': 'auto', 'signed': False, 'size': 1, 'type': 'Field', 'value': 1}
- property name#
Returns the type name of the Bit field (read-only).
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 fieldvalue
as a lowercase hexadecimal string prefixed with0x
.- Parameters
align_to (int) – aligns the Byte field to the number of bytes, can be between
1
and8
. If no field alignment is set the Byte field aligns itself to the next matching byte size according to the size of the Byte field.
Example:
>>> byte = Byte() >>> byte.is_decimal() True >>> byte.name 'Byte' >>> byte.alignment Alignment(byte_size=1, bit_offset=0) >>> byte.byte_order Byteorder.auto = 'auto' >>> byte.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> byte.index_field() Index(byte=1, bit=0, address=1, base_address=0, update=False) >>> byte.bit_size 8 >>> byte.signed False >>> byte.min() 0 >>> byte.max() 255 >>> byte.value '0x0' >>> bytes(byte) b'\x00' >>> int(byte) 0 >>> float(byte) 0.0 >>> hex(byte) '0x0' >>> bin(byte) '0b0' >>> oct(byte) '0o0' >>> bool(byte) False >>> byte.as_signed() 0 >>> byte.as_unsigned() 0 >>> byte.deserialize(bytes.fromhex('20')) Index(byte=1, bit=0, address=1, base_address=0, update=False) >>> byte.value '0x20' >>> byte.value = 16 >>> byte.value '0x10' >>> byte.value = -1 >>> byte.value '0x0' >>> byte.value = 256 >>> byte.value '0xff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> byte.serialize(bytestream) Index(byte=1, bit=0, address=1, base_address=0, update=False) >>> bytestream.hex() 'ff' >>> byte.describe() {'address': 0, 'alignment': [1, 0], 'class': 'Byte', 'index': [0, 0], 'max': 255, 'min': 0, 'name': 'Byte', 'order': 'auto', 'signed': False, 'size': 8, 'type': 'Field', 'value': '0xff'}
- property name#
Returns the type name of the Byte field (read-only).
- property 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 fieldvalue
as an unicode string character.- Parameters
align_to (int) – aligns the Char field to the number of bytes, can be between
1
and8
. If no field alignment is set the Char field aligns itself to the next matching byte size according to the size of the Char field.
Example:
>>> char = Char() >>> char.is_decimal() True >>> char.name 'Char' >>> char.alignment Alignment(byte_size=1, bit_offset=0) >>> char.byte_order Byteorder.auto = 'auto' >>> char.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> char.index_field() Index(byte=1, bit=0, address=1, base_address=0, update=False) >>> char.bit_size 8 >>> char.signed False >>> char.min() 0 >>> char.max() 255 >>> char.value '\x00' >>> bytes(char) b'\x00' >>> ord(char.value) 0 >>> int(char) 0 >>> float(char) 0.0 >>> hex(char) '0x0' >>> bin(char) '0b0' >>> oct(char) '0o0' >>> bool(char) False >>> char.as_signed() 0 >>> char.as_unsigned() 0 >>> char.deserialize(bytes.fromhex('41')) Index(byte=1, bit=0, address=1, base_address=0, update=False) >>> char.value 'A' >>> char.value = 66 >>> char.value 'B' >>> char.value = 0x41 >>> char.value 'A' >>> char.value = 'F' >>> char.value 'F' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> char.serialize(bytestream) Index(byte=1, bit=0, address=1, base_address=0, update=False) >>> bytestream.hex() '46' >>> char.describe() {'address': 0, 'alignment': [1, 0], 'class': 'Char', 'index': [0, 0], 'max': 255, 'min': 0, 'name': 'Char', 'order': 'auto', 'signed': False, 'size': 8, 'type': 'Field', 'value': 'F'}
- property name#
Returns the type name of the Char field (read-only).
- property 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 fieldvalue
as a signed integer number.- Parameters
bit_size (int) – is the size of the Signed field in bits, can be between
1
and64
.align_to (int) – aligns the Signed field to the number of bytes, can be between
1
and8
. 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 thevalue
of the Signed field.
Example:
>>> signed = Signed(16) >>> signed.is_decimal() True >>> signed.name 'Signed16' >>> signed.alignment Alignment(byte_size=2, bit_offset=0) >>> signed.byte_order Byteorder.auto = 'auto' >>> signed.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> signed.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> signed.bit_size 16 >>> signed.signed True >>> signed.min() -32768 >>> signed.max() 32767 >>> signed.value 0 >>> bytes(signed) b'\x00\x00' >>> int(signed) 0 >>> float(signed) 0.0 >>> hex(signed) '0x0' >>> bin(signed) '0b0' >>> oct(signed) '0o0' >>> bool(signed) False >>> signed.as_signed() 0 >>> signed.as_unsigned() 0 >>> signed.deserialize(bytes.fromhex('00c0')) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> signed.value -16384 >>> signed.value = -0x4000 >>> signed.value -16384 >>> signed.value = -32769 >>> signed.value -32768 >>> signed.value = 32768 >>> signed.value 32767 >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> signed.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ff7f' >>> signed.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Signed16', 'index': [0, 0], 'max': 32767, 'min': -32768, 'name': 'Signed16', 'order': 'auto', 'signed': True, 'size': 16, 'type': 'Field', 'value': 32767}
- class konfoo.Signed8(byte_order='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.
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 fieldvalue
as a lowercase hexadecimal string prefixed with0x
.- Parameters
bit_size (int) – is the size of the Unsigned field in bits, can be between
1
and64
.align_to (int) – aligns the Unsigned field to the number of bytes, can be between
1
and8
. 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 thevalue
of the Unsigned field.
Example:
>>> unsigned = Unsigned(16) >>> unsigned.is_decimal() True >>> unsigned.name 'Unsigned16' >>> unsigned.alignment Alignment(byte_size=2, bit_offset=0) >>> unsigned.byte_order Byteorder.auto = 'auto' >>> unsigned.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> unsigned.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> unsigned.bit_size 16 >>> unsigned.signed False >>> unsigned.min() 0 >>> unsigned.max() 65535 >>> unsigned.value '0x0' >>> bytes(unsigned) b'\x00\x00' >>> int(unsigned) 0 >>> float(unsigned) 0.0 >>> hex(unsigned) '0x0' >>> bin(unsigned) '0b0' >>> oct(unsigned) '0o0' >>> bool(unsigned) False >>> unsigned.as_signed() 0 >>> unsigned.as_unsigned() 0 >>> unsigned.deserialize(bytes.fromhex('00c0')) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> unsigned.value '0xc000' >>> unsigned.value = 0x4000 >>> unsigned.value '0x4000' >>> unsigned.value = -0x1 >>> unsigned.value '0x0' >>> unsigned.value = 0x10000 >>> unsigned.value '0xffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> unsigned.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ffff' >>> unsigned.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Unsigned16', 'index': [0, 0], 'max': 65535, 'min': 0, 'name': 'Unsigned16', 'order': 'auto', 'signed': False, 'size': 16, 'type': 'Field', 'value': '0xffff'}
- property value#
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.
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 fieldvalue
as a binary string prefixed with0b
.- Parameters
bit_size (int) – is the size of the Bitset field in bits, can be between
1
and64
.align_to (int) – aligns the Bitset field to the number of bytes, can be between
1
and8
. 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 thevalue
of the Bitset field.
Example:
>>> bitset = Bitset(16) >>> bitset.is_decimal() True >>> bitset.name 'Bitset16' >>> bitset.alignment Alignment(byte_size=2, bit_offset=0) >>> bitset.byte_order Byteorder.auto = 'auto' >>> bitset.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> bitset.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bitset.bit_size 16 >>> bitset.signed False >>> bitset.min() 0 >>> bitset.max() 65535 >>> bitset.value '0b0000000000000000' >>> bytes(bitset) b'\x00\x00' >>> int(bitset) 0 >>> float(bitset) 0.0 >>> hex(bitset) '0x0' >>> bin(bitset) '0b0' >>> oct(bitset) '0o0' >>> bool(bitset) False >>> bitset.as_signed() 0 >>> bitset.as_unsigned() 0 >>> bitset.deserialize(bytes.fromhex('f00f')) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bitset.value '0b0000111111110000' >>> bitset.value = 0b1111 >>> bitset.value '0b0000000000001111' >>> bitset.value = -1 >>> bitset.value '0b0000000000000000' >>> bitset.value = 0x10000 >>> bitset.value '0b1111111111111111' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> bitset.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ffff' >>> bitset.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Bitset16', 'index': [0, 0], 'max': 65535, 'min': 0, 'name': 'Bitset16', 'order': 'auto', 'signed': False, 'size': 16, 'type': 'Field', 'value': '0b1111111111111111'}
- property value#
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.
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 fieldvalue
as a boolean value.- Parameters
bit_size (int) – is the size of the Bool field in bits, can be between
1
and64
.align_to (int) – aligns the Bool field to the number of bytes, can be between
1
and8
. 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 thevalue
of the Bool field.
Example:
>>> boolean = Bool(16) >>> boolean.is_decimal() True >>> boolean.is_bool() True >>> boolean.name 'Bool16' >>> boolean.alignment Alignment(byte_size=2, bit_offset=0) >>> boolean.byte_order Byteorder.auto = 'auto' >>> boolean.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> boolean.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> boolean.bit_size 16 >>> boolean.signed False >>> boolean.min() 0 >>> boolean.max() 65535 >>> boolean.value False >>> bytes(boolean) b'\x00\x00' >>> int(boolean) 0 >>> float(boolean) 0.0 >>> hex(boolean) '0x0' >>> bin(boolean) '0b0' >>> oct(boolean) '0o0' >>> bool(boolean) False >>> boolean.as_signed() 0 >>> boolean.as_unsigned() 0 >>> boolean.deserialize(bytes.fromhex('0f00')) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> boolean.value True >>> boolean.value = False >>> boolean.value False >>> boolean.value = -1 >>> boolean.value False >>> boolean.value = 0x10000 >>> boolean.value True >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> boolean.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ffff' >>> boolean.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Bool16', 'index': [0, 0], 'max': 65535, 'min': 0, 'name': 'Bool16', 'order': 'auto', 'signed': False, 'size': 16, 'type': 'Field', 'value': True}
- property value#
Field value as a boolean value,
True
orFalse
.
- 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.
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 fieldvalue
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
and64
.align_to (int) – aligns the Enum field to the number of bytes, can be between
1
and8
. 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 thevalue
of the Enum field.
Example:
>>> enum = Enum(16, enumeration=ItemClass) >>> enum.is_decimal() True >>> enum.name 'Enum16' >>> enum.alignment Alignment(byte_size=2, bit_offset=0) >>> enum.byte_order Byteorder.auto = 'auto' >>> enum.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> enum.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> enum.bit_size 16 >>> enum.signed False >>> bytes(enum) b'\x00\x00' >>> enum.min() 0 >>> enum.max() 65535 >>> enum.value 0 >>> int(enum) 0 >>> float(enum) 0.0 >>> hex(enum) '0x0' >>> bin(enum) '0b0' >>> oct(enum) '0o0' >>> bool(enum) False >>> enum.as_signed() 0 >>> enum.as_unsigned() 0 >>> enum.deserialize(bytes.fromhex('2800')) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> enum.value 'Decimal' >>> enum.value = 48 >>> enum.value 'Enum' >>> enum.value = 'Enum' >>> enum.value 'Enum' >>> enum.value = 40 >>> enum.value 'Decimal' >>> enum.value = -1 >>> enum.value 0 >>> enum.value = 65536 >>> enum.value 65535 >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> enum.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ffff' >>> enum.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Enum16', 'index': [0, 0], 'max': 65535, 'min': 0, 'name': 'Enum16', 'order': 'auto', 'signed': False, 'size': 16, 'type': 'Field', 'value': 65535}
- property value#
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 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.
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 fieldvalue
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 aDecimal
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
and64
.align_to (int) – aligns the Scaled field to the number of bytes, can be between
1
and8
. 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 thevalue
of the Scaled field.
Example:
>>> scaled = Scaled(100, 16) >>> scaled.is_decimal() True >>> scaled.name 'Scaled16' >>> scaled.alignment Alignment(byte_size=2, bit_offset=0) >>> scaled.byte_order Byteorder.auto = 'auto' >>> scaled.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> scaled.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> scaled.scale 100.0 >>> scaled.scaling_base() 16384.0 >>> scaled.bit_size 16 >>> scaled.signed True >>> scaled.min() -32768 >>> scaled.max() 32767 >>> scaled.value 0.0 >>> bytes(scaled) b'\x00\x00' >>> int(scaled) 0 >>> float(scaled) 0.0 >>> hex(scaled) '0x0' >>> bin(scaled) '0b0' >>> oct(scaled) '0o0' >>> bool(scaled) False >>> scaled.as_signed() 0 >>> scaled.as_unsigned() 0 >>> scaled.deserialize(bytes.fromhex('0040')) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> scaled.value 100.0 >>> scaled.value = -100 >>> scaled.value -100.0 >>> scaled.value = -200.001 >>> scaled.value -200.0 >>> scaled.value = 200 >>> scaled.value 199.993896484375 >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> scaled.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ff7f' >>> scaled.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Scaled16', 'index': [0, 0], 'max': 32767, 'min': -32768, 'name': 'Scaled16', 'order': 'auto', 'scale': 100.0, 'signed': True, 'size': 16, 'type': 'Field', 'value': 199.993896484375}
- property value#
Field value as a floating point number.
- property scale#
Scaling factor of the Scaled field.
- describe(name=None, **options)[source]#
Returns the metadata of a Field as a
dict
.metadata = { 'address': self.index.address, 'alignment': [self.alignment.byte_size, self.alignment.bit_offset], 'class': self.name, 'index': [self.index.byte, self.index.bit], 'name': name if name else self.name, 'order': self.byte_order.value, 'size': self.bit_size, 'type': Field.item_type.name, 'value': self.value }
- 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.
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 fieldvalue
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
and64
.align_to (int) – aligns the Fraction field to the number of bytes, can be between
1
and8
. 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 thevalue
of the Fraction field
Example:
>>> unipolar = Fraction(2, 16) >>> unipolar.is_decimal() True >>> unipolar.name 'Fraction2.16' >>> unipolar.alignment Alignment(byte_size=2, bit_offset=0) >>> unipolar.byte_order Byteorder.auto = 'auto' >>> unipolar.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> unipolar.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> unipolar.bit_size 16 >>> unipolar.signed False >>> unipolar.min() 0 >>> unipolar.max() 65535 >>> unipolar.value 0.0 >>> bytes(unipolar) b'\x00\x00' >>> int(unipolar) 0 >>> float(unipolar) 0.0 >>> hex(unipolar) '0x0' >>> bin(unipolar) '0b0' >>> oct(unipolar) '0o0' >>> bool(unipolar) False >>> unipolar.as_signed() 0 >>> unipolar.as_unsigned() 0 >>> unipolar.deserialize(bytes.fromhex('0080')) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> unipolar.value 200.0 >>> unipolar.value = 100 >>> unipolar.value 100.0 >>> unipolar.as_float(0x4000) 100.0 >>> unipolar.value = -1 >>> unipolar.value 0.0 >>> unipolar.value = 400 >>> unipolar.value 399.993896484375 >>> unipolar.as_float(0xffff) 399.993896484375 >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> unipolar.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ffff' >>> unipolar.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Fraction2.16', 'index': [0, 0], 'max': 65535, 'min': 0, 'name': 'Fraction2.16', 'order': 'auto', 'signed': False, 'size': 16, 'type': 'Field', 'value': 399.993896484375}
Example:
>>> bipolar = Fraction(2, 16, 2, True) >>> bipolar.is_decimal() True >>> bipolar.name 'Fraction2.16' >>> bipolar.alignment Alignment(byte_size=2, bit_offset=0) >>> bipolar.byte_order Byteorder.auto = 'auto' >>> bipolar.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> bipolar.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bipolar.bit_size 16 >>> bipolar.signed False >>> bipolar.min() 0 >>> bipolar.max() 65535 >>> bipolar.value 0.0 >>> bytes(bipolar) b'\x00\x00' >>> int(bipolar) 0 >>> float(bipolar) 0.0 >>> hex(bipolar) '0x0' >>> bin(bipolar) '0b0' >>> oct(bipolar) '0o0' >>> bool(bipolar) False >>> bipolar.as_signed() 0 >>> bipolar.as_unsigned() 0 >>> bipolar.deserialize(bytes.fromhex('0040')) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bipolar.value 100.0 >>> bipolar.value = -100 >>> bipolar.value -100.0 >>> bipolar.as_float(0xc000) -100.0 >>> bipolar.as_float(0x8000) -0.0 >>> bipolar.value = -200 >>> bipolar.value -199.993896484375 >>> bipolar.as_float(0xffff) -199.993896484375 >>> bipolar.value = 200 >>> bipolar.value 199.993896484375 >>> bipolar.as_float(0x7fff) 199.993896484375 >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> bipolar.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ff7f' >>> bipolar.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Fraction2.16', 'index': [0, 0], 'max': 65535, 'min': 0, 'name': 'Fraction2.16', 'order': 'auto', 'signed': True, 'size': 16, 'type': 'Field', 'value': 199.993896484375}
- property name#
Returns the type name of the Fraction field (read-only).
- property value#
Field value as a floating point number.
- describe(name=None, **options)[source]#
Returns the metadata of a Field as a
dict
.metadata = { 'address': self.index.address, 'alignment': [self.alignment.byte_size, self.alignment.bit_offset], 'class': self.name, 'index': [self.index.byte, self.index.bit], 'name': name if name else self.name, 'order': self.byte_order.value, 'size': self.bit_size, 'type': Field.item_type.name, 'value': self.value }
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 fieldvalue
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
and64
.align_to (int) – aligns the Bipolar field to the number of bytes, can be between
1
and8
. 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 thevalue
of the Bipolar field.
Example:
>>> bipolar = Bipolar(2, 16) >>> bipolar.is_decimal() True >>> bipolar.name 'Bipolar2.16' >>> bipolar.alignment Alignment(byte_size=2, bit_offset=0) >>> bipolar.byte_order Byteorder.auto = 'auto' >>> bipolar.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> bipolar.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bipolar.bit_size 16 >>> bipolar.signed False >>> bipolar.min() 0 >>> bipolar.max() 65535 >>> bipolar.value 0.0 >>> bytes(bipolar) b'\x00\x00' >>> int(bipolar) 0 >>> float(bipolar) 0.0 >>> hex(bipolar) '0x0' >>> bin(bipolar) '0b0' >>> oct(bipolar) '0o0' >>> bool(bipolar) False >>> bipolar.as_signed() 0 >>> bipolar.as_unsigned() 0 >>> bipolar.value = -100 >>> bipolar.value -100.0 >>> bipolar.as_float(0xc000) -100.0 >>> bipolar.as_float(0x8000) -0.0 >>> bipolar.value = -200 >>> bipolar.value -199.993896484375 >>> bipolar.as_float(0xffff) -199.993896484375 >>> bipolar.value = 200 >>> bipolar.value 199.993896484375 >>> bipolar.as_float(0x7fff) 199.993896484375 >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> bipolar.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ff7f' >>> bipolar.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Bipolar2.16', 'index': [0, 0], 'max': 65535, 'min': 0, 'name': 'Bipolar2.16', 'order': 'auto', 'signed': True, 'size': 16, 'type': 'Field', 'value': 199.993896484375}
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 fieldvalue
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
and64
.align_to (int) – aligns the Unipolar field to the number of bytes, can be between
1
and8
. 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 thevalue
of the Unipolar field.
Example:
>>> unipolar = Unipolar(2, 16) >>> unipolar.is_decimal() True >>> unipolar.name 'Unipolar2.16' >>> unipolar.alignment Alignment(byte_size=2, bit_offset=0) >>> unipolar.byte_order Byteorder.auto = 'auto' >>> unipolar.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> unipolar.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> unipolar.bit_size 16 >>> unipolar.signed False >>> unipolar.min() 0 >>> unipolar.max() 65535 >>> unipolar.value 0.0 >>> bytes(unipolar) b'\x00\x00' >>> int(unipolar) 0 >>> float(unipolar) 0.0 >>> hex(unipolar) '0x0' >>> bin(unipolar) '0b0' >>> oct(unipolar) '0o0' >>> bool(unipolar) False >>> unipolar.as_signed() 0 >>> unipolar.as_unsigned() 0 >>> unipolar.deserialize(bytes.fromhex('0080')) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> unipolar.value 200.0 >>> unipolar.value = 100 >>> unipolar.value 100.0 >>> unipolar.as_float(0x4000) 100.0 >>> unipolar.value = -1 >>> unipolar.value 0.0 >>> unipolar.value = 400 >>> unipolar.value 399.993896484375 >>> unipolar.as_float(0xffff) 399.993896484375 >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> unipolar.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ffff' >>> unipolar.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Unipolar2.16', 'index': [0, 0], 'max': 65535, 'min': 0, 'name': 'Unipolar2.16', 'order': 'auto', 'signed': False, 'size': 16, 'type': 'Field', 'value': 399.993896484375}
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 fieldvalue
as an UTC datetime string in the ISO formatYYYY-mm-dd HH:MM:SS
.- Parameters
byte_order (
Byteorder
,str
) – byte order used to unpack and pack thevalue
of the Datetime field.
Example:
>>> datetime = Datetime() >>> datetime.is_decimal() True >>> datetime.name 'Datetime32' >>> datetime.alignment Alignment(byte_size=4, bit_offset=0) >>> datetime.byte_order Byteorder.auto = 'auto' >>> datetime.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> datetime.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> datetime.bit_size 32 >>> datetime.signed False >>> datetime.min() 0 >>> datetime.max() 4294967295 >>> datetime.value '1970-01-01 00:00:00' >>> bytes(datetime) b'\x00\x00\x00\x00' >>> int(datetime) 0 >>> float(datetime) 0.0 >>> hex(datetime) '0x0' >>> bin(datetime) '0b0' >>> oct(datetime) '0o0' >>> bool(datetime) False >>> datetime.as_signed() 0 >>> datetime.as_unsigned() 0 >>> datetime.deserialize(bytes.fromhex('ffffffff')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> datetime.value '2106-02-07 06:28:15' >>> datetime.value = '1969-12-31 23:59:59' >>> datetime.value '1970-01-01 00:00:00' >>> datetime.value = '2106-02-07 06:28:16' >>> datetime.value '2106-02-07 06:28:15' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> datetime.serialize(bytestream) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> bytestream.hex() 'ffffffff' >>> datetime.describe() {'address': 0, 'alignment': [4, 0], 'class': 'Datetime32', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'Datetime32', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Field', 'value': '2106-02-07 06:28:15'}
- property value#
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 fieldvalue
as an IPv4 address formatted string.- Parameters
byte_order (
Byteorder
,str
) – byte order used to unpack and pack thevalue
of the IPv4Address field.
Example:
>>> ipv4 = IPv4Address() >>> ipv4.is_decimal() True >>> ipv4.name 'Ipaddress32' >>> ipv4.alignment Alignment(byte_size=4, bit_offset=0) >>> ipv4.byte_order Byteorder.auto = 'auto' >>> ipv4.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> ipv4.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> ipv4.bit_size 32 >>> ipv4.signed False >>> ipv4.min() 0 >>> ipv4.max() 4294967295 >>> ipv4.value '0.0.0.0' >>> bytes(ipv4) b'\x00\x00\x00\x00' >>> int(ipv4) 0 >>> float(ipv4) 0.0 >>> hex(ipv4) '0x0' >>> bin(ipv4) '0b0' >>> oct(ipv4) '0o0' >>> bool(ipv4) False >>> ipv4.as_signed() 0 >>> ipv4.as_unsigned() 0 >>> ipv4.deserialize(bytes.fromhex('ffffffff')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> ipv4.value '255.255.255.255' >>> ipv4.value = '192.168.0.0' >>> ipv4.value '192.168.0.0' >>> ipv4.value = '255.255.255.255' >>> ipv4.value '255.255.255.255' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> ipv4.serialize(bytestream) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> bytestream.hex() 'ffffffff' >>> ipv4.describe() {'address': 0, 'alignment': [4, 0], 'class': 'Ipaddress32', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'Ipaddress32', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Field', 'value': '255.255.255.255'}
- property value#
Field value as an IPv4 address formatted string.
Pointer#
- class konfoo.Pointer(template=None, address=None, data_order=Byteorder.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 fieldvalue
as a hexadecimal string.A Pointer field refers absolutely to a
data
object of a dataProvider
.The Pointer class extends the
Decimal
field with theContainer
interface for its referenceddata
object.A Pointer field has additional features to read, write, deserialize, serialize and view binary data:
Deserialize the
value
for eachField
in thedata
object referenced by the Pointer field from a byte stream viadeserialize_data()
.Serialize the
value
for eachField
in thedata
object referenced by the Pointer field to a byte stream viaserialize_data()
.Indexes each
Field
in thedata
object referenced by the Pointer field viaindex_data()
.Read from a
Provider
the necessary bytes for thedata
object referenced by the Pointer field viaread_from()
.Write to a
Provider
the necessary bytes for thedata
object referenced by the Pointer field viawrite_to()
.Get the accumulated size of all fields in the
data
object referenced by the Pointer field viadata_size
.Indexes the Pointer field and each
Field
in thedata
object referenced by the Pointer field viaindex_fields()
.View the selected attributes of the Pointer field and for each
Field
in thedata
object referenced by the Pointer field viaview_fields()
.List the path to the field and the field item for the Pointer field and for each
Field
in thedata
object referenced by the Pointer field as a flatten list viafield_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 thedata
object referenced by the Pointer field.bit_size (int) – is the size of the Pointer field in bits, can be between
1
and64
.align_to (int) – aligns the Pointer field to the number of bytes, can be between
1
and8
. 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 thevalue
of the Pointer field.
Example:
>>> pointer = Pointer() >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data >>> pointer.data_size 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.initialize_fields({'value': 0x8000}) >>> pointer.value '0x8000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> pointer.serialize(bytestream) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> bytestream.hex() 'ffffffff' >>> pointer.bytestream = b'KonFoo is Fun' >>> pointer.bytestream '4b6f6e466f6f2069732046756e' >>> pointer.serialize_data() b'' >>> pointer.deserialize_data() Index(byte=0, bit=0, address=4294967295, base_address=4294967295, update=False) >>> pointer.serialize_data() b'' >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'Pointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'Pointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff'} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': None} >>> pointer.to_json() '{"value": "0xffffffff", "data": null}' >>> pointer.field_items() [('field', Pointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff'))] >>> pointer.to_list() [('Pointer.field', '0xffffffff')] >>> pointer.to_dict() {'Pointer': {'field': '0xffffffff'}}
- property address#
Returns the data source address of the
data
object referenced by the Pointer field (read-only).
- property base_address#
Returns the data source base address of the
data
object referenced by the Pointer field (read-only).
- property bytestream#
Byte stream of the Pointer field for the referenced
data
object. Returned as a lowercase hexadecimal encoded string.
- property data#
Data object referenced by the Pointer field.
- property data_byte_order#
Byteorder
used to deserialize and serialize thedata
object referenced by the Pointer field.
- property value#
Field value as a lowercase hexadecimal string prefixed with
0x
.
- 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 thevalue
for eachField
in thedata
object in accordance with the decoding byte order for the de-serialization and the decodingbyte_order
of eachField
in thedata
object.A specific decoding
byte_order
of aField
in thedata
object overrules the decoding byte order for the de-serialization.Returns the
Index
of the buffer after the last de-serializedField
in thedata
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 thedata_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 thevalue
for eachField
in thedata
object to a number of bytes in accordance with the encoding byte order for the serialization and the encodingbyte_order
of eachField
in thedata
object.A specific encoding
byte_order
of aField
in thedata
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 thedata_byte_order
of the Pointer field.
- read_from(provider, null_allowed=False, **options)[source]#
Reads from the data
Provider
the necessary number of bytes for thedata
object referenced by the Pointer field.A Pointer field stores the binary data read from the data
Provider
in itsbytestream
.- Parameters
null_allowed (bool) – if
True
read access of address zero (Null) is allowed.nested (bool) – if
True
allPointer
fields in thedata
object of the Pointer field reads their referenceddata
object fields as well (chained method call). Each Pointer field stores the bytes for its referenceddata
object in itsbytestream
.
- patch(item, byte_order=Byteorder.little)[source]#
Returns a memory
Patch
for the given item that shall be patched in the data source.
- write_to(provider, item, byte_order=Byteorder.little)[source]#
Writes via a data
Provider
theField
values of the given item to the data source.
- 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 decodingbyte_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.
byte_order (
Byteorder
,str
) – decoding byte order for the de-serialization.nested (bool) – if
True
a Pointer field de-serialize its referenceddata
object as well (chained method call). EachPointer
field uses for the de-serialization of its referenceddata
object its ownbytestream
.
- 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 encodingbyte_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.
byte_order (
Byteorder
,str
) – encoding byte order for the serialization.nested (bool) – if
True
a Pointer field serializes its referenceddata
object as well (chained method call). EachPointer
field uses for the serialization of its referenceddata
object its ownbytestream
.
- initialize_fields(content)[source]#
Initializes the Pointer field itself and the
Field
items in thedata
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 thedata
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 theIndex
after the Pointer field.
- view_fields(*attributes, **options)[source]#
Returns a
dict
which contains the selected field attributes of the Pointer field itself extended with a['data']
key which contains the selected field attribute or the dictionaries of the selected field attributes for eachField
nested in thedata
object referenced by the Pointer field.The attributes of each
Field
for containers nested in thedata
object referenced by the Pointer field are viewed as well (chained method call).- Parameters
attributes (str) – selected
Field
attributes. Fallback is the fieldvalue
.fieldnames (tuple) – sequence of dictionary keys for the selected field attributes. Defaults to
(*attributes)
.nested (bool) – if
True
allPointer
fields in thedata
object referenced by the Pointer field views their referenceddata
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 eachField
nested in thedata
object referenced by the Pointer field.
- describe(name='', **options)[source]#
Returns the metadata of a Pointer as a
dict
.metadata = { 'address': self.index.address, 'alignment': [self.alignment.byte_size, self.alignment.bit_offset], 'class': self.__class__.__name__, 'index': [self.index.byte, self.index.bit], 'max': self.max(), 'min': self.min(), 'name': name if name else self.__class__.__name__, 'order': self.byte_order.value, 'size': self.bit_size, 'type': Pointer.item_type.name, 'value': self.value, 'member': [self.data.describe()] }
- class konfoo.Pointer8(template=None, address=None, data_order=Byteorder.little)[source]#
A Pointer8 field is a
Pointer
field with aField
size of one byte.
- class konfoo.Pointer16(template=None, address=None, data_order=Byteorder.little, field_order='auto')[source]#
A Pointer16 field is a
Pointer
field with aField
size of two bytes.
- class konfoo.Pointer24(template=None, address=None, data_order=Byteorder.little, field_order='auto')[source]#
A Pointer24 field is a
Pointer
field with aField
size of three bytes.
- class konfoo.Pointer32(template=None, address=None, data_order=Byteorder.little, field_order='auto')[source]#
A Pointer32 field is a
Pointer
field with aField
size of four bytes.
- class konfoo.Pointer48(template=None, address=None, data_order=Byteorder.little, field_order='auto')[source]#
A Pointer48 field is a
Pointer
field with aField
size of six bytes.
- class konfoo.Pointer64(template=None, address=None, data_order=Byteorder.little, field_order='auto')[source]#
A Pointer64 field is a
Pointer
field with aField
size of eight bytes.
Structure Pointer#
- class konfoo.StructurePointer(template=None, address=None, data_order=Byteorder.little, bit_size=32, align_to=None, field_order='auto')[source]#
A StructurePointer field is a
Pointer
which refers to aStructure
.- Parameters
template – template for the
data
object referenced by the Pointer field. The template must be aStructure
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 thedata
object referenced by the Pointer field.bit_size (int) – is the size of the Pointer field in bits, can be between
1
and64
.align_to (int) – aligns the Pointer field to the number of bytes, can be between
1
and8
. 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 thevalue
of the Pointer field.
Example:
>>> pointer = StructurePointer() >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data {} >>> pointer.data_size 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> len(pointer) 0 >>> [name for name in pointer.keys()] [] >>> [member.value for member in pointer.values()] [] >>> [(name, member.value) for name, member in pointer.items()] [] >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'StructurePointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'StructurePointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'class': 'Structure', 'name': 'data', 'size': 0, 'type': 'Structure', 'member': []} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': {}} >>> pointer.to_json() '{"value": "0xffffffff", "data": {}}' >>> pointer.field_items() [('field', StructurePointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff'))] >>> pointer.to_list(nested=True) [('StructurePointer.field', '0xffffffff')] >>> pointer.to_dict(nested=True) {'StructurePointer': {'field': '0xffffffff'}}
- class konfoo.StructurePointer8(template=None, address=None, data_order=Byteorder.little)[source]#
A StructurePointer8 field is a
StructurePointer
field with aField
size of one byte.
- class konfoo.StructurePointer16(template=None, address=None, data_order=Byteorder.little, field_order='auto')[source]#
A StructurePointer16 field is a
StructurePointer
field with aField
size of two bytes.
- class konfoo.StructurePointer24(template=None, address=None, data_order=Byteorder.little, field_order='auto')[source]#
A StructurePointer24 field is a
StructurePointer
field with aField
size of three bytes.
- class konfoo.StructurePointer32(template=None, address=None, data_order=Byteorder.little, field_order='auto')[source]#
A StructurePointer32 field is a
StructurePointer
field with aField
size of four bytes.
- class konfoo.StructurePointer48(template=None, address=None, data_order=Byteorder.little, field_order='auto')[source]#
A StructurePointer48 field is a
StructurePointer
field with aField
size of six bytes.
- class konfoo.StructurePointer64(template=None, address=None, data_order=Byteorder.little, field_order='auto')[source]#
A StructurePointer64 field is a
StructurePointer
field with aField
size of eight bytes.
Sequence Pointer#
- class konfoo.SequencePointer(iterable=None, address=None, data_order=Byteorder.little, bit_size=32, align_to=None, field_order='auto')[source]#
A SequencePointer field is a
Pointer
field which refers to aSequence
.A SequencePointer field is:
containable:
item
inself
returnsTrue
if item is part of the referencedSequence
.sized:
len(self)
returns the number of items in the referencedSequence
.indexable
self[index]
returns the item at the index of the referencedSequence
.iterable
iter(self)
iterates over the items of the referencedSequence
A SequencePointer field supports the usual methods for sequences:
Insert an item before the index into the referenced
Sequence
viainsert()
.Pop an item with the index from the referenced
Sequence
viapop()
.Remove the first occurrence of an item from the referenced
Sequence
viaremove()
.
- Parameters
iterable – any iterable that contains items of
Structure
,Sequence
,Array
orField
instances. If the iterable is one of these instances itself then the iterable itself is appended to theSequence
.address (int) – absolute address of the
data
object referenced by the Pointer field.data_order (
Byteorder
,str
) – byte order used to unpack and pack thedata
object referenced by the Pointer field.bit_size (int) – is the size of the Pointer field in bits, can be between
1
and64
.align_to (int) – aligns the Pointer field to the number of bytes, can be between
1
and8
. 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 thevalue
of the Pointer field.
Example:
>>> pointer = SequencePointer() >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data [] >>> pointer.data_size 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer).hex() '00000000' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> len(pointer) 0 >>> [item for item in pointer] [] >>> pointer[:] [] >>> pointer.append(Field()) >>> pointer[0] Field(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=0, bit_offset=0), bit_size=0, value=None) >>> len(pointer) 1 >>> pointer.pop() Field(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=0, bit_offset=0), bit_size=0, value=None) >>> pointer.insert(0, Field()) >>> pointer.data [Field(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=0, bit_offset=0), bit_size=0, value=None)] >>> pointer.remove(pointer[0]) >>> pointer.data [] >>> pointer.clear() >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'SequencePointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'SequencePointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'class': 'Sequence', 'name': 'data', 'size': 0, 'type': 'Sequence', 'member': []} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': []} >>> pointer.to_json() '{"value": "0xffffffff", "data": []}' >>> pointer.field_items() [('field', SequencePointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff'))] >>> pointer.to_list(nested=True) [('SequencePointer.field', '0xffffffff')] >>> pointer.to_dict(nested=True) {'SequencePointer': {'field': '0xffffffff'}}
Array Pointer#
- class konfoo.ArrayPointer(template, size=0, address=None, data_order=Byteorder.little, bit_size=32, align_to=None, field_order='auto')[source]#
An ArrayPointer field is a
SequencePointer
field which refers to aArray
.An ArrayPointer field adapts and extends a
SequencePointer
field with the following features:Append a new
Array
element to the referencedArray
viaappend()
.Insert a new
Array
element before the index into the referencedArray
viainsert()
.
- Parameters
template – template for the
Array
element. The template can be anyField
instance or any callable that returns aStructure
,Sequence
,Array
or anyField
instance.size (int) – is the size of the
Array
in number ofArray
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 thedata
object referenced by the Pointer field.bit_size (int) – is the size of the Pointer field in bits, can be between
1
and64
.align_to (int) – aligns the Pointer field to the number of bytes, can be between
1
and8
. 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 thevalue
of the Pointer field.
Example:
>>> pointer = ArrayPointer(Byte) >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data [] >>> pointer.data_size 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> len(pointer) 0 >>> [item for item in pointer] [] >>> pointer[:] [] >>> pointer.append() >>> pointer[0] Byte(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=1, bit_offset=0), bit_size=8, value='0x0') >>> len(pointer) 1 >>> pointer.pop() Byte(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=1, bit_offset=0), bit_size=8, value='0x0') >>> pointer.insert(0) >>> pointer.data [Byte(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=1, bit_offset=0), bit_size=8, value='0x0')] >>> pointer.remove(pointer[0]) >>> pointer.data [] >>> pointer.resize(10) >>> len(pointer) 10 >>> pointer.clear() >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'ArrayPointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'ArrayPointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'class': 'Array', 'name': 'data', 'size': 0, 'type': 'Array', 'member': []} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': []} >>> pointer.to_json() '{"value": "0xffffffff", "data": []}' >>> pointer.field_items() [('field', ArrayPointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff'))] >>> pointer.to_list(nested=True) [('ArrayPointer.field', '0xffffffff')] >>> pointer.to_dict(nested=True) {'ArrayPointer': {'field': '0xffffffff'}}
- class konfoo.ArrayPointer8(template, address=None, data_order=Byteorder.little)[source]#
An ArrayPointer8 field is an
ArrayPointer
field with aField
size of one byte.
- class konfoo.ArrayPointer16(template, address=None, data_order=Byteorder.little, field_order='auto')[source]#
An ArrayPointer16 field is an
ArrayPointer
field with aField
size of two bytes.
- class konfoo.ArrayPointer24(template, address=None, data_order=Byteorder.little, field_order='auto')[source]#
An ArrayPointer24 field is an
ArrayPointer
field with aField
size of three bytes.
- class konfoo.ArrayPointer32(template, address=None, data_order=Byteorder.little, field_order='auto')[source]#
An ArrayPointer32 field is an
ArrayPointer
field with aField
size of four bytes.
- class konfoo.ArrayPointer48(template, address=None, data_order=Byteorder.little, field_order='auto')[source]#
An ArrayPointer48 field is an
ArrayPointer
field with aField
size of six bytes.
- class konfoo.ArrayPointer64(template, address=None, data_order=Byteorder.little, field_order='auto')[source]#
An ArrayPointer64 field is an
ArrayPointer
field with aField
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 aStream
field.A StreamPointer field is:
containable:
item
inself
returnsTrue
if item is part of the referencedStream
field.sized:
len(self)
returns the length of the referencedStream
field.indexable
self[index]
returns the byte at the index of the referencedStream
field.iterable
iter(self)
iterates over the bytes of the referencedStream
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
and64
.align_to (int) – aligns the Pointer field to the number of bytes, can be between
1
and8
. 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 thevalue
of the Pointer field.
Example:
>>> pointer = StreamPointer() >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data Stream(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=0, bit_offset=0), bit_size=0, value='') >>> pointer.data_size 0 >>> len(pointer) 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> pointer.serialize(bytestream) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> bytestream.hex() 'ffffffff' >>> pointer.resize(10) >>> pointer.data_size 10 >>> len(pointer) 10 >>> pointer.bytestream = b'KonFoo is Fun' >>> pointer.bytestream '4b6f6e466f6f2069732046756e' >>> pointer.serialize_data().hex() '00000000000000000000' >>> pointer.deserialize_data() Index(byte=10, bit=0, address=4294967305, base_address=4294967295, update=False) >>> pointer.serialize_data() b'KonFoo is ' >>> [byte for byte in pointer] # converts to int [75, 111, 110, 70, 111, 111, 32, 105, 115, 32] >>> [hex(byte) for byte in pointer] ['0x4b', '0x6f', '0x6e', '0x46', '0x6f', '0x6f', '0x20', '0x69', '0x73', '0x20'] >>> pointer[5] # converts to int 111 >>> 111 in pointer True >>> 0x0 in pointer False >>> pointer[:6] # converts to bytes b'KonFoo' >>> pointer[3:6] # converts to bytes b'Foo' >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'StreamPointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'StreamPointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'address': 4294967295, 'alignment': [10, 0], 'class': 'Stream10', 'index': [0, 0], 'name': 'data', 'order': 'auto', 'size': 80, 'type': 'Field', 'value': '4b6f6e466f6f20697320'} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': '4b6f6e466f6f20697320'} >>> pointer.to_json() '{"value": "0xffffffff", "data": "4b6f6e466f6f20697320"}' >>> pointer.field_items() [('field', StreamPointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff')), ('data', Stream(index=Index(byte=0, bit=0, address=4294967295, base_address=4294967295, update=False), alignment=Alignment(byte_size=10, bit_offset=0), bit_size=80, value='4b6f6e466f6f20697320'))] >>> pointer.to_list() [('StreamPointer.field', '0xffffffff'), ('StreamPointer.data', '4b6f6e466f6f20697320')] >>> pointer.to_dict() {'StreamPointer': {'field': '0xffffffff', 'data': '4b6f6e466f6f20697320'}}
- class konfoo.StreamPointer8(size=0, address=None)[source]#
A StreamPointer8 field is a
StreamPointer
field with aField
size of one byte.
- class konfoo.StreamPointer16(size=0, address=None, field_order='auto')[source]#
A StreamPointer16 field is a
StreamPointer
field with aField
size of two bytes.
- class konfoo.StreamPointer24(size=0, address=None, field_order='auto')[source]#
A StreamPointer24 field is a
StreamPointer
field with aField
size of three bytes.
- class konfoo.StreamPointer32(size=0, address=None, field_order='auto')[source]#
A StreamPointer32 field is a
StreamPointer
field with aField
size of four bytes.
- class konfoo.StreamPointer48(size=0, address=None, field_order='auto')[source]#
A StreamPointer48 field is a
StreamPointer
field with aField
size of six bytes.
- class konfoo.StreamPointer64(size=0, address=None, field_order='auto')[source]#
A StreamPointer64 field is a
StreamPointer
field with aField
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 aString
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
and64
.align_to (int) – aligns the Pointer field to the number of bytes, can be between
1
and8
. 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 thevalue
of the Pointer field.
Example:
>>> pointer = StringPointer() >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data String(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=0, bit_offset=0), bit_size=0, value='') >>> pointer.data_size 0 >>> len(pointer) 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> pointer.serialize(bytestream) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> bytestream.hex() 'ffffffff' >>> pointer.resize(10) >>> pointer.data_size 10 >>> len(pointer) 10 >>> pointer.bytestream = b'KonFoo is Fun' >>> pointer.bytestream '4b6f6e466f6f2069732046756e' >>> pointer.serialize_data().hex() '00000000000000000000' >>> pointer.deserialize_data() Index(byte=10, bit=0, address=4294967305, base_address=4294967295, update=False) >>> pointer.serialize_data() b'KonFoo is ' >>> [byte for byte in pointer] # converts to int [75, 111, 110, 70, 111, 111, 32, 105, 115, 32] >>> [chr(byte) for byte in pointer] # converts to int ['K', 'o', 'n', 'F', 'o', 'o', ' ', 'i', 's', ' '] >>> chr(pointer[5]) # converts to int -> chr 'o' >>> ord(' ') in pointer True >>> 0x0 in pointer False >>> pointer[:6] # converts to bytes b'KonFoo' >>> pointer[3:6] # converts to bytes b'Foo' >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'StringPointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'StringPointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'address': 4294967295, 'alignment': [10, 0], 'class': 'String10', 'index': [0, 0], 'name': 'data', 'order': 'auto', 'size': 80, 'type': 'Field', 'value': 'KonFoo is '} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': 'KonFoo is '} >>> pointer.to_json() '{"value": "0xffffffff", "data": "KonFoo is "}' >>> pointer.field_items() [('field', StringPointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff')), ('data', String(index=Index(byte=0, bit=0, address=4294967295, base_address=4294967295, update=False), alignment=Alignment(byte_size=10, bit_offset=0), bit_size=80, value='KonFoo is '))] >>> pointer.to_list() [('StringPointer.field', '0xffffffff'), ('StringPointer.data', 'KonFoo is ')] >>> pointer.to_dict() {'StringPointer': {'field': '0xffffffff', 'data': 'KonFoo is '}}
- class konfoo.StringPointer8(size=0, address=None)[source]#
A StringPointer8 field is a
StringPointer
field with aField
size of one byte.
- class konfoo.StringPointer16(size=0, address=None, field_order='auto')[source]#
A StringPointer16 field is a
StringPointer
field with aField
size of two bytes.
- class konfoo.StringPointer24(size=0, address=None, field_order='auto')[source]#
A StringPointer24 field is a
StringPointer
field with aField
size of three bytes.
- class konfoo.StringPointer32(size=0, address=None, field_order='auto')[source]#
A StringPointer32 field is a
StringPointer
field with aField
size of four bytes.
- class konfoo.StringPointer48(size=0, address=None, field_order='auto')[source]#
A StringPointer48 field is a
StringPointer
field with aField
size of six bytes.
- class konfoo.StringPointer64(size=0, address=None, field_order='auto')[source]#
A StringPointer64 field is a
StringPointer
field with aField
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-sizedString
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
and64
.align_to (int) – aligns the Pointer field to the number of bytes, can be between
1
and8
. 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 thevalue
of the Pointer field.
Example:
>>> pointer = AutoStringPointer() >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data String(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=64, bit_offset=0), bit_size=512, value='') >>> pointer.data_size 64 >>> len(pointer) 64 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> pointer.serialize(bytestream) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> bytestream.hex() 'ffffffff' >>> pointer.resize(10) >>> pointer.data_size 10 >>> len(pointer) 10 >>> pointer.bytestream = b'KonFoo is Fun' >>> pointer.bytestream '4b6f6e466f6f2069732046756e' >>> pointer.serialize_data().hex() '00000000000000000000' >>> pointer.deserialize_data() Index(byte=10, bit=0, address=4294967305, base_address=4294967295, update=False) >>> pointer.serialize_data() b'KonFoo is ' >>> [byte for byte in pointer] # converts to int [75, 111, 110, 70, 111, 111, 32, 105, 115, 32] >>> [chr(byte) for byte in pointer] # converts to int ['K', 'o', 'n', 'F', 'o', 'o', ' ', 'i', 's', ' '] >>> chr(pointer[5]) # converts to int -> chr 'o' >>> ord(' ') in pointer True >>> 0x0 in pointer False >>> pointer[:6] # converts to bytes b'KonFoo' >>> pointer[3:6] # converts to bytes b'Foo' >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'AutoStringPointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'AutoStringPointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'address': 4294967295, 'alignment': [10, 0], 'class': 'String10', 'index': [0, 0], 'name': 'data', 'order': 'auto', 'size': 80, 'type': 'Field', 'value': 'KonFoo is '} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': 'KonFoo is '} >>> pointer.to_json() '{"value": "0xffffffff", "data": "KonFoo is "}' >>> pointer.field_items() [('field', AutoStringPointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff')), ('data', String(index=Index(byte=0, bit=0, address=4294967295, base_address=4294967295, update=False), alignment=Alignment(byte_size=10, bit_offset=0), bit_size=80, value='KonFoo is '))] >>> pointer.to_list() [('AutoStringPointer.field', '0xffffffff'), ('AutoStringPointer.data', 'KonFoo is ')] >>> pointer.to_dict() {'AutoStringPointer': {'field': '0xffffffff', 'data': 'KonFoo is '}}
- read_from(provider, null_allowed=False, **options)[source]#
Reads from the data
Provider
the necessary number of bytes for thedata
object referenced by the Pointer field.A Pointer field stores the binary data read from the data
Provider
in itsbytestream
.- Parameters
null_allowed (bool) – if
True
read access of address zero (Null) is allowed.nested (bool) – if
True
allPointer
fields in thedata
object of the Pointer field reads their referenceddata
object fields as well (chained method call). Each Pointer field stores the bytes for its referenceddata
object in itsbytestream
.
Relative Pointer#
- class konfoo.RelativePointer(template=None, address=None, data_order=Byteorder.little, bit_size=32, align_to=None, field_order='auto')[source]#
A RelativePointer field is a
Pointer
field which references itsdata
object relative to a base address in the data source.Important
The
base_address
of a RelativePointer is defined by the fieldindex
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 thedata
object referenced by the RelativePointer field.bit_size (int) – is the size of the RelativePointer field in bits, can be between
1
and64
.align_to (int) – aligns the RelativePointer field to the number of bytes, can be between
1
and8
. 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 thevalue
of the RelativePointer field.
Example:
>>> pointer = RelativePointer() >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data >>> pointer.data_size 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> pointer.serialize(bytestream) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> bytestream.hex() 'ffffffff' >>> pointer.bytestream = b'KonFoo is Fun' >>> pointer.bytestream '4b6f6e466f6f2069732046756e' >>> pointer.serialize_data() b'' >>> pointer.deserialize_data() Index(byte=0, bit=0, address=4294967295, base_address=0, update=False) >>> pointer.serialize_data() b'' >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'RelativePointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'RelativePointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff'} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': None} >>> pointer.to_json() '{"value": "0xffffffff", "data": null}' >>> pointer.field_items() [('field', RelativePointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff'))] >>> pointer.to_list() [('RelativePointer.field', '0xffffffff')] >>> pointer.to_dict() {'RelativePointer': {'field': '0xffffffff'}}
- property address#
Returns the data source address of the
data
object referenced by the RelativePointer field (read-only).
- property 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)[source]#
A RelativePointer8 field is a
RelativePointer
field with aField
size of one byte.
- class konfoo.RelativePointer16(template=None, address=None, data_order=Byteorder.little, field_order='auto')[source]#
A RelativePointer16 field is a
RelativePointer
field with aField
size of two bytes.
- class konfoo.RelativePointer24(template=None, address=None, data_order=Byteorder.little, field_order='auto')[source]#
A RelativePointer24 field is a
RelativePointer
field with aField
size of three bytes.
- class konfoo.RelativePointer32(template=None, address=None, data_order=Byteorder.little, field_order='auto')[source]#
A RelativePointer32 field is a
RelativePointer
field with aField
size of four bytes.
- class konfoo.RelativePointer48(template=None, address=None, data_order=Byteorder.little, field_order='auto')[source]#
A RelativePointer48 field is a
RelativePointer
field with aField
size of six bytes.
- class konfoo.RelativePointer64(template=None, address=None, data_order=Byteorder.little, field_order='auto')[source]#
A RelativePointer64 field is a
RelativePointer
field with aField
size of eight bytes.
Structure Relative Pointer#
- class konfoo.StructureRelativePointer(template=None, address=None, data_order=Byteorder.little, bit_size=32, align_to=None, field_order='auto')[source]#
A StructureRelativePointer field is a
RelativePointer
which refers to aStructure
.- Parameters
template – template for the
data
object referenced by the RelativePointer field. The template must be aStructure
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 thedata
object referenced by the RelativePointer field.bit_size (int) – is the size of the RelativePointer field in bits, can be between
1
and64
.align_to (int) – aligns the RelativePointer field to the number of bytes, can be between
1
and8
. 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 thevalue
of the RelativePointer field.
Example:
>>> pointer = StructureRelativePointer() >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data {} >>> pointer.data_size 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> len(pointer) 0 >>> [name for name in pointer.keys()] [] >>> [member.value for member in pointer.values()] [] >>> [(name, member.value) for name, member in pointer.items()] [] >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'StructureRelativePointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'StructureRelativePointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'class': 'Structure', 'name': 'data', 'size': 0, 'type': 'Structure', 'member': []} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': {}} >>> pointer.to_json() '{"value": "0xffffffff", "data": {}}' >>> pointer.field_items() [('field', StructureRelativePointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff'))] >>> pointer.to_list(nested=True) [('StructureRelativePointer.field', '0xffffffff')] >>> pointer.to_dict(nested=True) {'StructureRelativePointer': {'field': '0xffffffff'}}
- class konfoo.StructureRelativePointer8(template=None, address=None, data_order=Byteorder.little)[source]#
A StructureRelativePointer8 field is a
StructureRelativePointer
field with aField
size of one byte.
- class konfoo.StructureRelativePointer16(template=None, address=None, data_order=Byteorder.little, field_order='auto')[source]#
A StructureRelativePointer16 field is a
StructureRelativePointer
field with aField
size of two bytes.
- class konfoo.StructureRelativePointer24(template=None, address=None, data_order=Byteorder.little, field_order='auto')[source]#
A StructureRelativePointer24 field is a
StructureRelativePointer
field with aField
size of three bytes.- Members
- class konfoo.StructureRelativePointer32(template=None, address=None, data_order=Byteorder.little, field_order='auto')[source]#
A StructureRelativePointer32 field is a
StructureRelativePointer
field with aField
size of four bytes.
- class konfoo.StructureRelativePointer48(template=None, address=None, data_order=Byteorder.little, field_order='auto')[source]#
A StructureRelativePointer48 field is a
StructureRelativePointer
field with aField
size of six bytes.
- class konfoo.StructureRelativePointer64(template=None, address=None, data_order=Byteorder.little, field_order='auto')[source]#
A StructureRelativePointer64 field is a
StructureRelativePointer
field with aField
size of eight bytes.
Sequence Relative Pointer#
- class konfoo.SequenceRelativePointer(iterable=None, address=None, data_order=Byteorder.little, bit_size=32, align_to=None, field_order='auto')[source]#
A SequenceRelativePointer field is a
RelativePointer
which refers to aSequence
.A SequenceRelativePointer is:
containable:
item
inself
returnsTrue
if item is part of the referencedSequence
.sized:
len(self)
returns the number of items in the referencedSequence
.indexable
self[index]
returns the item at the index of the referencedSequence
.iterable
iter(self)
iterates over the items of the referencedSequence
A SequenceRelativePointer supports the usual methods:
Insert an item before the index into the referenced
Sequence
viainsert()
.Pop an item with the index from the referenced
Sequence
viapop()
.Remove the first occurrence of an item from the referenced
Sequence
viaremove()
.
- Parameters
iterable – any iterable that contains items of
Structure
,Sequence
,Array
orField
instances. If the iterable is one of these instances itself then the iterable itself is appended to theSequence
.address (int) – relative address of the
data
object referenced by the RelativePointer field.data_order (
Byteorder
,str
) – byte order used to unpack and pack thedata
object referenced by the RelativePointer field.bit_size (int) – is the size of the RelativePointer field in bits, can be between
1
and64
.align_to (int) – aligns the RelativePointer field to the number of bytes, can be between
1
and8
. 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 thevalue
of the RelativePointer field.
Example:
>>> pointer = SequenceRelativePointer() >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data [] >>> pointer.data_size 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> len(pointer) 0 >>> [item for item in pointer] [] >>> pointer[:] [] >>> pointer.append(Field()) >>> pointer[0] Field(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=0, bit_offset=0), bit_size=0, value=None) >>> len(pointer) 1 >>> pointer.pop() Field(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=0, bit_offset=0), bit_size=0, value=None) >>> pointer.insert(0, Field()) >>> pointer.data [Field(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=0, bit_offset=0), bit_size=0, value=None)] >>> pointer.remove(pointer[0]) >>> pointer.data [] >>> pointer.clear() >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'SequenceRelativePointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'SequenceRelativePointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'class': 'Sequence', 'name': 'data', 'size': 0, 'type': 'Sequence', 'member': []} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': []} >>> pointer.to_json() '{"value": "0xffffffff", "data": []}' >>> pointer.field_items() [('field', SequenceRelativePointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff'))] >>> pointer.to_list(nested=True) [('SequenceRelativePointer.field', '0xffffffff')] >>> pointer.to_dict(nested=True) {'SequenceRelativePointer': {'field': '0xffffffff'}}
Array Relative Pointer#
- class konfoo.ArrayRelativePointer(template, size=0, address=None, data_order=Byteorder.little, bit_size=32, align_to=None, field_order='auto')[source]#
An ArrayRelativePointer field is a
SequenceRelativePointer
which refers to aArray
.An ArrayRelativePointer adapts and extends a
SequenceRelativePointer
with the following features:- Parameters
template – template for the
Array
element. The template can be anyField
instance or any callable that returns aStructure
,Sequence
,Array
or anyField
instance.size (int) – is the size of the
Array
in number ofArray
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 thedata
object referenced by the RelativePointer field.bit_size (int) – is the size of the RelativePointer field in bits, can be between
1
and64
.align_to (int) – aligns the RelativePointer field to the number of bytes, can be between
1
and8
. 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 thevalue
of the RelativePointer field.
Example:
>>> pointer = ArrayRelativePointer(Byte) >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data [] >>> pointer.data_size 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> len(pointer) 0 >>> [item for item in pointer] [] >>> pointer[:] [] >>> pointer.append() >>> pointer[0] Byte(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=1, bit_offset=0), bit_size=8, value='0x0') >>> len(pointer) 1 >>> pointer.pop() Byte(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=1, bit_offset=0), bit_size=8, value='0x0') >>> pointer.insert(0) >>> pointer.data [Byte(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=1, bit_offset=0), bit_size=8, value='0x0')] >>> pointer.remove(pointer[0]) >>> pointer.data [] >>> pointer.resize(10) >>> len(pointer) 10 >>> pointer.clear() >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'ArrayRelativePointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'ArrayRelativePointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'class': 'Array', 'name': 'data', 'size': 0, 'type': 'Array', 'member': []} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': []} >>> pointer.to_json() '{"value": "0xffffffff", "data": []}' >>> pointer.field_items() [('field', ArrayRelativePointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff'))] >>> pointer.to_list(nested=True) [('ArrayRelativePointer.field', '0xffffffff')] >>> pointer.to_dict(nested=True) {'ArrayRelativePointer': {'field': '0xffffffff'}}
- class konfoo.ArrayRelativePointer8(template, address=None, data_order=Byteorder.little)[source]#
An ArrayRelativePointer8 field is an
ArrayRelativePointer
field with aField
size of one byte.
- class konfoo.ArrayRelativePointer16(template, address=None, data_order=Byteorder.little, field_order='auto')[source]#
An ArrayRelativePointer16 field is an
ArrayRelativePointer
field with aField
size of two bytes.
- class konfoo.ArrayRelativePointer24(template, address=None, data_order=Byteorder.little, field_order='auto')[source]#
An ArrayRelativePointer24 field is an
ArrayRelativePointer
field with aField
size of three bytes.
- class konfoo.ArrayRelativePointer32(template, address=None, data_order=Byteorder.little, field_order='auto')[source]#
An ArrayRelativePointer32 field is an
ArrayRelativePointer
field with aField
size of four bytes.
- class konfoo.ArrayRelativePointer48(template, address=None, data_order=Byteorder.little, field_order='auto')[source]#
An ArrayRelativePointer48 field is an
ArrayRelativePointer
field with aField
size of six bytes.
- class konfoo.ArrayRelativePointer64(template, address=None, data_order=Byteorder.little, field_order='auto')[source]#
An ArrayRelativePointer64 field is an
ArrayRelativePointer
field with aField
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 aStream
field.A StreamRelativePointer field is:
containable:
item
inself
returnsTrue
if item is part of the referencedStream
field.sized:
len(self)
returns the length of the referencedStream
field.indexable
self[index]
returns the byte at the index of the referencedStream
field.iterable
iter(self)
iterates over the bytes of the referencedStream
field.
- Parameters
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
and64
.align_to (int) – aligns the RelativePointer field to the number of bytes, can be between
1
and8
. 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 thevalue
of the RelativePointer field.
Example:
>>> pointer = StreamRelativePointer() >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data Stream(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=0, bit_offset=0), bit_size=0, value='') >>> pointer.data_size 0 >>> len(pointer) 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> pointer.serialize(bytestream) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> bytestream.hex() 'ffffffff' >>> pointer.resize(10) >>> pointer.data_size 10 >>> len(pointer) 10 >>> pointer.bytestream = b'KonFoo is Fun' >>> pointer.bytestream '4b6f6e466f6f2069732046756e' >>> pointer.serialize_data().hex() '00000000000000000000' >>> pointer.deserialize_data() Index(byte=10, bit=0, address=4294967305, base_address=0, update=False) >>> pointer.serialize_data() b'KonFoo is ' >>> [byte for byte in pointer] # converts to int [75, 111, 110, 70, 111, 111, 32, 105, 115, 32] >>> [hex(byte) for byte in pointer] ['0x4b', '0x6f', '0x6e', '0x46', '0x6f', '0x6f', '0x20', '0x69', '0x73', '0x20'] >>> pointer[5] # converts to int 111 >>> 111 in pointer True >>> 0x0 in pointer False >>> pointer[:6] # converts to bytes b'KonFoo' >>> pointer[3:6] # converts to bytes b'Foo' >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'StreamRelativePointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'StreamRelativePointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'address': 4294967295, 'alignment': [10, 0], 'class': 'Stream10', 'index': [0, 0], 'name': 'data', 'order': 'auto', 'size': 80, 'type': 'Field', 'value': '4b6f6e466f6f20697320'} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': '4b6f6e466f6f20697320'} >>> pointer.to_json() '{"value": "0xffffffff", "data": "4b6f6e466f6f20697320"}' >>> pointer.field_items() [('field', StreamRelativePointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff')), ('data', Stream(index=Index(byte=0, bit=0, address=4294967295, base_address=0, update=False), alignment=Alignment(byte_size=10, bit_offset=0), bit_size=80, value='4b6f6e466f6f20697320'))] >>> pointer.to_list() [('StreamRelativePointer.field', '0xffffffff'), ('StreamRelativePointer.data', '4b6f6e466f6f20697320')] >>> pointer.to_dict() {'StreamRelativePointer': {'field': '0xffffffff', 'data': '4b6f6e466f6f20697320'}}
- class konfoo.StreamRelativePointer8(size=0, address=None)[source]#
A StreamRelativePointer8 field is a
StreamRelativePointer
field with aField
size of one byte.
- class konfoo.StreamRelativePointer16(size=0, address=None, field_order='auto')[source]#
A StreamRelativePointer16 field is a
StreamRelativePointer
field with aField
size of two bytes.
- class konfoo.StreamRelativePointer24(size=0, address=None, field_order='auto')[source]#
A StreamRelativePointer24 field is a
StreamRelativePointer
field with aField
size of three bytes.
- class konfoo.StreamRelativePointer32(size=0, address=None, field_order='auto')[source]#
A StreamRelativePointer32 field is a
StreamRelativePointer
field with aField
size of four bytes.
- class konfoo.StreamRelativePointer48(size=0, address=None, field_order='auto')[source]#
A StreamRelativePointer48 field is a
StreamRelativePointer
field with aField
size of six bytes.
- class konfoo.StreamRelativePointer64(size=0, address=None, field_order='auto')[source]#
A StreamRelativePointer64 field is a
StreamRelativePointer
field with aField
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 aString
field.- Parameters
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
and64
.align_to (int) – aligns the RelativePointer field to the number of bytes, can be between
1
and8
. 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 thevalue
of the RelativePointer field.
Example:
>>> pointer = StringRelativePointer() >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.data String(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=0, bit_offset=0), bit_size=0, value='') >>> pointer.data_size 0 >>> len(pointer) 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> pointer.serialize(bytestream) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> bytestream.hex() 'ffffffff' >>> pointer.resize(10) >>> pointer.data_size 10 >>> len(pointer) 10 >>> pointer.bytestream = b'KonFoo is Fun' >>> pointer.bytestream '4b6f6e466f6f2069732046756e' >>> pointer.serialize_data().hex() '00000000000000000000' >>> pointer.deserialize_data() Index(byte=10, bit=0, address=4294967305, base_address=0, update=False) >>> pointer.serialize_data() b'KonFoo is ' >>> [byte for byte in pointer] # converts to int [75, 111, 110, 70, 111, 111, 32, 105, 115, 32] >>> [chr(byte) for byte in pointer] # converts to int ['K', 'o', 'n', 'F', 'o', 'o', ' ', 'i', 's', ' '] >>> chr(pointer[5]) # converts to int -> chr 'o' >>> ord(' ') in pointer True >>> 0x0 in pointer False >>> pointer[:6] # converts to bytes b'KonFoo' >>> pointer[3:6] # converts to bytes b'Foo' >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'StringRelativePointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'StringRelativePointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'address': 4294967295, 'alignment': [10, 0], 'class': 'String10', 'index': [0, 0], 'name': 'data', 'order': 'auto', 'size': 80, 'type': 'Field', 'value': 'KonFoo is '} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': 'KonFoo is '} >>> pointer.to_json() '{"value": "0xffffffff", "data": "KonFoo is "}' >>> pointer.field_items() [('field', StringRelativePointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff')), ('data', String(index=Index(byte=0, bit=0, address=4294967295, base_address=0, update=False), alignment=Alignment(byte_size=10, bit_offset=0), bit_size=80, value='KonFoo is '))] >>> pointer.to_list() [('StringRelativePointer.field', '0xffffffff'), ('StringRelativePointer.data', 'KonFoo is ')] >>> pointer.to_dict() {'StringRelativePointer': {'field': '0xffffffff', 'data': 'KonFoo is '}}
- class konfoo.StringRelativePointer8(size=0, address=None)[source]#
A StringRelativePointer8 field is a
StringRelativePointer
field with aField
size of one byte.
- class konfoo.StringRelativePointer16(size=0, address=None, field_order='auto')[source]#
A StringRelativePointer16 field is a
StringRelativePointer
field with aField
size of two bytes.
- class konfoo.StringRelativePointer24(size=0, address=None, field_order='auto')[source]#
A StringRelativePointer24 field is a
StringRelativePointer
field with aField
size of three bytes.
- class konfoo.StringRelativePointer32(size=0, address=None, field_order='auto')[source]#
A StringRelativePointer32 field is a
StringRelativePointer
field with aField
size of four bytes.
- class konfoo.StringRelativePointer48(size=0, address=None, field_order='auto')[source]#
A StringRelativePointer48 field is a
StringRelativePointer
field with aField
size of six bytes.
- class konfoo.StringRelativePointer64(size=0, address=None, field_order='auto')[source]#
A StringRelativePointer64 field is a
StringRelativePointer
field with aField
size of eight bytes.
Byteorder#
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 aPointer
field. The data source is normally accessed via a dataProvider
by aPointer
field.
Field Alignment#
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 aPointer
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(value)[source]#
The Enumeration class is a subclass from the
IntEnum
class provided by the Python standard moduleenum
and extends its base class with methodsto 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)
- classmethod names()[source]#
Returns a list of the member names of a Enumeration.
Example:
>>> class Color(Enumeration): ... black = 0x000000 ... maroon = 0x080000 ... white = 0xffffff >>> Color.names() ['black', 'maroon', 'white']
- classmethod values()[source]#
Returns a list of the member values of a Enumeration.
Example:
>>> class Color(Enumeration): ... black = 0x000000 ... maroon = 0x080000 ... white = 0xffffff >>> Color.values() [0, 524288, 16777215]
- classmethod get_name(value)[source]#
Returns the name of the Enumeration member with the matching value or an empty string if no member match.
Example:
>>> class Color(Enumeration): ... black = 0x000000 ... maroon = 0x080000 ... white = 0xffffff >>> Color.get_name(0xffffff) 'white' >>> Color.get_name(0x777777) ''
- classmethod get_value(name)[source]#
Returns the value of the Enumeration member with the matching name or None if no member match.
Example:
>>> class Color(Enumeration): ... black = 0x000000 ... maroon = 0x080000 ... white = 0xffffff >>> Color.get_value('white') 16777215 >>> Color.get_value('red')
- classmethod get_member(value, default=None)[source]#
Returns the first Enumeration member with the matching value or the specified default value if no member match.
Example:
>>> class Color(Enumeration): ... black = 0x000000 ... maroon = 0x080000 ... white = 0xffffff >>> Color.get_member(0) Color.black = 0 >>> Color.get_member(0x777777, None)
Categories#
- class konfoo.Category(value)[source]#
The Category class is a is a subclass of the
Enum
class provided by the Python standard moduleenum
and extends its base class with methodsto 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')
- classmethod names()[source]#
Returns a list of the member names of a Category.
Example:
>>> class Format(Category): ... hour = 'hh' ... minute = 'mm' ... second = 'ss' >>> Format.names() ['hour', 'minute', 'second']
- classmethod values()[source]#
Returns a list of the member values of a Category.
Example:
>>> class Format(Category): ... hour = 'hh' ... minute = 'mm' ... second = 'ss' >>> Format.values() ['hh', 'mm', 'ss']
- classmethod get_name(value)[source]#
Returns the name of the Category member with the matching value or a empty string if no member match.
Example:
>>> class Format(Category): ... hour = 'hh' ... minute = 'mm' ... second = 'ss' >>> Format.get_name('hh') 'hour' >>> Format.get_name('dd') ''
- classmethod get_value(name)[source]#
Returns the value of the Category member with the matching name or None if no member match.
Example:
>>> class Format(Category): ... hour = 'hh' ... minute = 'mm' ... second = 'ss' >>> Format.get_value('hour') 'hh' >>> Format.get_value('day')
- classmethod get_member(value, default=None)[source]#
Returns the first Category member with the matching value or the specified default value if no member match.
Example:
>>> class Format(Category): ... hour = 'hh' ... minute = 'mm' ... second = 'ss' >>> Format.get_member('hh') Format.hour = 'hh' >>> Format.get_member('day', None)
Exceptions#
- exception konfoo.ByteOrderTypeError(field, 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.
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 fileThe
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": [] }
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
or32
.
Example:
>>> viewer = HexViewer() >>> viewer.dump(b'KonF`00` is Fun.') | 00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 | ---------+-------------------------------------------------+----------------- 00000000 | 4B 6F 6E 46 60 30 30 60 20 69 73 20 46 75 6E 2E | KonF`00` is Fun.
- property columns#
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.