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.-
read
(address=0, count=0)[source]¶ Returns a number of bytes read from a data source beginning at the start address.
Parameters: 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.Parameters: file ( Path
,str
) – name and location of the file to read.-
path
= None¶ File path.
-
cache
¶ Returns the internal byte stream cache of the Provider (read-only).
-
read
(address=0, count=0)[source]¶ Returns a number of bytes read from the
cache
beginning at the start address.Parameters:
-
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.-
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.
- attributes (str) – selected
-
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).
- attributes (str) – selected
-
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).
- attributes (str) – selected
-
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).
- attributes (str) – selected
-
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).
- file (str) – name and location of the
-
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).
- file (str) – name and location of the
-
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
- file (str) – name and location of the
-
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}}'
- file (str) – name and location of the
-
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.
- index (Index) – current read
Index
within the buffer. - 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.
- index (Index) – current write
Index
within the buffer. - 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.Parameters:
-
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.Parameters: content (dict) – a dictionary contains the Field
values for each member in the Structure.
-
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).
- attributes (str) – selected
-
field_items
(path='', **options)[source]¶ Returns a flatten list of
('field path', field item)
tuples for eachField
nested in the Structure.Parameters:
-
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() ] }
Parameters:
- Read from a
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.-
append
(item)[source]¶ Appends the item to the end of the Sequence.
Parameters: item – any Structure
,Sequence
,Array
orField
instance.
-
pop
(index=-1)[source]¶ Removes and returns the item at the index from the Sequence.
Parameters: index (int) – Sequence index.
-
remove
(item)[source]¶ Removes the first occurrence of an item from the Sequence.
Parameters: item – any Structure
,Sequence
,Array
orField
instance.
-
extend
(iterable)[source]¶ Extends the Sequence by appending items from the iterable.
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.
-
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.
- index (Index) – current read
Index
within the buffer. - 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.
- index (Index) – current write
Index
within the buffer. - 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.Parameters:
-
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.Parameters: content (list) – a list contains the Field
values for each item in the Sequence.
-
view_fields
(*attributes, **options)[source]¶ Returns a list with the selected field attribute or a list with the dictionaries of the selected field attributes for each
Field
nested in the Sequence.The attributes of each
Field
for containers nested in the Sequence are viewed as well (chained method call).Parameters: - attributes (str) – selected
Field
attributes. Fallback is the 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).
- attributes (str) – selected
-
field_items
(path='', **options)[source]¶ Returns a flatten list of
('field path', field item)
tuples for eachField
nested in the Sequence.Parameters:
-
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) ] }
Parameters:
- containable:
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.
-
initialize_fields
(content)[source]¶ Initializes the
Field
elements in the Array with the values in the content list.If the content list is shorter than the Array then the content list is used as a rotating fill pattern for the
Field
elements in the Array.Parameters: content (list) – a list contains the Field
values for each element in the Array or oneField
value for all elements in the Array.
- Append a new array element to the Array via
Fields¶
-
class
konfoo.
Field
(bit_size=0, align_to=0, byte_order='auto')[source]¶ The Field class is the abstract class for all field classes.
A Field has a specific name, bit size, byte order and can be aligned to other fields.
A Field has methods to unpack, pack, deserialize and serialize its field value from and to a byte stream and stores its location within the byte stream and the providing data source in its field index.
Parameters: -
bit_size
¶ Returns the size of the Field in bits (read-only).
-
name
¶ Returns the type name of the Field (read-only).
-
value
¶ Field value.
-
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.
-
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.
- index (Index) – current read
Index
within the buffer. - 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.
- index (Index) – current write
Index
of the buffer. - 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.Parameters: index (Index) – start Index
for 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 }
Parameters:
-
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'}
-
name
¶ Returns the type name of the Stream field (read-only).
-
value
¶ Field value as a lowercase hexadecimal encoded string.
-
hex
()[source]¶ Returns a string containing two hexadecimal digits for each byte in the
value
of the Stream field.
-
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.
- containable:
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 '}
-
value
¶ Field value as an ascii encoded string.
- containable:
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}
-
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 }
Parameters:
-
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}
-
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 }
Parameters:
-
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}
-
value
¶ Field value as a decimal number.
-
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 }
Parameters:
- bit_size (int) – is the size of the Decimal field in bits,
can be between
-
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}
-
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'}
-
name
¶ Returns the type name of the Byte field (read-only).
-
value
¶ Field value as a lowercase hexadecimal string prefixed with
0x
.
-
Char¶
-
class
konfoo.
Char
(align_to=None)[source]¶ A Char field is an unsigned
Decimal
field with a size of one byte and returns its 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'}
-
name
¶ Returns the type name of the Char field (read-only).
-
value
¶ Field value as an unicode string character.
-
Signed¶
-
class
konfoo.
Signed
(bit_size, align_to=None, byte_order='auto')[source]¶ A Signed field is a signed
Decimal
field with a variable size and returns its 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}
- bit_size (int) – is the size of the Signed field in bits,
can be between
-
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'}
-
value
¶ Field value as a lowercase hexadecimal string prefixed with
0x
.
- bit_size (int) – is the size of the Unsigned field in bits,
can be between
-
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'}
-
value
¶ Field value as a binary string prefixed with
0b
.
- bit_size (int) – is the size of the Bitset field in bits,
can be between
-
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}
-
value
¶ Field value as a boolean value,
True
orFalse
.
- bit_size (int) – is the size of the Bool field in bits,
can be between
-
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}
-
value
¶ Field value as an enum name string. Fall back is an unsigned integer number.
- bit_size (int) – is the size of the Enum field in bits,
can be between
-
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}
-
value
¶ Field value as a floating point number.
-
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 }
Parameters:
-
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}
-
name
¶ Returns the type name of the Fraction field (read-only).
-
value
¶ Field value as a floating point number.
-
describe
(name=None, **options)[source]¶ Returns the metadata of a Field as a
dict
.metadata = { 'address': self.index.address, 'alignment': [self.alignment.byte_size, self.alignment.bit_offset], 'class': self.name, 'index': [self.index.byte, self.index.bit], 'name': name if name else self.name, 'order': self.byte_order.value, 'size': self.bit_size, 'type': Field.item_type.name, 'value': self.value }
Parameters:
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'}
-
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'}
-
value
¶ Field value as an IPv4 address formatted string.
-
Pointer¶
-
class
konfoo.
Pointer
(template=None, address=None, data_order=Byteorder.little = 'little', bit_size=32, align_to=None, field_order='auto')[source]¶ A Pointer field is an unsigned
Decimal
field with a size of four bytes and returns its 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'}}
-
address
¶ Returns the data source address of the
data
object referenced by the Pointer field (read-only).
-
base_address
¶ Returns the data source base address of the
data
object referenced by the Pointer field (read-only).
-
bytestream
¶ Byte stream of the Pointer field for the referenced
data
object. Returned as a lowercase hexadecimal encoded string.
-
data
¶ Data object referenced by the Pointer field.
-
data_byte_order
¶ Byteorder
used to deserialize and serialize thedata
object referenced by the Pointer field.
-
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.
- buffer (bytes) – byte stream. Default is the internal
-
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: - provider (Provider) – data
Provider
. - 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
.
- provider (Provider) – data
-
patch
(item, byte_order=Byteorder.little = 'little')[source]¶ Returns a memory
Patch
for the given item that shall be patched in the data source.Parameters:
-
write_to
(provider, item, byte_order=Byteorder.little = 'little')[source]¶ Writes via a data
Provider
theField
values of the given item to the data source.Parameters:
-
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.
- index (Index) – current read
Index
within the buffer. - byte_order (
Byteorder
,str
) – decoding byte order for the de-serialization. - nested (bool) – if
True
a Pointer field de-serialize its 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.
- index (Index) – current write
Index
within the buffer. - byte_order (
Byteorder
,str
) – encoding byte order for the serialization. - nested (bool) – if
True
a Pointer field serializes its 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.Parameters: content (dict) – a dictionary contains the value
for the Pointer field and thevalue
for eachField
in 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.Parameters:
-
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).
- attributes (str) – selected
-
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.Parameters:
-
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()] }
Parameters:
- Deserialize the
-
class
konfoo.
Pointer8
(template=None, address=None, data_order=Byteorder.little = '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 = '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 = '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 = '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 = '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 = '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 = '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() #doctest: +SKIP {'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'}}
- template – template for the
-
class
konfoo.
StructurePointer8
(template=None, address=None, data_order=Byteorder.little = '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 = '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 = '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 = '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 = '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 = '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 = '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:
- Append an item to the referenced
Sequence
viaappend()
. - Insert an item before the index into the referenced
Sequence
viainsert()
. - Extend the referenced
Sequence
with items viaextend()
. - Clear the referenced
Sequence
viaclear()
. - Pop an item with the index from the referenced
Sequence
viapop()
. - Remove the first occurrence of an item from the referenced
Sequence
viaremove()
. - Reverse all items in the referenced
Sequence
viareverse()
.
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() #doctest: +SKIP {'address': 0, 'alignment': [4, 0], 'class': 'SequencePointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'SequencePointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'class': 'Sequence', 'name': 'data', 'size': 0, 'type': 'Sequence', 'member': []} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': []} >>> pointer.to_json() '{"value": "0xffffffff", "data": []}' >>> pointer.field_items() [('field', SequencePointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff'))] >>> pointer.to_list(nested=True) [('SequencePointer.field', '0xffffffff')] >>> pointer.to_dict(nested=True) {'SequencePointer': {'field': '0xffffffff'}}
-
append
(item)[source]¶ Appends the item to the end of the
Sequence
.Parameters: item – any Structure
,Sequence
,Array
orField
instance.
-
pop
(index=-1)[source]¶ Removes and returns the item at the index from the
Sequence
.Parameters: index (int) – Sequence
index.
- containable:
Array Pointer¶
-
class
konfoo.
ArrayPointer
(template, size=0, address=None, data_order=Byteorder.little = 'little', bit_size=32, align_to=None, field_order='auto')[source]¶ An ArrayPointer field is a
SequencePointer
field which refers to 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()
. - Re-size the referenced
Array
viaresize()
.
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() #doctest: +SKIP {'address': 0, 'alignment': [4, 0], 'class': 'ArrayPointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'ArrayPointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'class': 'Array', 'name': 'data', 'size': 0, 'type': 'Array', 'member': []} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': []} >>> pointer.to_json() '{"value": "0xffffffff", "data": []}' >>> pointer.field_items() [('field', ArrayPointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff'))] >>> pointer.to_list(nested=True) [('ArrayPointer.field', '0xffffffff')] >>> pointer.to_dict(nested=True) {'ArrayPointer': {'field': '0xffffffff'}}
- Append a new
-
class
konfoo.
ArrayPointer8
(template, address=None, data_order=Byteorder.little = '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 = '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 = '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 = '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 = '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 = '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: - size (int) – is the size of the
Stream
field in bytes. - address (int) – absolute address of the
data
object referenced by the Pointer field. - bit_size (int) – is the size of the Pointer field in bits,
can be between
1
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() #doctest: +SKIP {'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'}}
- containable:
-
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: - size (int) – is the size of the
String
field in bytes. - address (int) – absolute address of the
data
object referenced by the Pointer field. - bit_size (int) – is the size of the Pointer field in bits,
can be between
1
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() #doctest: +SKIP {'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 '}}
- size (int) – is the size of the
-
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() #doctest: +SKIP {'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: - provider (Provider) – data
Provider
. - 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
.
- provider (Provider) – data
- address (int) – absolute address of the
Relative Pointer¶
-
class
konfoo.
RelativePointer
(template=None, address=None, data_order=Byteorder.little = 'little', bit_size=32, align_to=None, field_order='auto')[source]¶ A RelativePointer field is a
Pointer
field which references 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'}}
-
address
¶ Returns the data source address of the
data
object referenced by the RelativePointer field (read-only).
-
base_address
¶ Returns the data source base address of the
data
object relative referenced by the RelativePointer field (read-only).
- template – template for the
-
class
konfoo.
RelativePointer8
(template=None, address=None, data_order=Byteorder.little = '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 = '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 = '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 = '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 = '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 = '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 = '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() #doctest: +SKIP {'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'}}
- template – template for the
-
class
konfoo.
StructureRelativePointer8
(template=None, address=None, data_order=Byteorder.little = '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 = '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 = '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 = '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 = '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 = '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 = '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:
- Append an item to the referenced
Sequence
viaappend()
. - Insert an item before the index into the referenced
Sequence
viainsert()
. - Extend the referenced
Sequence
with items viaextend()
. - Clear the referenced
Sequence
viaclear()
. - Pop an item with the index from the referenced
Sequence
viapop()
. - Remove the first occurrence of an item from the referenced
Sequence
viaremove()
. - Reverse all items in the referenced
Sequence
viareverse()
.
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() #doctest: +SKIP {'address': 0, 'alignment': [4, 0], 'class': 'SequenceRelativePointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'SequenceRelativePointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'class': 'Sequence', 'name': 'data', 'size': 0, 'type': 'Sequence', 'member': []} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': []} >>> pointer.to_json() '{"value": "0xffffffff", "data": []}' >>> pointer.field_items() [('field', SequenceRelativePointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff'))] >>> pointer.to_list(nested=True) [('SequenceRelativePointer.field', '0xffffffff')] >>> pointer.to_dict(nested=True) {'SequenceRelativePointer': {'field': '0xffffffff'}}
-
append
(item)[source]¶ Appends the item to the end of the
Sequence
.Parameters: item – any Structure
,Sequence
,Array
orField
instance.
-
pop
(index=-1)[source]¶ Removes and returns the item at the index from the
Sequence
.Parameters: index (int) – Sequence
index
- containable:
Array Relative Pointer¶
-
class
konfoo.
ArrayRelativePointer
(template, size=0, address=None, data_order=Byteorder.little = 'little', bit_size=32, align_to=None, field_order='auto')[source]¶ An ArrayRelativePointer field is a
SequenceRelativePointer
which refers to aArray
.An ArrayRelativePointer adapts and extends a
SequenceRelativePointer
with the following features:- Append a new
Array
element to theArray
viaappend()
. - Insert a new
Array
element before the index into theArray
viainsert()
. - Re-size the
Array
viaresize()
.
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() #doctest: +SKIP {'address': 0, 'alignment': [4, 0], 'class': 'ArrayRelativePointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'ArrayRelativePointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'class': 'Array', 'name': 'data', 'size': 0, 'type': 'Array', 'member': []} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': []} >>> pointer.to_json() '{"value": "0xffffffff", "data": []}' >>> pointer.field_items() [('field', ArrayRelativePointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff'))] >>> pointer.to_list(nested=True) [('ArrayRelativePointer.field', '0xffffffff')] >>> pointer.to_dict(nested=True) {'ArrayRelativePointer': {'field': '0xffffffff'}}
- Append a new
-
class
konfoo.
ArrayRelativePointer8
(template, address=None, data_order=Byteorder.little = '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 = '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 = '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 = '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 = '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 = '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: - size (int) – is the size of the
Stream
field in bytes. - address (int) – relative address of the
data
object referenced by the RelativePointer field. - bit_size (int) – is the size of the RelativePointer field in bits,
can be between
1
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() #doctest: +SKIP {'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'}}
- containable:
-
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: - size (int) – is the size of the
String
field in bytes. - address (int) – relative address of the
data
object referenced by the RelativePointer field. - bit_size (int) – is the size of the RelativePointer field in bits,
can be between
1
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() #doctest: +SKIP {'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 '}}
- size (int) – is the size of the
-
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.Parameters: - byte (int) – byte offset of the
Field
in the byte stream. - bit (int) – bit offset of the
Field
relative to its byte offset. - address (int) – address of the
Field
in the data source. - base_address (int) – start address of the byte stream in the data source.
- update (bool) – if
True
the byte stream needs to be updated.
- byte (int) – byte offset of the
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
[source]¶ The Enumeration class is a subclass from the
IntEnum
class provided by the Python standard moduleenum
and extends its base class with methods- to describe a specific Enumeration member by its name, value pair
- to list the member names of an Enumeration
- to list the member values of an Enumeration
- to get the value of the Enumeration member with the matching name
- to get the name of the Enumeration member with the matching value
- to get the member of the Enumeration with the matching value
Example:
>>> class Color(Enumeration): ... black = 0x000000 ... maroon = 0x080000 ... white = 0xffffff >>> Color <enum 'Color'> >>> type(Color.maroon) <enum 'Color'> >>> isinstance(Color, Enumeration) False >>> issubclass(Color, Enumeration) True >>> isinstance(Color.maroon, Color) True >>> print(Color.maroon) (maroon, 524288) >>> str(Color.maroon) '(maroon, 524288)' >>> Color.maroon Color.maroon = 524288 >>> repr(Color.maroon) 'Color.maroon = 524288' >>> list(Color) [Color.black = 0, Color.maroon = 524288, Color.white = 16777215] >>> [color for color in Color] [Color.black = 0, Color.maroon = 524288, Color.white = 16777215] >>> Color.maroon.name 'maroon' >>> Color.maroon.value 524288 >>> Color.maroon.describe() ('maroon', 524288) >>> [color.name for color in Color] ['black', 'maroon', 'white'] >>> Color.names() ['black', 'maroon', 'white'] >>> [color.value for color in Color] [0, 524288, 16777215] >>> Color.values() [0, 524288, 16777215] >>> Color['maroon'].value 524288 >>> Color.get_value('maroon') 524288 >>> Color(0).name 'black' >>> Color.get_name(0) 'black' >>> Color.get_member(0) Color.black = 0 >>> int(Color.black) 0 >>> 0 in Color.values() True >>> 'black' in Color.names() True
Categories¶
-
class
konfoo.
Category
[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 methods- to describe a specific Category member by its name, value pair
- to list the member names of a Category
- to list the member values of a Category
- to get the value of the Category member with the matching name
- to get the name of the Category member with the matching value
- to get the member of the Category with the matching value
Example:
>>> class Format(Category): ... hour = 'hh' ... minute = 'mm' ... second = 'ss' >>> Format <enum 'Format'> >>> type(Format.hour) <enum 'Format'> >>> isinstance(Format, Category) False >>> issubclass(Format, Category) True >>> isinstance(Format.hour, Format) True >>> print(Format.hour) (hour, hh) >>> str(Format.hour) '(hour, hh)' >>> Format.hour Format.hour = 'hh' >>> repr(Format.hour) "Format.hour = 'hh'" >>> list(Format) [Format.hour = 'hh', Format.minute = 'mm', Format.second = 'ss'] >>> [format for format in Format] [Format.hour = 'hh', Format.minute = 'mm', Format.second = 'ss'] >>> Format.hour.name 'hour' >>> Format.hour.value 'hh' >>> Format.hour.describe() ('hour', 'hh') >>> [format.name for format in Format] ['hour', 'minute', 'second'] >>> Format.names() ['hour', 'minute', 'second'] >>> [format.value for format in Format] ['hh', 'mm', 'ss'] >>> Format.values() ['hh', 'mm', 'ss'] >>> Format['hour'].value 'hh' >>> Format.get_value('hour') 'hh' >>> Format('hh').name 'hour' >>> Format.get_name('hh') 'hour' >>> Format.get_member('hh') Format.hour = 'hh' >>> 'hh' in Format.values() True >>> 'hour' in Format.names() True
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": [] }
Parameters:
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.
-
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.
-