API#
This part of the documentation lists the full API reference of all public classes and functions.
Provider#
- class konfoo.Provider[source]#
The
Provider
class provides access for thePointer
class to read and write byte streams from and back to a data source.The
Provider
class servers as a metaclass.A derived class must implement the two methods
read()
andwrite()
for reading and writing byte streams from and back to the data source.- abstract read(address: int = 0, count: int = 0) bytes [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: Path | str)[source]#
The
FileProvider
is a byte streamProvider
for binary files.The file content is internal stored in a
cache
.The
read()
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#
File path.
- read(address: int = 0, count: int = 0) bytes [source]#
Returns a number of bytes read from the
cache
beginning at the start address.
Container#
- class konfoo.Container[source]#
The
Container
class is an abstract interface for all classes which can containField
items. Container classes areStructures
,Sequences
,Arrays
andPointers
.The
Container
class provides core features to view, save and load the attributes of theField
items in the Container.- abstract view_fields(*attributes: str, **options: Any) dict[str, Any] | list[Any] [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[str, ...]) – 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.
- abstract field_items(path: str = '', **options: Any) list[tuple[str, konfoo.core.Field]] [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: str, **options: Any) list[tuple[str, Any] | tuple[str, tuple[Any, ...]]] [source]#
Returns a flatten list of
('field path', attribute)
or('field path', tuple(attributes))
tuples for eachField
nested in the Container.- Parameters
attributes (str) – selected
Field
attributes. Fallback is the fieldvalue
.name (str) – name of the Container. Default is the class name of the instance.
chain (bool) – if
True
the field attributes are chained to its field path. Defaults toFalse
.nested (bool) – if
True
allPointer
fields in the Container lists their referenceddata
object field attributes as well (chained method call).
- to_dict(*attributes: str, **options: Any) dict[str, Any | tuple[Any, ...]] [source]#
Returns a flatten
dict
of{'field path': attribute}
or{'field path': tuple(attributes)}
pairs for eachField
nested in the Container.- Parameters
- save(file: str, *attributes: str, **options: Any) None [source]#
Saves the selected field attributes for each
Field
nested in the Container to an.ini
file.- Parameters
file (str) – name and location of the
.ini
file.attributes (str) – selected
Field
attributes. Fallback is the fieldvalue
.section (str) – section in the
.ini
file to look for theField
values of the Container. If no section is specified the class name of the instance is used.nested (bool) – if
True
allPointer
fields in the Container saves their referenceddata
object field attributes as well (chained method call).
Example:
>>> class Foo(Structure): ... def __init__(self): ... super().__init__() ... self.stream = Stream() ... self.float = Float() ... self.structure = Structure() ... self.structure.decimal = Decimal(8) ... self.array = Array(Byte, 3) ... self.pointer = Pointer() >>> foo = Foo() >>> foo.to_list(nested=True) [('Foo.stream', ''), ('Foo.float', 0.0), ('Foo.structure.decimal', 0), ('Foo.array[0]', '0x0'), ('Foo.array[1]', '0x0'), ('Foo.array[2]', '0x0'), ('Foo.pointer', '0x0')] >>> foo.to_json(nested=True) '{"stream": "", "float": 0.0, "structure": {"decimal": 0}, "array": ["0x0", "0x0", "0x0"], "pointer": {"value": "0x0", "data": null}}' >>> foo.save('foo.ini')
File foo.ini:
[Foo] stream = float = 0.0 structure.decimal = 0 array[0] = 0x0 array[1] = 0x0 array[2] = 0x0 pointer = 0x0
- load(file: str, **options: Any) None [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 look-up 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 values as well (chained method call).verbose (bool) – if
True
the loading is executed in verbose mode.
File foo.ini:
[Foo] stream = float = 0.0 structure.decimal = 0 array[0] = 0x0 array[1] = 0x0 array[2] = 0x0 pointer = 0x0
Example:
>>> class Foo(Structure): ... def __init__(self): ... super().__init__() ... self.stream = Stream() ... self.float = Float() ... self.structure = Structure() ... self.structure.decimal = Decimal(8) ... self.array = Array(Byte, 3) ... self.pointer = Pointer() >>> foo = Foo() >>> foo.load('foo.ini') [Foo] Foo.stream = Foo.float = 0.0 Foo.structure.decimal = 0 Foo.array[0] = 0x0 Foo.array[1] = 0x0 Foo.array[2] = 0x0 Foo.pointer = 0x0 >>> foo.to_list(nested=True) [('Foo.stream', ''), ('Foo.float', 0.0), ('Foo.structure.decimal', 0), ('Foo.array[0]', '0x0'), ('Foo.array[1]', '0x0'), ('Foo.array[2]', '0x0'), ('Foo.pointer', '0x0')] >>> foo.to_json(nested=True) '{"stream": "", "float": 0.0, "structure": {"decimal": 0}, "array": ["0x0", "0x0", "0x0"], "pointer": {"value": "0x0", "data": null}}'
- to_json(*attributes: str, **options: Any) str [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[str, ...]) – 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).
- write_json(file: str, *attributes: str, **options: Any) None [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[str, ...]) – sequence of dictionary keys for the field path and 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).
- to_csv(*attributes: str, **options: Any) list[dict[str, Any]] [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[str, ...]) – sequence of dictionary keys for the field path and the selected field attributes. Defaults to
('id', *attributes)
.nested (bool) – if
True
allPointer
fields in the Container lists their referenceddata
object field attributes as well (chained method call).
- write_csv(file: str, *attributes: str, **options: Any) None [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[str, ...]) – 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).
Structure#
- class konfoo.Structure(*args: Mapping | None, **kwargs: Any)[source]#
The
Structure
is adict
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 thedict
with theContainer
interface and attribute getter and setter for the{'key': value}
tuples to access and to assign the members of the Structure easier, but this comes with the trade-off that the dictionary keys must be valid Python attribute names.A Structure has additional methods to read, deserialize, serialize and view binary data:
Read from a
Provider
the necessary bytes for 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 flatted list viafield_items()
.Get the metadata of the Structure via
describe()
.
- read_from(provider: Provider, **options: Any) None [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: bytes = b'', index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) Index [source]#
De-serializes the Structure from the byte buffer starting at the beginning of the buffer or with the given index by mapping the bytes to the
value
for 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 to de-serialize from.
index (Index) – current read
Index
within the buffer to de-serialize.byte_order (Byteorder|Literal['auto', 'big', 'little']) – decoding byte order for the de-serialization.
nested (bool) – if
True
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 = bytearray(b''), index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) Index [source]#
Serializes the Structure to the byte buffer starting at the beginning 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 to serialize to.
byte_order (Byteorder|Literal['auto', 'big', 'little']) – 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 = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) Index [source]#
Indexes all fields in the Structure starting with the given index and returns the
Index
after the lastField
in the Structure.
- container_size() tuple[int, int] [source]#
Returns the accumulated bit size of all fields in the Structure as a tuple in the form of
(number of bytes, remaining number of bits)
.
- first_field() Field | None [source]#
Returns the first
Field
in the Structure, orNone
for an empty Structure.
- initialize_fields(content: dict[str, Any]) None [source]#
Initializes the
Field
members in the Structure with the values in the content dictionary.
- view_fields(*attributes: str, **options: Any) dict[str, Any] [source]#
Returns an
dict
which contains the{'member name': field attribute}
, or the{'member name': dict(field attributes)}
tuples 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[str, ...]) – sequence of dictionary keys for the selected field attributes. Defaults to
(*attributes)
.nested (bool) – if
True
allPointer
fields nested in the Structure views their referenceddata
object field attributes as well (chained method call).
- field_items(path: str = '', **options: Any) list[tuple[str, konfoo.core.Field]] [source]#
Returns a flatten list of
('field path', field item)
tuples for eachField
nested in the Structure.
- describe(name: str = '', **options: Any) dict[str, Any] [source]#
Returns the metadata of the Structure as a
dict
.metadata = { 'class': self.__class__.__name__, 'name': name if name else self.__class__.__name__, 'size': len(self), 'type': Structure.item_type.name 'member': [ item.describe(member) for member, item in self.items() ] }
Sequence#
- class konfoo.Sequence(iterable: Iterable[Structure | Sequence | Field] | Structure | Sequence | Field | None = None)[source]#
The
Sequence
is a mutable sequence containing heterogeneous items, and is extended with theContainer
interface.Allowed items are
Structure
,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 flatted list viafield_items()
.Get the metadata of the Sequence via
describe()
.
- Parameters
iterable (Iterable[Structure|Sequence|Field]|Structure|Sequence|Field|None) – any iterable that contains items of
Structure
,Sequence
,Array
orField
instances. If the iterable is one of these instances itself then the iterable itself is appended to the Sequence.
- append(item: Structure | Sequence | Field) None [source]#
Appends the item to the end of the Sequence.
- insert(index: int, item: Structure | Sequence | Field) None [source]#
Inserts the item before the index into the Sequence.
- pop(index: int = -1) Structure | Sequence | Field [source]#
Removes and returns the item at the index from the Sequence.
- Parameters
index (int) – Sequence index.
- remove(item: Structure | Sequence | Field) None [source]#
Removes the first occurrence of an item from the Sequence.
- extend(iterable: Iterable[Structure | Sequence | Field] | Structure | Sequence | Field) None [source]#
Extends the Sequence by appending items from the iterable.
- read_from(provider: Provider, **options: Any) None [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: bytes = b'', index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) Index [source]#
De-serializes the Sequence from the byte buffer starting at the beginning of the buffer or with the given index by mapping the bytes to the
value
for 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 to de-serialize from.
index (Index) – current read
Index
within the buffer to de-serialize.byte_order (Byteorder|Literal['auto', 'big', 'little']) – decoding byte order for the de-serialization.
nested (bool) – if
True
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 = bytearray(b''), index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) Index [source]#
Serializes the Sequence to the byte buffer starting at the beginning 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 to serialize to.
byte_order (Byteorder|Literal['auto', 'big', 'little']) – 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 = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) Index [source]#
Indexes all fields in the Sequence starting with the given index and returns the
Index
after the lastField
in the Sequence.
- container_size() tuple[int, int] [source]#
Returns the accumulated bit size of all fields in the Sequence as a tuple in the form of
(number of bytes, remaining number of bits)
.
- first_field() Field | None [source]#
Returns the first
Field
in the Sequence, orNone
for an empty Sequence.
- initialize_fields(content: list[Any]) None [source]#
Initializes the
Field
items in the Sequence with the values in the content list.
- view_fields(*attributes: str, **options: Any) list[Any] [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[str, ...]) – sequence of dictionary keys for the selected field attributes. Defaults to
(*attributes)
.nested (bool) – if
True
allPointer
fields nested in the Sequence views their referenceddata
object field attributes as well (chained method call).
- field_items(path: str = '', **options: Any)[source]#
Returns a flatten list of
('field path', field item)
tuples for eachField
nested in the Sequence.
- describe(name: str = '', **options: Any) dict[str, Any] [source]#
Returns the metadata of the Sequence as a
dict
.metadata = { 'class': self.__class__.__name__, 'name': name if name else self.__class__.__name__, 'size': len(self), 'type': Sequence.item_type.name 'member': [ item.describe('name[idx]') for idx, item in enumerate(self) ] }
Array#
- class konfoo.Array(template: Callable | Structure | Sequence | Field, capacity: int = 0)[source]#
The
Array
is aSequence
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: int) None [source]#
Inserts a new array element before the index of the Array.
- Parameters
index (int) – Array index.
- resize(capacity: int) None [source]#
Re-sizes the Array by appending new array elements or removing array elements from the end.
- Parameters
capacity (int) – new capacity of the Array in number of array elements.
Fields#
- class konfoo.Field(bit_size: int = 0, align_to: int = 0, byte_order: Literal['auto', 'big', 'little'] | Byteorder = '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
- abstract unpack(buffer: bytes = b'', index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) Any [source]#
Unpacks the field
value
from the buffer at the given index in accordance with the decoding byte order for the de-serialization and thebyte_order
andalignment
of the Field.The specific decoding
byte_order
of the Field overrules the decoding byte order for the de-serialization.Returns the deserialized field
value
.- Parameters
Note
This abstract method must be implemented by a derived class.
- abstract pack(buffer: bytearray = bytearray(b''), **options: Any) bytes [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: bytes = b'', index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) Index [source]#
De-serializes the Field from the byte buffer starting at the beginning of the buffer or with the given index by unpacking the bytes to the
value
of the Field in accordance with the decoding byte order for the de-serialization and the 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 to de-serialize from.
index (Index) – current read
Index
within the buffer to de-serialize.byte_order (Byteorder|Literal['auto', 'big', 'little']) – decoding byte order for the de-serialization.
nested (bool) – if
True
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 = bytearray(b''), index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) Index [source]#
Serializes the Field to the byte buffer starting at the beginning of the buffer or with the given index by packing the
value
of the Field to the byte buffer in accordance with the encoding byte order for the serialization and the 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 to serialize to.
byte_order (Byteorder|Literal['auto', 'big', 'little']) – 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 = Index(byte=0, bit=0, address=0, base_address=0, update=False)) Index [source]#
Indexes the Field with the given index und returns the
Index
after the Field.
- describe(name: str = '', **options: Any) dict[str, Any] [source]#
Returns the metadata of a Field as a
dict
.metadata = { 'address': self.index.address, 'alignment': [self.alignment.byte_size, self.alignment.bit_offset], 'class': self.name, 'index': [self.index.byte, self.index.bit], 'name': name if name else self.name, 'order': self.byte_order.value, 'size': self.bit_size, 'type': Field.item_type.name, 'value': self.value }
Stream#
- class konfoo.Stream(capacity: int = 0)[source]#
The
Stream
field is aField
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
capacity (int) – is the capacity of the Stream field in bytes.
Example:
>>> stream = Stream() >>> stream.is_stream() True >>> stream.name 'Stream' >>> stream.alignment Alignment(byte_size=0, bit_offset=0) >>> stream.byte_order Byteorder.auto = 'auto' >>> stream.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> stream.index_field() Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> stream.bit_size 0 >>> len(stream) 0 >>> bool(stream) False >>> stream.value '' >>> bytes(stream) b'' >>> stream.hex() '' >>> stream.resize(10) >>> stream.name 'Stream10' >>> stream.alignment Alignment(byte_size=10, bit_offset=0) >>> stream.bit_size 80 >>> stream.index_field() Index(byte=10, bit=0, address=10, base_address=0, update=False) >>> stream.value '00000000000000000000' >>> stream.value = '0102030405' >>> stream.value '01020304050000000000' >>> stream.resize(15) >>> stream.value '010203040500000000000000000000' >>> stream.resize(10) >>> stream.value = '0102030405060708090a0b0c' >>> stream.value '0102030405060708090a' >>> stream.hex() '0102030405060708090a' >>> len(stream) 10 >>> [byte for byte in stream] # converts to int [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] >>> [hex(byte) for byte in stream] ['0x1', '0x2', '0x3', '0x4', '0x5', '0x6', '0x7', '0x8', '0x9', '0xa'] >>> stream[5] # converts to int 6 >>> 7 in stream True >>> 0x0 in stream False >>> stream[5:].hex() # converts to bytes '060708090a' >>> stream.describe() {'address': 0, 'alignment': [10, 0], 'class': 'Stream10', 'index': [0, 0], 'name': 'Stream10', 'order': 'auto', 'size': 80, 'type': 'Field', 'value': '0102030405060708090a'}
String#
- class konfoo.String(capacity: int = 0)[source]#
The
String
field is aStream
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
capacity (int) – is the capacity of the String field in bytes.
Example:
>>> string = String() >>> string.is_stream() True >>> string.is_string() True >>> string.is_terminated() False >>> string.name 'String' >>> string.alignment Alignment(byte_size=0, bit_offset=0) >>> string.byte_order Byteorder.auto = 'auto' >>> string.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> string.index_field() Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> string.bit_size 0 >>> len(string) 0 >>> bool(string) False >>> string.value '' >>> bytes(string) b'' >>> string.hex() '' >>> string.resize(10) >>> string.name 'String10' >>> string.alignment Alignment(byte_size=10, bit_offset=0) >>> string.bit_size 80 >>> string.index_field() Index(byte=10, bit=0, address=10, base_address=0, update=False) >>> string.value '' >>> string.value = 'KonFoo' >>> string.value 'KonFoo' >>> string.resize(3) >>> string.value 'Kon' >>> string.resize(10) >>> string.value 'Kon' >>> string.value = 'KonFoo is Fun' >>> string.value 'KonFoo is ' >>> string.hex() '4b6f6e466f6f20697320' >>> len(string) 10 >>> [byte for byte in string] # converts to int [75, 111, 110, 70, 111, 111, 32, 105, 115, 32] >>> [chr(byte) for byte in string] # converts to int ['K', 'o', 'n', 'F', 'o', 'o', ' ', 'i', 's', ' '] >>> chr(string[5]) # converts to int -> chr 'o' >>> ord(' ') in string True >>> 0x0 in string False >>> string[:6] # converts to bytes b'KonFoo' >>> string[3:6] # converts to bytes b'Foo' >>> string.describe() {'address': 0, 'alignment': [10, 0], 'class': 'String10', 'index': [0, 0], 'name': 'String10', 'order': 'auto', 'size': 80, 'type': 'Field', 'value': 'KonFoo is '}
Float#
- class konfoo.Float(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Float
field is aField
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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the Float field.
Example:
>>> real = Float() >>> real.is_float() True >>> real.name 'Float32' >>> real.alignment Alignment(byte_size=4, bit_offset=0) >>> real.byte_order Byteorder.auto = 'auto' >>> real.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> real.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> real.bit_size 32 >>> real.min() -3.4028234663852886e+38 >>> real.max() 3.4028234663852886e+38 >>> real.smallest() 1.1754943508222875e-38 >>> real.epsilon() 5.960464477539063e-08 >>> real.value 0.0 >>> bytes(real) b'\x00\x00\x00\x00' >>> int(real) 0 >>> float(real) 0.0 >>> bool(real) False >>> real.value = 0x10 >>> real.value 16.0 >>> real.value = -3.4028234663852887e+38 >>> real.value -3.4028234663852886e+38 >>> real.value = 3.4028234663852887e+38 >>> real.value 3.4028234663852886e+38 >>> real.describe() {'address': 0, 'alignment': [4, 0], 'class': 'Float32', 'index': [0, 0], 'max': 3.4028234663852886e+38, 'min': -3.4028234663852886e+38, 'name': 'Float32', 'order': 'auto', 'size': 32, 'type': 'Field', 'value': 3.4028234663852886e+38}
Double#
- class konfoo.Double(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Double
field is aField
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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the Double field.
Example:
>>> double = Double() >>> double.is_float() True >>> double.name 'Double64' >>> double.alignment Alignment(byte_size=8, bit_offset=0) >>> double.byte_order Byteorder.auto = 'auto' >>> double.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> double.index_field() Index(byte=8, bit=0, address=8, base_address=0, update=False) >>> double.bit_size 64 >>> double.min() -1.7976931348623157e+308 >>> double.max() 1.7976931348623157e+308 >>> double.smallest() 2.2250738585072014e-308 >>> double.epsilon() 1.1102230246251565e-16 >>> double.value 0.0 >>> bytes(double) b'\x00\x00\x00\x00\x00\x00\x00\x00' >>> int(double) 0 >>> float(double) 0.0 >>> bool(double) False >>> double.value = 0x10 >>> double.value 16.0 >>> double.value = -1.7976931348623158e+308 >>> double.value -1.7976931348623157e+308 >>> double.value = 1.7976931348623158e+308 >>> double.value 1.7976931348623157e+308 >>> double.describe() {'address': 0, 'alignment': [8, 0], 'class': 'Double64', 'index': [0, 0], 'max': 1.7976931348623157e+308, 'min': -1.7976931348623157e+308, 'name': 'Double64', 'order': 'auto', 'size': 64, 'type': 'Field', 'value': 1.7976931348623157e+308}
Decimal#
- class konfoo.Decimal(bit_size: int, align_to: int | None = None, signed: bool = False, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Decimal
field is aField
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|None) – 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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the Decimal field.
Example:
>>> unsigned = Decimal(16) >>> unsigned.is_decimal() True >>> unsigned.name 'Decimal16' >>> unsigned.alignment Alignment(byte_size=2, bit_offset=0) >>> unsigned.byte_order Byteorder.auto = 'auto' >>> unsigned.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> unsigned.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> unsigned.bit_size 16 >>> unsigned.signed False >>> unsigned.min() 0 >>> unsigned.max() 65535 >>> unsigned.value 0 >>> bytes(unsigned) b'\x00\x00' >>> int(unsigned) 0 >>> float(unsigned) 0.0 >>> hex(unsigned) '0x0' >>> bin(unsigned) '0b0' >>> oct(unsigned) '0o0' >>> bool(unsigned) False >>> unsigned.as_signed() 0 >>> unsigned.as_unsigned() 0 >>> unsigned.deserialize(bytes.fromhex('0080')) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> unsigned.value 32768 >>> unsigned.value = 0x4000 >>> unsigned.value 16384 >>> unsigned.value = -1 >>> unsigned.value 0 >>> unsigned.value = 65536 >>> unsigned.value 65535 >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> unsigned.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ffff' >>> unsigned.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Decimal16', 'index': [0, 0], 'max': 65535, 'min': 0, 'name': 'Decimal16', 'order': 'auto', 'signed': False, 'size': 16, 'type': 'Field', 'value': 65535}
Example:
>>> signed = Decimal(16, signed=True) >>> signed.is_decimal() True >>> signed.name 'Decimal16' >>> signed.alignment Alignment(byte_size=2, bit_offset=0) >>> signed.byte_order Byteorder.auto = 'auto' >>> signed.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> signed.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> signed.bit_size 16 >>> signed.signed True >>> signed.min() -32768 >>> signed.max() 32767 >>> signed.value 0 >>> bytes(signed) b'\x00\x00' >>> int(signed) 0 >>> float(signed) 0.0 >>> hex(signed) '0x0' >>> bin(signed) '0b0' >>> oct(signed) '0o0' >>> bool(signed) False >>> signed.deserialize(bytes.fromhex('00c0')) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> signed.value -16384 >>> signed.value = -0x4000 >>> signed.value -16384 >>> signed.value = -32769 >>> signed.value -32768 >>> signed.value = 32768 >>> signed.value 32767 >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> signed.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ff7f' >>> signed.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Decimal16', 'index': [0, 0], 'max': 32767, 'min': -32768, 'name': 'Decimal16', 'order': 'auto', 'signed': True, 'size': 16, 'type': 'Field', 'value': 32767}
- class konfoo.Decimal8(signed: bool = False, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Decimal8
field is aDecimal
field with a size of one byte and is by default unsigned.
- class konfoo.Decimal16(signed: bool = False, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Decimal16
field is aDecimal
field with a size of two bytes and is by default unsigned.
- class konfoo.Decimal24(signed: bool = False, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Decimal24
field is aDecimal
field with a size of three bytes and is by default unsigned.
- class konfoo.Decimal32(signed: bool = False, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Decimal32
field is aDecimal
field with a size of four bytes and is by default unsigned.
- class konfoo.Decimal64(signed: bool = False, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Decimal64
field is aDecimal
field with a size of eight bytes and is by default unsigned.
Bit#
- class konfoo.Bit(number: int, align_to: int | None = None)[source]#
The
Bit
field is an unsignedDecimal
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}
Byte#
- class konfoo.Byte(align_to: int | None = None)[source]#
The
Byte
field is an unsignedDecimal
field with a size of one byte, and returns its fieldvalue
as a lowercase hexadecimal string prefixed with0x
.- Parameters
align_to (int|None) – 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'}
Char#
- class konfoo.Char(align_to: int | None = None)[source]#
The
Char
field is an unsignedDecimal
field with a size of one byte, and returns its fieldvalue
as a unicode string character.- Parameters
align_to (int|None) – 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'}
Signed#
- class konfoo.Signed(bit_size: int, align_to: int | None = None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Signed
field is a signedDecimal
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|None) – 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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the Signed field.
Example:
>>> signed = Signed(16) >>> signed.is_decimal() True >>> signed.name 'Signed16' >>> signed.alignment Alignment(byte_size=2, bit_offset=0) >>> signed.byte_order Byteorder.auto = 'auto' >>> signed.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> signed.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> signed.bit_size 16 >>> signed.signed True >>> signed.min() -32768 >>> signed.max() 32767 >>> signed.value 0 >>> bytes(signed) b'\x00\x00' >>> int(signed) 0 >>> float(signed) 0.0 >>> hex(signed) '0x0' >>> bin(signed) '0b0' >>> oct(signed) '0o0' >>> bool(signed) False >>> signed.as_signed() 0 >>> signed.as_unsigned() 0 >>> signed.deserialize(bytes.fromhex('00c0')) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> signed.value -16384 >>> signed.value = -0x4000 >>> signed.value -16384 >>> signed.value = -32769 >>> signed.value -32768 >>> signed.value = 32768 >>> signed.value 32767 >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> signed.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ff7f' >>> signed.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Signed16', 'index': [0, 0], 'max': 32767, 'min': -32768, 'name': 'Signed16', 'order': 'auto', 'signed': True, 'size': 16, 'type': 'Field', 'value': 32767}
- class konfoo.Signed8(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Signed8
field is aSigned
field with a size of one byte.
- class konfoo.Signed16(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Signed16
field is aSigned
field with a size of two bytes.
- class konfoo.Signed24(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Signed24
field is aSigned
field with a size of three bytes.
Unsigned#
- class konfoo.Unsigned(bit_size: int, align_to: int | None = None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Unsigned
field is an unsignedDecimal
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|None) – 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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the Unsigned field.
Example:
>>> unsigned = Unsigned(16) >>> unsigned.is_decimal() True >>> unsigned.name 'Unsigned16' >>> unsigned.alignment Alignment(byte_size=2, bit_offset=0) >>> unsigned.byte_order Byteorder.auto = 'auto' >>> unsigned.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> unsigned.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> unsigned.bit_size 16 >>> unsigned.signed False >>> unsigned.min() 0 >>> unsigned.max() 65535 >>> unsigned.value '0x0' >>> bytes(unsigned) b'\x00\x00' >>> int(unsigned) 0 >>> float(unsigned) 0.0 >>> hex(unsigned) '0x0' >>> bin(unsigned) '0b0' >>> oct(unsigned) '0o0' >>> bool(unsigned) False >>> unsigned.as_signed() 0 >>> unsigned.as_unsigned() 0 >>> unsigned.deserialize(bytes.fromhex('00c0')) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> unsigned.value '0xc000' >>> unsigned.value = 0x4000 >>> unsigned.value '0x4000' >>> unsigned.value = -0x1 >>> unsigned.value '0x0' >>> unsigned.value = 0x10000 >>> unsigned.value '0xffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> unsigned.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ffff' >>> unsigned.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Unsigned16', 'index': [0, 0], 'max': 65535, 'min': 0, 'name': 'Unsigned16', 'order': 'auto', 'signed': False, 'size': 16, 'type': 'Field', 'value': '0xffff'}
- class konfoo.Unsigned8(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Unsigned8
field is anUnsigned
field with a size of one byte.
- class konfoo.Unsigned16(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Unsigned16
field is anUnsigned
field with a size of two bytes.
- class konfoo.Unsigned24(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Unsigned24
field is anUnsigned
field with a size of three bytes.
- class konfoo.Unsigned32(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Unsigned32
field is anUnsigned
field with a size of four bytes.
- class konfoo.Unsigned64(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Unsigned64
field is anUnsigned
field with a size of eight bytes.
Bitset#
- class konfoo.Bitset(bit_size: int, align_to: int | None = None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Bitset
field is an unsignedDecimal
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|None) – 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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the Bitset field.
Example:
>>> bitset = Bitset(16) >>> bitset.is_decimal() True >>> bitset.name 'Bitset16' >>> bitset.alignment Alignment(byte_size=2, bit_offset=0) >>> bitset.byte_order Byteorder.auto = 'auto' >>> bitset.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> bitset.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bitset.bit_size 16 >>> bitset.signed False >>> bitset.min() 0 >>> bitset.max() 65535 >>> bitset.value '0b0000000000000000' >>> bytes(bitset) b'\x00\x00' >>> int(bitset) 0 >>> float(bitset) 0.0 >>> hex(bitset) '0x0' >>> bin(bitset) '0b0' >>> oct(bitset) '0o0' >>> bool(bitset) False >>> bitset.as_signed() 0 >>> bitset.as_unsigned() 0 >>> bitset.deserialize(bytes.fromhex('f00f')) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bitset.value '0b0000111111110000' >>> bitset.value = 0b1111 >>> bitset.value '0b0000000000001111' >>> bitset.value = -1 >>> bitset.value '0b0000000000000000' >>> bitset.value = 0x10000 >>> bitset.value '0b1111111111111111' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> bitset.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ffff' >>> bitset.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Bitset16', 'index': [0, 0], 'max': 65535, 'min': 0, 'name': 'Bitset16', 'order': 'auto', 'signed': False, 'size': 16, 'type': 'Field', 'value': '0b1111111111111111'}
- class konfoo.Bitset8(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Bitset8
field is aBitset
field with a size of one byte.
- class konfoo.Bitset16(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Bitset16
field is aBitset
field with a size of two bytes.
- class konfoo.Bitset24(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Bitset24
field is aBitset
field with a size of three bytes.
Bool#
- class konfoo.Bool(bit_size: int, align_to: int | None = None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Bool
field is an unsignedDecimal
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|None) – 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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the Bool field.
Example:
>>> boolean = Bool(16) >>> boolean.is_decimal() True >>> boolean.is_bool() True >>> boolean.name 'Bool16' >>> boolean.alignment Alignment(byte_size=2, bit_offset=0) >>> boolean.byte_order Byteorder.auto = 'auto' >>> boolean.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> boolean.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> boolean.bit_size 16 >>> boolean.signed False >>> boolean.min() 0 >>> boolean.max() 65535 >>> boolean.value False >>> bytes(boolean) b'\x00\x00' >>> int(boolean) 0 >>> float(boolean) 0.0 >>> hex(boolean) '0x0' >>> bin(boolean) '0b0' >>> oct(boolean) '0o0' >>> bool(boolean) False >>> boolean.as_signed() 0 >>> boolean.as_unsigned() 0 >>> boolean.deserialize(bytes.fromhex('0f00')) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> boolean.value True >>> boolean.value = False >>> boolean.value False >>> boolean.value = -1 >>> boolean.value False >>> boolean.value = 0x10000 >>> boolean.value True >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> boolean.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ffff' >>> boolean.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Bool16', 'index': [0, 0], 'max': 65535, 'min': 0, 'name': 'Bool16', 'order': 'auto', 'signed': False, 'size': 16, 'type': 'Field', 'value': True}
- class konfoo.Bool24(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Bool24
field is aBool
field with a size of three bytes.
Enum#
- class konfoo.Enum(bit_size: int, align_to: int | None = None, enumeration: Type[Enumeration] | None = None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Enum
field is an unsignedDecimal
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|None) – 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 (Type[Enumeration]|None) –
Enumeration
definition of the Enum field.byte_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the Enum field.
Example:
>>> enum = Enum(16, enumeration=ItemClass) >>> enum.is_decimal() True >>> enum.name 'Enum16' >>> enum.alignment Alignment(byte_size=2, bit_offset=0) >>> enum.byte_order Byteorder.auto = 'auto' >>> enum.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> enum.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> enum.bit_size 16 >>> enum.signed False >>> bytes(enum) b'\x00\x00' >>> enum.min() 0 >>> enum.max() 65535 >>> enum.value 0 >>> int(enum) 0 >>> float(enum) 0.0 >>> hex(enum) '0x0' >>> bin(enum) '0b0' >>> oct(enum) '0o0' >>> bool(enum) False >>> enum.as_signed() 0 >>> enum.as_unsigned() 0 >>> enum.deserialize(bytes.fromhex('2800')) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> enum.value 'Decimal' >>> enum.value = 48 >>> enum.value 'Enum' >>> enum.value = 'Enum' >>> enum.value 'Enum' >>> enum.value = 40 >>> enum.value 'Decimal' >>> enum.value = -1 >>> enum.value 0 >>> enum.value = 65536 >>> enum.value 65535 >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> enum.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ffff' >>> enum.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Enum16', 'index': [0, 0], 'max': 65535, 'min': 0, 'name': 'Enum16', 'order': 'auto', 'signed': False, 'size': 16, 'type': 'Field', 'value': 65535}
- class konfoo.Antivalent(align_to: int | None = None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Antivalent
field is anEnum
field with a size of two bits and a fix assigned enumeration.
- class konfoo.Enum4(align_to: int | None = None, enumeration: Enumeration | None = None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
- class konfoo.Enum8(enumeration: Enumeration | None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
- class konfoo.Enum16(enumeration: Enumeration | None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
- class konfoo.Enum24(enumeration: Enumeration | None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Enum24
field is anEnum
field with a size of three bytes.
Scaled#
- class konfoo.Scaled(scale: float | int, bit_size: int, align_to: int | None = None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Scaled
field is a signedDecimal
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
bit_size (int) – is the size of the Scaled field in bits, can be between
1
and64
.align_to (int|None) – 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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the Scaled field.
Example:
>>> scaled = Scaled(100, 16) >>> scaled.is_decimal() True >>> scaled.name 'Scaled16' >>> scaled.alignment Alignment(byte_size=2, bit_offset=0) >>> scaled.byte_order Byteorder.auto = 'auto' >>> scaled.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> scaled.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> scaled.scale 100.0 >>> scaled.scaling_base() 16384.0 >>> scaled.bit_size 16 >>> scaled.signed True >>> scaled.min() -32768 >>> scaled.max() 32767 >>> scaled.value 0.0 >>> bytes(scaled) b'\x00\x00' >>> int(scaled) 0 >>> float(scaled) 0.0 >>> hex(scaled) '0x0' >>> bin(scaled) '0b0' >>> oct(scaled) '0o0' >>> bool(scaled) False >>> scaled.as_signed() 0 >>> scaled.as_unsigned() 0 >>> scaled.deserialize(bytes.fromhex('0040')) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> scaled.value 100.0 >>> scaled.value = -100 >>> scaled.value -100.0 >>> scaled.value = -200.001 >>> scaled.value -200.0 >>> scaled.value = 200 >>> scaled.value 199.993896484375 >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> scaled.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ff7f' >>> scaled.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Scaled16', 'index': [0, 0], 'max': 32767, 'min': -32768, 'name': 'Scaled16', 'order': 'auto', 'scale': 100.0, 'signed': True, 'size': 16, 'type': 'Field', 'value': 199.993896484375}
- class konfoo.Scaled8(scale: float | int, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Scaled8
field is aScaled
field with a size of one byte.
- class konfoo.Scaled16(scale: float | int, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Scaled16
field is aScaled
field with a size of two bytes.
- class konfoo.Scaled24(scale: float | int, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Scaled24
field is aScaled
field with a size of three bytes.
Fraction#
- class konfoo.Fraction(bits_integer: int, bit_size: int, align_to: int | None = None, signed: bool = False, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Fraction
field is an unsignedDecimal
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|None) – 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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the Fraction field
Example:
>>> unipolar = Fraction(2, 16) >>> unipolar.is_decimal() True >>> unipolar.name 'Fraction2.16' >>> unipolar.alignment Alignment(byte_size=2, bit_offset=0) >>> unipolar.byte_order Byteorder.auto = 'auto' >>> unipolar.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> unipolar.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> unipolar.bit_size 16 >>> unipolar.signed False >>> unipolar.min() 0 >>> unipolar.max() 65535 >>> unipolar.value 0.0 >>> bytes(unipolar) b'\x00\x00' >>> int(unipolar) 0 >>> float(unipolar) 0.0 >>> hex(unipolar) '0x0' >>> bin(unipolar) '0b0' >>> oct(unipolar) '0o0' >>> bool(unipolar) False >>> unipolar.as_signed() 0 >>> unipolar.as_unsigned() 0 >>> unipolar.deserialize(bytes.fromhex('0080')) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> unipolar.value 200.0 >>> unipolar.value = 100 >>> unipolar.value 100.0 >>> unipolar.as_float(0x4000) 100.0 >>> unipolar.value = -1 >>> unipolar.value 0.0 >>> unipolar.value = 400 >>> unipolar.value 399.993896484375 >>> unipolar.as_float(0xffff) 399.993896484375 >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> unipolar.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ffff' >>> unipolar.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Fraction2.16', 'index': [0, 0], 'max': 65535, 'min': 0, 'name': 'Fraction2.16', 'order': 'auto', 'signed': False, 'size': 16, 'type': 'Field', 'value': 399.993896484375}
Example:
>>> bipolar = Fraction(2, 16, 2, True) >>> bipolar.is_decimal() True >>> bipolar.name 'Fraction2.16' >>> bipolar.alignment Alignment(byte_size=2, bit_offset=0) >>> bipolar.byte_order Byteorder.auto = 'auto' >>> bipolar.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> bipolar.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bipolar.bit_size 16 >>> bipolar.signed False >>> bipolar.min() 0 >>> bipolar.max() 65535 >>> bipolar.value 0.0 >>> bytes(bipolar) b'\x00\x00' >>> int(bipolar) 0 >>> float(bipolar) 0.0 >>> hex(bipolar) '0x0' >>> bin(bipolar) '0b0' >>> oct(bipolar) '0o0' >>> bool(bipolar) False >>> bipolar.as_signed() 0 >>> bipolar.as_unsigned() 0 >>> bipolar.deserialize(bytes.fromhex('0040')) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bipolar.value 100.0 >>> bipolar.value = -100 >>> bipolar.value -100.0 >>> bipolar.as_float(0xc000) -100.0 >>> bipolar.as_float(0x8000) -0.0 >>> bipolar.value = -200 >>> bipolar.value -199.993896484375 >>> bipolar.as_float(0xffff) -199.993896484375 >>> bipolar.value = 200 >>> bipolar.value 199.993896484375 >>> bipolar.as_float(0x7fff) 199.993896484375 >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> bipolar.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ff7f' >>> bipolar.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Fraction2.16', 'index': [0, 0], 'max': 65535, 'min': 0, 'name': 'Fraction2.16', 'order': 'auto', 'signed': True, 'size': 16, 'type': 'Field', 'value': 199.993896484375}
Bipolar#
- class konfoo.Bipolar(bits_integer: int, bit_size: int, align_to: int | None = None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Bipolar
field is a signedFraction
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|None) – 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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the Bipolar field.
Example:
>>> bipolar = Bipolar(2, 16) >>> bipolar.is_decimal() True >>> bipolar.name 'Bipolar2.16' >>> bipolar.alignment Alignment(byte_size=2, bit_offset=0) >>> bipolar.byte_order Byteorder.auto = 'auto' >>> bipolar.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> bipolar.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bipolar.bit_size 16 >>> bipolar.signed False >>> bipolar.min() 0 >>> bipolar.max() 65535 >>> bipolar.value 0.0 >>> bytes(bipolar) b'\x00\x00' >>> int(bipolar) 0 >>> float(bipolar) 0.0 >>> hex(bipolar) '0x0' >>> bin(bipolar) '0b0' >>> oct(bipolar) '0o0' >>> bool(bipolar) False >>> bipolar.as_signed() 0 >>> bipolar.as_unsigned() 0 >>> bipolar.value = -100 >>> bipolar.value -100.0 >>> bipolar.as_float(0xc000) -100.0 >>> bipolar.as_float(0x8000) -0.0 >>> bipolar.value = -200 >>> bipolar.value -199.993896484375 >>> bipolar.as_float(0xffff) -199.993896484375 >>> bipolar.value = 200 >>> bipolar.value 199.993896484375 >>> bipolar.as_float(0x7fff) 199.993896484375 >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> bipolar.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ff7f' >>> bipolar.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Bipolar2.16', 'index': [0, 0], 'max': 65535, 'min': 0, 'name': 'Bipolar2.16', 'order': 'auto', 'signed': True, 'size': 16, 'type': 'Field', 'value': 199.993896484375}
Unipolar#
- class konfoo.Unipolar(bits_integer: int, bit_size: int, align_to: int | None = None, byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Unipolar
field is an unsignedFraction
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|None) – 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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the Unipolar field.
Example:
>>> unipolar = Unipolar(2, 16) >>> unipolar.is_decimal() True >>> unipolar.name 'Unipolar2.16' >>> unipolar.alignment Alignment(byte_size=2, bit_offset=0) >>> unipolar.byte_order Byteorder.auto = 'auto' >>> unipolar.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> unipolar.index_field() Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> unipolar.bit_size 16 >>> unipolar.signed False >>> unipolar.min() 0 >>> unipolar.max() 65535 >>> unipolar.value 0.0 >>> bytes(unipolar) b'\x00\x00' >>> int(unipolar) 0 >>> float(unipolar) 0.0 >>> hex(unipolar) '0x0' >>> bin(unipolar) '0b0' >>> oct(unipolar) '0o0' >>> bool(unipolar) False >>> unipolar.as_signed() 0 >>> unipolar.as_unsigned() 0 >>> unipolar.deserialize(bytes.fromhex('0080')) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> unipolar.value 200.0 >>> unipolar.value = 100 >>> unipolar.value 100.0 >>> unipolar.as_float(0x4000) 100.0 >>> unipolar.value = -1 >>> unipolar.value 0.0 >>> unipolar.value = 400 >>> unipolar.value 399.993896484375 >>> unipolar.as_float(0xffff) 399.993896484375 >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> unipolar.serialize(bytestream) Index(byte=2, bit=0, address=2, base_address=0, update=False) >>> bytestream.hex() 'ffff' >>> unipolar.describe() {'address': 0, 'alignment': [2, 0], 'class': 'Unipolar2.16', 'index': [0, 0], 'max': 65535, 'min': 0, 'name': 'Unipolar2.16', 'order': 'auto', 'signed': False, 'size': 16, 'type': 'Field', 'value': 399.993896484375}
Datetime#
- class konfoo.Datetime(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Datetime
field is an unsignedDecimal
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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the Datetime field.
Example:
>>> datetime = Datetime() >>> datetime.is_decimal() True >>> datetime.name 'Datetime32' >>> datetime.alignment Alignment(byte_size=4, bit_offset=0) >>> datetime.byte_order Byteorder.auto = 'auto' >>> datetime.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> datetime.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> datetime.bit_size 32 >>> datetime.signed False >>> datetime.min() 0 >>> datetime.max() 4294967295 >>> datetime.value '1970-01-01 00:00:00' >>> bytes(datetime) b'\x00\x00\x00\x00' >>> int(datetime) 0 >>> float(datetime) 0.0 >>> hex(datetime) '0x0' >>> bin(datetime) '0b0' >>> oct(datetime) '0o0' >>> bool(datetime) False >>> datetime.as_signed() 0 >>> datetime.as_unsigned() 0 >>> datetime.deserialize(bytes.fromhex('ffffffff')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> datetime.value '2106-02-07 06:28:15' >>> datetime.value = '1969-12-31 23:59:59' >>> datetime.value '1970-01-01 00:00:00' >>> datetime.value = '2106-02-07 06:28:16' >>> datetime.value '2106-02-07 06:28:15' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> datetime.serialize(bytestream) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> bytestream.hex() 'ffffffff' >>> datetime.describe() {'address': 0, 'alignment': [4, 0], 'class': 'Datetime32', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'Datetime32', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Field', 'value': '2106-02-07 06:28:15'}
IPv4Address#
- class konfoo.IPv4Address(byte_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
IPv4Address
field is an unsignedDecimal
field with a fix size of four bytes and returns its fieldvalue
as an IPv4 address formatted string.- Parameters
byte_order (Byteorder|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the IPv4Address field.
Example:
>>> ipv4 = IPv4Address() >>> ipv4.is_decimal() True >>> ipv4.name 'Ipaddress32' >>> ipv4.alignment Alignment(byte_size=4, bit_offset=0) >>> ipv4.byte_order Byteorder.auto = 'auto' >>> ipv4.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> ipv4.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> ipv4.bit_size 32 >>> ipv4.signed False >>> ipv4.min() 0 >>> ipv4.max() 4294967295 >>> ipv4.value '0.0.0.0' >>> bytes(ipv4) b'\x00\x00\x00\x00' >>> int(ipv4) 0 >>> float(ipv4) 0.0 >>> hex(ipv4) '0x0' >>> bin(ipv4) '0b0' >>> oct(ipv4) '0o0' >>> bool(ipv4) False >>> ipv4.as_signed() 0 >>> ipv4.as_unsigned() 0 >>> ipv4.deserialize(bytes.fromhex('ffffffff')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> ipv4.value '255.255.255.255' >>> ipv4.value = '192.168.0.0' >>> ipv4.value '192.168.0.0' >>> ipv4.value = '255.255.255.255' >>> ipv4.value '255.255.255.255' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> ipv4.serialize(bytestream) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> bytestream.hex() 'ffffffff' >>> ipv4.describe() {'address': 0, 'alignment': [4, 0], 'class': 'Ipaddress32', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'Ipaddress32', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Field', 'value': '255.255.255.255'}
Pointer#
- class konfoo.Pointer(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Pointer
field is an unsignedDecimal
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 flatted list viafield_items()
.Get the metadata of the Pointer field via
describe()
.
- Parameters
template (Structure|Sequence|Field|None) – template for the
data
object referenced by the Pointer field.address (int|None) – absolute address of the
data
object referenced by the Pointer field.data_order (Byteorder|Literal['big', 'little']) – byte order used to unpack and pack the
data
object referenced by the Pointer field.bit_size (int) – is the size of the Pointer field in bits, can be between
1
and64
.align_to (int|None) – 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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the Pointer field.
Example:
>>> pointer = Pointer() >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data >>> pointer.data_size 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.initialize_fields({'value': 0x8000}) >>> pointer.value '0x8000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> pointer.serialize(bytestream) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> bytestream.hex() 'ffffffff' >>> pointer.bytestream = b'KonFoo is Fun' >>> pointer.bytestream '4b6f6e466f6f2069732046756e' >>> pointer.serialize_data() b'' >>> pointer.deserialize_data() Index(byte=0, bit=0, address=4294967295, base_address=4294967295, update=False) >>> pointer.serialize_data() b'' >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'Pointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'Pointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff'} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': None} >>> pointer.to_json() '{"value": "0xffffffff", "data": null}' >>> pointer.field_items() [('field', Pointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff'))] >>> pointer.to_list() [('Pointer.field', '0xffffffff')] >>> pointer.to_dict() {'Pointer': {'field': '0xffffffff'}}
- property address: int#
Returns the data source address of the
data
object referenced by the Pointer field (read-only).
- property base_address: int#
Returns the data source base address of the
data
object referenced by the Pointer field (read-only).
- property bytestream: str#
Byte stream of the Pointer field for the referenced
data
object. Returned as a lowercase hexadecimal encoded string.
- property data_byte_order: Byteorder#
Byteorder
used to deserialize and serialize thedata
object referenced by the Pointer field.
- deserialize_data(buffer: bytes = b'', byte_order: Literal['big', 'little'] | Byteorder | None = None) Index [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|Literal['big', 'little']) – decoding byte order for the de-serialization. Default is the
data_byte_order
of the Pointer field.
- serialize_data(byte_order: Literal['big', 'little'] | Byteorder | None = None) bytes [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|Literal['big', 'little']) – encoding byte order for the serialization. Default is the
data_byte_order
of the Pointer field.
- read_from(provider: Provider, null_allowed: bool = False, **options: Any) None [source]#
Reads from the data
Provider
the necessary number of bytes for thedata
object referenced by the Pointer field.A Pointer field stores the binary data read from the data
Provider
in itsbytestream
.- Parameters
null_allowed (bool) – if
True
read access of address zero (Null) is allowed.nested (bool) – if
True
allPointer
fields in thedata
object of the Pointer field reads their referenceddata
object fields as well (chained method call). Each Pointer field stores the bytes for its referenceddata
object in itsbytestream
.
- patch(item: Structure | Sequence | Field, byte_order: Literal['big', 'little'] | Byteorder = Byteorder.little) Patch | None [source]#
Returns a memory
Patch
for the given item that shall be patched in the data source.
- write_to(provider: Provider, item: Structure | Sequence | Field, byte_order: Byteorder = Byteorder.little) None [source]#
Writes via a data
Provider
theField
values of the given item to the data source.
- deserialize(buffer: bytes = b'', index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) Index [source]#
De-serializes the Pointer field from the byte buffer starting at the beginning of the buffer or with the given index by mapping the bytes to the
value
of the Pointer field in accordance with the decoding byte order for the de-serialization and the 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 to de-serialize from.
index (Index) – current read
Index
within the buffer to de-serialize.byte_order (Byteorder|Literal['auto', 'big', 'little']) – decoding byte order for the de-serialization.
nested (bool) – if
True
a Pointer field de-serialize its referenceddata
object as well (chained method call). EachPointer
field uses for the de-serialization of its referenceddata
object its ownbytestream
.
- serialize(buffer: bytearray = bytearray(b''), index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) Index [source]#
Serializes the Pointer field to the byte buffer starting at the beginning of the buffer or with the given index by mapping the
value
of the Pointer field to the byte buffer in accordance with the encoding byte order for the serialization and the encodingbyte_order
of the Pointer field.The specific encoding
byte_order
of the Pointer field overrules the encoding byte order for the serialization.Returns the
Index
of the buffer after the Pointer field.Optional the serialization of the referenced
data
object of the Pointer field can be enabled.- Parameters
buffer (bytearray) – byte stream to serialize to.
byte_order (Byteorder|Literal['auto', 'big', 'little']) – 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: dict[str, Any]) None [source]#
Initializes the Pointer field itself and the
Field
items in thedata
object referenced by the Pointer field with the values in the content dictionary.The
['value']
key in the content dictionary refers to the Pointer field itself and the['data']
key refers to thedata
object referenced by the Pointer field.
- index_fields(index: Index = Index(byte=0, bit=0, address=0, base_address=0, update=False), **options: Any) Index [source]#
Indexes the Pointer field and the
data
object referenced by the Pointer field starting with the given index and returns theIndex
after the Pointer field.
- view_fields(*attributes: str, **options: Any) dict[str, Any] [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[str, ...]) – sequence of dictionary keys for the selected field attributes. Defaults to
(*attributes)
.nested (bool) – if
True
allPointer
fields in thedata
object referenced by the Pointer field views their referenceddata
object field attributes as well (chained method call).
- field_items(path: str = '', **options: Any) list[tuple[str, konfoo.core.Field]] [source]#
Returns a flatten list of
('field path', field item)
tuples for the Pointer field itself and for eachField
nested in thedata
object referenced by the Pointer field.
- describe(name: str = '', **options: Any) dict[str, Any] [source]#
Returns the metadata of a Pointer as a
dict
.metadata = { 'address': self.index.address, 'alignment': [self.alignment.byte_size, self.alignment.bit_offset], 'class': self.__class__.__name__, 'index': [self.index.byte, self.index.bit], 'max': self.max(), 'min': self.min(), 'name': name if name else self.__class__.__name__, 'order': self.byte_order.value, 'size': self.bit_size, 'type': Pointer.item_type.name, 'value': self.value, 'member': [self.data.describe()] }
- class konfoo.Pointer8(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little)[source]#
The
Pointer8
field is aPointer
field with aField
size of one byte.
- class konfoo.Pointer16(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Pointer16
field is aPointer
field with aField
size of two bytes.
- class konfoo.Pointer24(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Pointer24
field is aPointer
field with aField
size of three bytes.
- class konfoo.Pointer32(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Pointer32
field is aPointer
field with aField
size of four bytes.
- class konfoo.Pointer48(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Pointer48
field is aPointer
field with aField
size of six bytes.
- class konfoo.Pointer64(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
Pointer64
field is aPointer
field with aField
size of eight bytes.
Structure Pointer#
- class konfoo.StructurePointer(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StructurePointer
field is aPointer
which refers to aStructure
.- Parameters
template (Structure|None) – template for the
data
object referenced by the Pointer field. The template must be aStructure
instance.address (int|None) – absolute address of the
data
object referenced by the Pointer field.data_order (Byteorder|Literal['big', 'little']) – byte order used to unpack and pack the
data
object referenced by the Pointer field.bit_size (int) – is the size of the Pointer field in bits, can be between
1
and64
.align_to (int|None) – 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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the Pointer field.
Example:
>>> pointer = StructurePointer() >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data {} >>> pointer.data_size 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> len(pointer) 0 >>> [name for name in pointer.keys()] [] >>> [member.value for member in pointer.values()] [] >>> [(name, member.value) for name, member in pointer.items()] [] >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'StructurePointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'StructurePointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'class': 'Structure', 'name': 'data', 'size': 0, 'type': 'Structure', 'member': []} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': {}} >>> pointer.to_json() '{"value": "0xffffffff", "data": {}}' >>> pointer.field_items() [('field', StructurePointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff'))] >>> pointer.to_list(nested=True) [('StructurePointer.field', '0xffffffff')] >>> pointer.to_dict(nested=True) {'StructurePointer': {'field': '0xffffffff'}}
- class konfoo.StructurePointer8(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little)[source]#
The
StructurePointer8
field is aStructurePointer
field with aField
size of one byte.
- class konfoo.StructurePointer16(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StructurePointer16
field is aStructurePointer
field with aField
size of two bytes.
- class konfoo.StructurePointer24(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StructurePointer24
field is aStructurePointer
field with aField
size of three bytes.
- class konfoo.StructurePointer32(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StructurePointer32
field is aStructurePointer
field with aField
size of four bytes.
- class konfoo.StructurePointer48(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StructurePointer48
field is aStructurePointer
field with aField
size of six bytes.
- class konfoo.StructurePointer64(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StructurePointer64
field is aStructurePointer
field with aField
size of eight bytes.
Sequence Pointer#
- class konfoo.SequencePointer(iterable: Iterable[Structure | Sequence | Field] | Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
SequencePointer
field is aPointer
field which refers to aSequence
.A SequencePointer field is:
containable:
item
inself
returnsTrue
if item is part of the referencedSequence
.sized:
len(self)
returns the number of items in the referencedSequence
.indexable
self[index]
returns the item at the index of the referencedSequence
.iterable
iter(self)
iterates over the items of the referencedSequence
A SequencePointer field supports the usual methods for sequences:
Insert an item before the index into the referenced
Sequence
viainsert()
.Pop an item with the index from the referenced
Sequence
viapop()
.Remove the first occurrence of an item from the referenced
Sequence
viaremove()
.
- Parameters
iterable (Iterable[Structure|Sequence|Field]|Structure|Sequence|Field|None) – 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|None) – absolute address of the
data
object referenced by the Pointer field.data_order (Byteorder|Literal['big', 'little']) – byte order used to unpack and pack the
data
object referenced by the Pointer field.bit_size (int) – is the size of the Pointer field in bits, can be between
1
and64
.align_to (int|None) – 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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the Pointer field.
Example:
>>> pointer = SequencePointer() >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data [] >>> pointer.data_size 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer).hex() '00000000' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> len(pointer) 0 >>> [item for item in pointer] [] >>> pointer[:] [] >>> pointer.append(Field()) >>> pointer[0] Field(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=0, bit_offset=0), bit_size=0, value=None) >>> len(pointer) 1 >>> pointer.pop() Field(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=0, bit_offset=0), bit_size=0, value=None) >>> pointer.insert(0, Field()) >>> pointer.data [Field(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=0, bit_offset=0), bit_size=0, value=None)] >>> pointer.remove(pointer[0]) >>> pointer.data [] >>> pointer.clear() >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'SequencePointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'SequencePointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'class': 'Sequence', 'name': 'data', 'size': 0, 'type': 'Sequence', 'member': []} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': []} >>> pointer.to_json() '{"value": "0xffffffff", "data": []}' >>> pointer.field_items() [('field', SequencePointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff'))] >>> pointer.to_list(nested=True) [('SequencePointer.field', '0xffffffff')] >>> pointer.to_dict(nested=True) {'SequencePointer': {'field': '0xffffffff'}}
- append(item: Structure | Sequence | Field) None [source]#
Appends the item to the end of the
Sequence
.
- insert(index: int, item: Structure | Sequence | Field) None [source]#
Inserts the item before the index into the
Sequence
.
- pop(index: int = -1) Structure | Sequence | Field [source]#
Removes and returns the item at the index from the
Sequence
.
- remove(item: Structure | Sequence | Field) None [source]#
Removes the first occurrence of an item from the
Sequence
.
Array Pointer#
- class konfoo.ArrayPointer(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
ArrayPointer
field is aSequencePointer
field which refers to aArray
.An ArrayPointer field adapts and extends a
SequencePointer
field with the following features:- Parameters
template (Callable|Structure|Sequence|Field) – template for the
Array
element. The template can be anyField
instance or any callable that returns aStructure
,Sequence
,Array
or anyField
instance.capacity (int) – is the capacity of the
Array
in number ofArray
elements.address (int|None) – absolute address of the
data
object referenced by the Pointer field.data_order (Byteorder|Literal['big', 'little']) – byte order used to unpack and pack the
data
object referenced by the Pointer field.bit_size (int) – is the size of the Pointer field in bits, can be between
1
and64
.align_to (int|None) – 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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the Pointer field.
Example:
>>> pointer = ArrayPointer(Byte) >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data [] >>> pointer.data_size 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> len(pointer) 0 >>> [item for item in pointer] [] >>> pointer[:] [] >>> pointer.append() >>> pointer[0] Byte(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=1, bit_offset=0), bit_size=8, value='0x0') >>> len(pointer) 1 >>> pointer.pop() Byte(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=1, bit_offset=0), bit_size=8, value='0x0') >>> pointer.insert(0) >>> pointer.data [Byte(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=1, bit_offset=0), bit_size=8, value='0x0')] >>> pointer.remove(pointer[0]) >>> pointer.data [] >>> pointer.resize(10) >>> len(pointer) 10 >>> pointer.clear() >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'ArrayPointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'ArrayPointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'class': 'Array', 'name': 'data', 'size': 0, 'type': 'Array', 'member': []} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': []} >>> pointer.to_json() '{"value": "0xffffffff", "data": []}' >>> pointer.field_items() [('field', ArrayPointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff'))] >>> pointer.to_list(nested=True) [('ArrayPointer.field', '0xffffffff')] >>> pointer.to_dict(nested=True) {'ArrayPointer': {'field': '0xffffffff'}}
- class konfoo.ArrayPointer8(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little)[source]#
The
ArrayPointer8
field is anArrayPointer
field with aField
size of one byte.
- class konfoo.ArrayPointer16(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
ArrayPointer16
field is anArrayPointer
field with aField
size of two bytes.
- class konfoo.ArrayPointer24(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
ArrayPointer24
field is anArrayPointer
field with aField
size of three bytes.
- class konfoo.ArrayPointer32(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
ArrayPointer32
field is anArrayPointer
field with aField
size of four bytes.
- class konfoo.ArrayPointer48(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
ArrayPointer48
field is anArrayPointer
field with aField
size of six bytes.
- class konfoo.ArrayPointer64(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
ArrayPointer64
field is anArrayPointer
field with aField
size of eight bytes.
Stream Pointer#
- class konfoo.StreamPointer(capacity: int = 0, address: int | None = None, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StreamPointer
field is aPointer
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
capacity (int) – is the capacity of the
Stream
field in bytes.address (int|None) – absolute address of the
data
object referenced by the Pointer field.bit_size (int) – is the size of the Pointer field in bits, can be between
1
and64
.align_to (int|None) – 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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the Pointer field.
Example:
>>> pointer = StreamPointer() >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data Stream(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=0, bit_offset=0), bit_size=0, value='') >>> pointer.data_size 0 >>> len(pointer) 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> pointer.serialize(bytestream) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> bytestream.hex() 'ffffffff' >>> pointer.resize(10) >>> pointer.data_size 10 >>> len(pointer) 10 >>> pointer.bytestream = b'KonFoo is Fun' >>> pointer.bytestream '4b6f6e466f6f2069732046756e' >>> pointer.serialize_data().hex() '00000000000000000000' >>> pointer.deserialize_data() Index(byte=10, bit=0, address=4294967305, base_address=4294967295, update=False) >>> pointer.serialize_data() b'KonFoo is ' >>> [byte for byte in pointer] # converts to int [75, 111, 110, 70, 111, 111, 32, 105, 115, 32] >>> [hex(byte) for byte in pointer] ['0x4b', '0x6f', '0x6e', '0x46', '0x6f', '0x6f', '0x20', '0x69', '0x73', '0x20'] >>> pointer[5] # converts to int 111 >>> 111 in pointer True >>> 0x0 in pointer False >>> b'KonFoo' in pointer True >>> pointer[:6] # converts to bytes b'KonFoo' >>> pointer[3:6] # converts to bytes b'Foo' >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'StreamPointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'StreamPointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'address': 4294967295, 'alignment': [10, 0], 'class': 'Stream10', 'index': [0, 0], 'name': 'data', 'order': 'auto', 'size': 80, 'type': 'Field', 'value': '4b6f6e466f6f20697320'} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': '4b6f6e466f6f20697320'} >>> pointer.to_json() '{"value": "0xffffffff", "data": "4b6f6e466f6f20697320"}' >>> pointer.field_items() [('field', StreamPointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff')), ('data', Stream(index=Index(byte=0, bit=0, address=4294967295, base_address=4294967295, update=False), alignment=Alignment(byte_size=10, bit_offset=0), bit_size=80, value='4b6f6e466f6f20697320'))] >>> pointer.to_list() [('StreamPointer.field', '0xffffffff'), ('StreamPointer.data', '4b6f6e466f6f20697320')] >>> pointer.to_dict() {'StreamPointer': {'field': '0xffffffff', 'data': '4b6f6e466f6f20697320'}}
- class konfoo.StreamPointer8(capacity: int = 0, address: int | None = None)[source]#
The
StreamPointer8
field is aStreamPointer
field with aField
size of one byte.
- class konfoo.StreamPointer16(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StreamPointer16
field is aStreamPointer
field with aField
size of two bytes.
- class konfoo.StreamPointer24(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StreamPointer24
field is aStreamPointer
field with aField
size of three bytes.
- class konfoo.StreamPointer32(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StreamPointer32
field is aStreamPointer
field with aField
size of four bytes.
- class konfoo.StreamPointer48(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StreamPointer48
field is aStreamPointer
field with aField
size of six bytes.
- class konfoo.StreamPointer64(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StreamPointer64
field is aStreamPointer
field with aField
size of eight bytes.
String Pointer#
- class konfoo.StringPointer(capacity: int = 0, address: int | None = None, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StringPointer
field is aStreamPointer
field which refers to aString
field.- Parameters
capacity (int) – is the capacity of the
String
field in bytes.address (int|None) – absolute address of the
data
object referenced by the Pointer field.bit_size (int) – is the size of the Pointer field in bits, can be between
1
and64
.align_to (int|None) – 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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the Pointer field.
Example:
>>> pointer = StringPointer() >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data String(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=0, bit_offset=0), bit_size=0, value='') >>> pointer.data_size 0 >>> len(pointer) 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> pointer.serialize(bytestream) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> bytestream.hex() 'ffffffff' >>> pointer.resize(10) >>> pointer.data_size 10 >>> len(pointer) 10 >>> pointer.bytestream = b'KonFoo is Fun' >>> pointer.bytestream '4b6f6e466f6f2069732046756e' >>> pointer.serialize_data().hex() '00000000000000000000' >>> pointer.deserialize_data() Index(byte=10, bit=0, address=4294967305, base_address=4294967295, update=False) >>> pointer.serialize_data() b'KonFoo is ' >>> [byte for byte in pointer] # converts to int [75, 111, 110, 70, 111, 111, 32, 105, 115, 32] >>> [chr(byte) for byte in pointer] # converts to int ['K', 'o', 'n', 'F', 'o', 'o', ' ', 'i', 's', ' '] >>> chr(pointer[5]) # converts to int -> chr 'o' >>> ord(' ') in pointer True >>> 0x0 in pointer False >>> pointer[:6] # converts to bytes b'KonFoo' >>> pointer[3:6] # converts to bytes b'Foo' >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'StringPointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'StringPointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'address': 4294967295, 'alignment': [10, 0], 'class': 'String10', 'index': [0, 0], 'name': 'data', 'order': 'auto', 'size': 80, 'type': 'Field', 'value': 'KonFoo is '} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': 'KonFoo is '} >>> pointer.to_json() '{"value": "0xffffffff", "data": "KonFoo is "}' >>> pointer.field_items() [('field', StringPointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff')), ('data', String(index=Index(byte=0, bit=0, address=4294967295, base_address=4294967295, update=False), alignment=Alignment(byte_size=10, bit_offset=0), bit_size=80, value='KonFoo is '))] >>> pointer.to_list() [('StringPointer.field', '0xffffffff'), ('StringPointer.data', 'KonFoo is ')] >>> pointer.to_dict() {'StringPointer': {'field': '0xffffffff', 'data': 'KonFoo is '}}
- class konfoo.StringPointer8(capacity: int = 0, address: int | None = None)[source]#
The
StringPointer8
field is aStringPointer
field with aField
size of one byte.
- class konfoo.StringPointer16(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StringPointer16
field is aStringPointer
field with aField
size of two bytes.
- class konfoo.StringPointer24(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StringPointer24
field is aStringPointer
field with aField
size of three bytes.
- class konfoo.StringPointer32(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StringPointer32
field is aStringPointer
field with aField
size of four bytes.
- class konfoo.StringPointer48(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StringPointer48
field is aStringPointer
field with aField
size of six bytes.
- class konfoo.StringPointer64(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StringPointer64
field is aStringPointer
field with aField
size of eight bytes.
Auto String Pointer#
- class konfoo.AutoStringPointer(address: int | None = None, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
AutoStringPointer
field is aStringPointer
field which refers to an auto-sizedString
field.- Parameters
address (int|None) – absolute address of the
data
object referenced by the Pointer field.bit_size (int) – is the size of the Pointer field in bits, can be between
1
and64
.align_to (int|None) – 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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the Pointer field.
Example:
>>> pointer = AutoStringPointer() >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data String(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=64, bit_offset=0), bit_size=512, value='') >>> pointer.data_size 64 >>> len(pointer) 64 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> pointer.serialize(bytestream) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> bytestream.hex() 'ffffffff' >>> pointer.resize(10) >>> pointer.data_size 10 >>> len(pointer) 10 >>> pointer.bytestream = b'KonFoo is Fun' >>> pointer.bytestream '4b6f6e466f6f2069732046756e' >>> pointer.serialize_data().hex() '00000000000000000000' >>> pointer.deserialize_data() Index(byte=10, bit=0, address=4294967305, base_address=4294967295, update=False) >>> pointer.serialize_data() b'KonFoo is ' >>> [byte for byte in pointer] # converts to int [75, 111, 110, 70, 111, 111, 32, 105, 115, 32] >>> [chr(byte) for byte in pointer] # converts to int ['K', 'o', 'n', 'F', 'o', 'o', ' ', 'i', 's', ' '] >>> chr(pointer[5]) # converts to int -> chr 'o' >>> ord(' ') in pointer True >>> 0x0 in pointer False >>> pointer[:6] # converts to bytes b'KonFoo' >>> pointer[3:6] # converts to bytes b'Foo' >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'AutoStringPointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'AutoStringPointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'address': 4294967295, 'alignment': [10, 0], 'class': 'String10', 'index': [0, 0], 'name': 'data', 'order': 'auto', 'size': 80, 'type': 'Field', 'value': 'KonFoo is '} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': 'KonFoo is '} >>> pointer.to_json() '{"value": "0xffffffff", "data": "KonFoo is "}' >>> pointer.field_items() [('field', AutoStringPointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff')), ('data', String(index=Index(byte=0, bit=0, address=4294967295, base_address=4294967295, update=False), alignment=Alignment(byte_size=10, bit_offset=0), bit_size=80, value='KonFoo is '))] >>> pointer.to_list() [('AutoStringPointer.field', '0xffffffff'), ('AutoStringPointer.data', 'KonFoo is ')] >>> pointer.to_dict() {'AutoStringPointer': {'field': '0xffffffff', 'data': 'KonFoo is '}}
Relative Pointer#
- class konfoo.RelativePointer(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
RelativePointer
field is aPointer
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 (Structure|Sequence|Field|None) – template for the
data
object referenced by the RelativePointer field.address (int|None) – relative address of the
data
object referenced by the RelativePointer field.data_order (Byteorder|Literal['big', 'little']) – byte order used to unpack and pack the
data
object referenced by the RelativePointer field.bit_size (int) – is the size of the RelativePointer field in bits, can be between
1
and64
.align_to (int|None) – 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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the RelativePointer field.
Example:
>>> pointer = RelativePointer() >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data >>> pointer.data_size 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> pointer.serialize(bytestream) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> bytestream.hex() 'ffffffff' >>> pointer.bytestream = b'KonFoo is Fun' >>> pointer.bytestream '4b6f6e466f6f2069732046756e' >>> pointer.serialize_data() b'' >>> pointer.deserialize_data() Index(byte=0, bit=0, address=4294967295, base_address=0, update=False) >>> pointer.serialize_data() b'' >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'RelativePointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'RelativePointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff'} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': None} >>> pointer.to_json() '{"value": "0xffffffff", "data": null}' >>> pointer.field_items() [('field', RelativePointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff'))] >>> pointer.to_list() [('RelativePointer.field', '0xffffffff')] >>> pointer.to_dict() {'RelativePointer': {'field': '0xffffffff'}}
- class konfoo.RelativePointer8(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little)[source]#
The
RelativePointer8
field is aRelativePointer
field with aField
size of one byte.
- class konfoo.RelativePointer16(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
RelativePointer16
field is aRelativePointer
field with aField
size of two bytes.
- class konfoo.RelativePointer24(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
RelativePointer24
field is aRelativePointer
field with aField
size of three bytes.
- class konfoo.RelativePointer32(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
RelativePointer32
field is aRelativePointer
field with aField
size of four bytes.
- class konfoo.RelativePointer48(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
RelativePointer48
field is aRelativePointer
field with aField
size of six bytes.
- class konfoo.RelativePointer64(template: Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
RelativePointer64
field is aRelativePointer
field with aField
size of eight bytes.
Structure Relative Pointer#
- class konfoo.StructureRelativePointer(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StructureRelativePointer
field is aRelativePointer
which refers to aStructure
.- Parameters
template (Structure|None) – template for the
data
object referenced by the RelativePointer field. The template must be aStructure
instance.address (int|None) – relative address of the
data
object referenced by the RelativePointer field.data_order (Byteorder|Literal['big', 'little']) – byte order used to unpack and pack the
data
object referenced by the RelativePointer field.bit_size (int) – is the size of the RelativePointer field in bits, can be between
1
and64
.align_to (int|None) – 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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the RelativePointer field.
Example:
>>> pointer = StructureRelativePointer() >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data {} >>> pointer.data_size 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> len(pointer) 0 >>> [name for name in pointer.keys()] [] >>> [member.value for member in pointer.values()] [] >>> [(name, member.value) for name, member in pointer.items()] [] >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'StructureRelativePointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'StructureRelativePointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'class': 'Structure', 'name': 'data', 'size': 0, 'type': 'Structure', 'member': []} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': {}} >>> pointer.to_json() '{"value": "0xffffffff", "data": {}}' >>> pointer.field_items() [('field', StructureRelativePointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff'))] >>> pointer.to_list(nested=True) [('StructureRelativePointer.field', '0xffffffff')] >>> pointer.to_dict(nested=True) {'StructureRelativePointer': {'field': '0xffffffff'}}
- class konfoo.StructureRelativePointer8(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little)[source]#
The
StructureRelativePointer8
field is aStructureRelativePointer
field with aField
size of one byte.
- class konfoo.StructureRelativePointer16(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StructureRelativePointer16
field is aStructureRelativePointer
field with aField
size of two bytes.
- class konfoo.StructureRelativePointer24(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StructureRelativePointer24
field is aStructureRelativePointer
field with aField
size of three bytes.- Members
- class konfoo.StructureRelativePointer32(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StructureRelativePointer32
field is aStructureRelativePointer
field with aField
size of four bytes.
- class konfoo.StructureRelativePointer48(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StructureRelativePointer48
field is aStructureRelativePointer
field with aField
size of six bytes.
- class konfoo.StructureRelativePointer64(template: Structure | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StructureRelativePointer64
field is aStructureRelativePointer
field with aField
size of eight bytes.
Sequence Relative Pointer#
- class konfoo.SequenceRelativePointer(iterable: Iterable[Structure | Sequence | Field] | Structure | Sequence | Field | None = None, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
SequenceRelativePointer
field is aRelativePointer
which refers to aSequence
.A SequenceRelativePointer is:
containable:
item
inself
returnsTrue
if item is part of the referencedSequence
.sized:
len(self)
returns the number of items in the referencedSequence
.indexable
self[index]
returns the item at the index of the referencedSequence
.iterable
iter(self)
iterates over the items of the referencedSequence
A SequenceRelativePointer supports the usual methods:
Insert an item before the index into the referenced
Sequence
viainsert()
.Pop an item with the index from the referenced
Sequence
viapop()
.Remove the first occurrence of an item from the referenced
Sequence
viaremove()
.
- Parameters
iterable (Iterable[Structure|Sequence|Field]|Structure|Sequence|Field) – 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|None) – relative address of the
data
object referenced by the RelativePointer field.data_order (Byteorder|Literal['big', 'little']) – byte order used to unpack and pack the
data
object referenced by the RelativePointer field.bit_size (int) – is the size of the RelativePointer field in bits, can be between
1
and64
.align_to (int|None) – 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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the RelativePointer field.
Example:
>>> pointer = SequenceRelativePointer() >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data [] >>> pointer.data_size 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> len(pointer) 0 >>> [item for item in pointer] [] >>> pointer[:] [] >>> pointer.append(Field()) >>> pointer[0] Field(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=0, bit_offset=0), bit_size=0, value=None) >>> len(pointer) 1 >>> pointer.pop() Field(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=0, bit_offset=0), bit_size=0, value=None) >>> pointer.insert(0, Field()) >>> pointer.data [Field(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=0, bit_offset=0), bit_size=0, value=None)] >>> pointer.remove(pointer[0]) >>> pointer.data [] >>> pointer.clear() >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'SequenceRelativePointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'SequenceRelativePointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'class': 'Sequence', 'name': 'data', 'size': 0, 'type': 'Sequence', 'member': []} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': []} >>> pointer.to_json() '{"value": "0xffffffff", "data": []}' >>> pointer.field_items() [('field', SequenceRelativePointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff'))] >>> pointer.to_list(nested=True) [('SequenceRelativePointer.field', '0xffffffff')] >>> pointer.to_dict(nested=True) {'SequenceRelativePointer': {'field': '0xffffffff'}}
- append(item: Structure | Sequence | Field) None [source]#
Appends the item to the end of the
Sequence
.
- insert(index: int, item: Structure | Sequence | Field) None [source]#
Inserts the item before the index into the
Sequence
.
- pop(index: int = -1) Structure | Sequence | Field [source]#
Removes and returns the item at the index from the
Sequence
.
- remove(item: Structure | Sequence | Field) None [source]#
Removes the first occurrence of an item from the
Sequence
.
Array Relative Pointer#
- class konfoo.ArrayRelativePointer(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
ArrayRelativePointer
field is aSequenceRelativePointer
which refers to aArray
.An ArrayRelativePointer adapts and extends a
SequenceRelativePointer
with the following features:- Parameters
template – template for the
Array
element. The template can be anyField
instance or any callable that returns aStructure
,Sequence
,Array
or anyField
instance.capacity (int) – is the capacity of the
Array
in number ofArray
elements.address (int|None) – relative address of the
data
object referenced by the RelativePointer field.data_order (Byteorder|Literal['big', 'little']) – byte order used to unpack and pack the
data
object referenced by the RelativePointer field.bit_size (int) – is the size of the RelativePointer field in bits, can be between
1
and64
.align_to (int|None) – 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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the RelativePointer field.
Example:
>>> pointer = ArrayRelativePointer(Byte) >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data [] >>> pointer.data_size 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> len(pointer) 0 >>> [item for item in pointer] [] >>> pointer[:] [] >>> pointer.append() >>> pointer[0] Byte(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=1, bit_offset=0), bit_size=8, value='0x0') >>> len(pointer) 1 >>> pointer.pop() Byte(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=1, bit_offset=0), bit_size=8, value='0x0') >>> pointer.insert(0) >>> pointer.data [Byte(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=1, bit_offset=0), bit_size=8, value='0x0')] >>> pointer.remove(pointer[0]) >>> pointer.data [] >>> pointer.resize(10) >>> len(pointer) 10 >>> pointer.clear() >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'ArrayRelativePointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'ArrayRelativePointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'class': 'Array', 'name': 'data', 'size': 0, 'type': 'Array', 'member': []} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': []} >>> pointer.to_json() '{"value": "0xffffffff", "data": []}' >>> pointer.field_items() [('field', ArrayRelativePointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff'))] >>> pointer.to_list(nested=True) [('ArrayRelativePointer.field', '0xffffffff')] >>> pointer.to_dict(nested=True) {'ArrayRelativePointer': {'field': '0xffffffff'}}
- class konfoo.ArrayRelativePointer8(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little)[source]#
The
ArrayRelativePointer8
field is anArrayRelativePointer
field with aField
size of one byte.
- class konfoo.ArrayRelativePointer16(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
ArrayRelativePointer16
field is anArrayRelativePointer
field with aField
size of two bytes.
- class konfoo.ArrayRelativePointer24(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
ArrayRelativePointer24
field is anArrayRelativePointer
field with aField
size of three bytes.
- class konfoo.ArrayRelativePointer32(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
ArrayRelativePointer32
field is anArrayRelativePointer
field with aField
size of four bytes.
- class konfoo.ArrayRelativePointer48(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
ArrayRelativePointer48
field is anArrayRelativePointer
field with aField
size of six bytes.
- class konfoo.ArrayRelativePointer64(template: Callable | Structure | Sequence | Field, capacity: int = 0, address: int | None = None, data_order: Literal['big', 'little'] | Byteorder = Byteorder.little, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
ArrayRelativePointer64
field is anArrayRelativePointer
field with aField
size of eight bytes.
Stream Relative Pointer#
- class konfoo.StreamRelativePointer(capacity: int = 0, address: int | None = None, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StreamRelativePointer
field is aRelativePointer
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
capacity (int) – is the capacity of the
Stream
field in bytes.address (int|None) – relative address of the
data
object referenced by the RelativePointer field.bit_size (int) – is the size of the RelativePointer field in bits, can be between
1
and64
.align_to (int|None) – 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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the RelativePointer field.
Example:
>>> pointer = StreamRelativePointer() >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.data Stream(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=0, bit_offset=0), bit_size=0, value='') >>> pointer.data_size 0 >>> len(pointer) 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> pointer.serialize(bytestream) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> bytestream.hex() 'ffffffff' >>> pointer.resize(10) >>> pointer.data_size 10 >>> len(pointer) 10 >>> pointer.bytestream = b'KonFoo is Fun' >>> pointer.bytestream '4b6f6e466f6f2069732046756e' >>> pointer.serialize_data().hex() '00000000000000000000' >>> pointer.deserialize_data() Index(byte=10, bit=0, address=4294967305, base_address=0, update=False) >>> pointer.serialize_data() b'KonFoo is ' >>> [byte for byte in pointer] # converts to int [75, 111, 110, 70, 111, 111, 32, 105, 115, 32] >>> [hex(byte) for byte in pointer] ['0x4b', '0x6f', '0x6e', '0x46', '0x6f', '0x6f', '0x20', '0x69', '0x73', '0x20'] >>> pointer[5] # converts to int 111 >>> 111 in pointer True >>> 0x0 in pointer False >>> pointer[:6] # converts to bytes b'KonFoo' >>> pointer[3:6] # converts to bytes b'Foo' >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'StreamRelativePointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'StreamRelativePointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'address': 4294967295, 'alignment': [10, 0], 'class': 'Stream10', 'index': [0, 0], 'name': 'data', 'order': 'auto', 'size': 80, 'type': 'Field', 'value': '4b6f6e466f6f20697320'} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': '4b6f6e466f6f20697320'} >>> pointer.to_json() '{"value": "0xffffffff", "data": "4b6f6e466f6f20697320"}' >>> pointer.field_items() [('field', StreamRelativePointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff')), ('data', Stream(index=Index(byte=0, bit=0, address=4294967295, base_address=0, update=False), alignment=Alignment(byte_size=10, bit_offset=0), bit_size=80, value='4b6f6e466f6f20697320'))] >>> pointer.to_list() [('StreamRelativePointer.field', '0xffffffff'), ('StreamRelativePointer.data', '4b6f6e466f6f20697320')] >>> pointer.to_dict() {'StreamRelativePointer': {'field': '0xffffffff', 'data': '4b6f6e466f6f20697320'}}
- class konfoo.StreamRelativePointer8(capacity: int = 0, address: int | None = None)[source]#
The
StreamRelativePointer8
field is aStreamRelativePointer
field with aField
size of one byte.
- class konfoo.StreamRelativePointer16(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StreamRelativePointer16
field is aStreamRelativePointer
field with aField
size of two bytes.
- class konfoo.StreamRelativePointer24(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StreamRelativePointer24
field is aStreamRelativePointer
field with aField
size of three bytes.
- class konfoo.StreamRelativePointer32(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StreamRelativePointer32
field is aStreamRelativePointer
field with aField
size of four bytes.
- class konfoo.StreamRelativePointer48(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StreamRelativePointer48
field is aStreamRelativePointer
field with aField
size of six bytes.
- class konfoo.StreamRelativePointer64(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StreamRelativePointer64
field is aStreamRelativePointer
field with aField
size of eight bytes.
String Relative Pointer#
- class konfoo.StringRelativePointer(capacity: int = 0, address: int | None = None, bit_size: int = 32, align_to: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StringRelativePointer
field is aStreamRelativePointer
field which refers to aString
field.- Parameters
capacity (int) – is the capacity of the
String
field in bytes.address (int|None) – relative address of the
data
object referenced by the RelativePointer field.bit_size (int) – is the size of the RelativePointer field in bits, can be between
1
and64
.align_to (int|None) – 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|Literal['auto', 'big', 'little']) – byte order used to unpack and pack the
value
of the RelativePointer field.
Example:
>>> pointer = StringRelativePointer() >>> pointer.is_decimal() True >>> pointer.is_pointer() True >>> pointer.name 'Pointer32' >>> pointer.alignment Alignment(byte_size=4, bit_offset=0) >>> pointer.byte_order Byteorder.auto = 'auto' >>> pointer.index Index(byte=0, bit=0, address=0, base_address=0, update=False) >>> pointer.index_field() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.bit_size 32 >>> pointer.signed False >>> pointer.min() 0 >>> pointer.max() 4294967295 >>> pointer.base_address 0 >>> pointer.address 0 >>> pointer.is_null() True >>> pointer.as_signed() 0 >>> pointer.as_unsigned() 0 >>> pointer.data String(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=0, bit_offset=0), bit_size=0, value='') >>> pointer.data_size 0 >>> len(pointer) 0 >>> pointer.data_byte_order Byteorder.little = 'little' >>> pointer.bytestream '' >>> pointer.value '0x0' >>> bytes(pointer) b'\x00\x00\x00\x00' >>> int(pointer) 0 >>> float(pointer) 0.0 >>> hex(pointer) '0x0' >>> bin(pointer) '0b0' >>> oct(pointer) '0o0' >>> bool(pointer) False >>> pointer.deserialize(bytes.fromhex('00c0')) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.value '0xc000' >>> pointer.value = 0x4000 >>> pointer.value '0x4000' >>> pointer.value = -0x1 >>> pointer.value '0x0' >>> pointer.value = 0x100000000 >>> pointer.value '0xffffffff' >>> bytestream = bytearray() >>> bytestream bytearray(b'') >>> pointer.serialize(bytestream) Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> bytestream.hex() 'ffffffff' >>> pointer.resize(10) >>> pointer.data_size 10 >>> len(pointer) 10 >>> pointer.bytestream = b'KonFoo is Fun' >>> pointer.bytestream '4b6f6e466f6f2069732046756e' >>> pointer.serialize_data().hex() '00000000000000000000' >>> pointer.deserialize_data() Index(byte=10, bit=0, address=4294967305, base_address=0, update=False) >>> pointer.serialize_data() b'KonFoo is ' >>> [byte for byte in pointer] # converts to int [75, 111, 110, 70, 111, 111, 32, 105, 115, 32] >>> [chr(byte) for byte in pointer] # converts to int ['K', 'o', 'n', 'F', 'o', 'o', ' ', 'i', 's', ' '] >>> chr(pointer[5]) # converts to int -> chr 'o' >>> ord(' ') in pointer True >>> 0x0 in pointer False >>> pointer[:6] # converts to bytes b'KonFoo' >>> pointer[3:6] # converts to bytes b'Foo' >>> pointer.describe() {'address': 0, 'alignment': [4, 0], 'class': 'StringRelativePointer', 'index': [0, 0], 'max': 4294967295, 'min': 0, 'name': 'StringRelativePointer', 'order': 'auto', 'signed': False, 'size': 32, 'type': 'Pointer', 'value': '0xffffffff', 'member': [ {'address': 4294967295, 'alignment': [10, 0], 'class': 'String10', 'index': [0, 0], 'name': 'data', 'order': 'auto', 'size': 80, 'type': 'Field', 'value': 'KonFoo is '} ]} >>> pointer.index_fields() Index(byte=4, bit=0, address=4, base_address=0, update=False) >>> pointer.view_fields() {'value': '0xffffffff', 'data': 'KonFoo is '} >>> pointer.to_json() '{"value": "0xffffffff", "data": "KonFoo is "}' >>> pointer.field_items() [('field', StringRelativePointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False), alignment=Alignment(byte_size=4, bit_offset=0), bit_size=32, value='0xffffffff')), ('data', String(index=Index(byte=0, bit=0, address=4294967295, base_address=0, update=False), alignment=Alignment(byte_size=10, bit_offset=0), bit_size=80, value='KonFoo is '))] >>> pointer.to_list() [('StringRelativePointer.field', '0xffffffff'), ('StringRelativePointer.data', 'KonFoo is ')] >>> pointer.to_dict() {'StringRelativePointer': {'field': '0xffffffff', 'data': 'KonFoo is '}}
- class konfoo.StringRelativePointer8(capacity: int = 0, address: int | None = None)[source]#
The
StringRelativePointer8
field is aStringRelativePointer
field with aField
size of one byte.
- class konfoo.StringRelativePointer16(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StringRelativePointer16
field is aStringRelativePointer
field with aField
size of two bytes.
- class konfoo.StringRelativePointer24(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StringRelativePointer24
field is aStringRelativePointer
field with aField
size of three bytes.
- class konfoo.StringRelativePointer32(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StringRelativePointer32
field is aStringRelativePointer
field with aField
size of four bytes.
- class konfoo.StringRelativePointer48(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StringRelativePointer48
field is aStringRelativePointer
field with aField
size of six bytes.
- class konfoo.StringRelativePointer64(capacity: int = 0, address: int | None = None, field_order: Literal['auto', 'big', 'little'] | Byteorder = 'auto')[source]#
The
StringRelativePointer64
field is aStringRelativePointer
field with aField
size of eight bytes.
Byteorder#
Field Index#
- class konfoo.Index(byte: int = 0, bit: int = 0, address: int = 0, base_address: int = 0, update: bool = False)[source]#
The
Index
class contains the relevant information of the location of aField
in a byte stream and in a data source. The byte stream is normally provided by aPointer
field. The data source is normally accessed via a dataProvider
by aPointer
field.
Field Alignment#
Memory Patch#
- class konfoo.Patch(buffer: bytes, address: int, byteorder: Byteorder, bit_size: int, bit_offset: int, inject: bool = False)[source]#
The
Patch
class contains the relevant information to patch a memory area of a data source accessed via a dataProvider
by aPointer
field.- Parameters
buffer (bytes) – byte stream for the memory area to patch within the data source. The byte stream contains the data of the patch item.
address (int) – address of the memory area to patch in the data source.
byteorder (Byteorder) – byte order of the memory area to patch in the data source.
bit_size (int) – bit size of the patch item.
bit_offset (int) – bit offset of the patch item within the memory area.
inject (bool) – if
True
the patch item must be injected into the memory area.
Enumerations#
- class konfoo.Enumeration(value)[source]#
The
Enumeration
class is a subclass from theIntEnum
class provided by the Python standard moduleenum
, and extends its base class with methodsto describe a specific Enumeration member by its name, value tuple
to list the member names of an Enumeration
to list the member values of an Enumeration
to get the value of the Enumeration member by its name
to get the name of the Enumeration member by its value
to get the member of the Enumeration by its value
Example:
>>> class Color(Enumeration): ... black = 0x000000 ... maroon = 0x080000 ... white = 0xffffff >>> Color <enum 'Color'> >>> type(Color.maroon) <enum 'Color'> >>> isinstance(Color, Enumeration) False >>> issubclass(Color, Enumeration) True >>> isinstance(Color.maroon, Color) True >>> print(Color.maroon) (maroon, 524288) >>> str(Color.maroon) '(maroon, 524288)' >>> Color.maroon Color.maroon = 524288 >>> repr(Color.maroon) 'Color.maroon = 524288' >>> list(Color) [Color.black = 0, Color.maroon = 524288, Color.white = 16777215] >>> [color for color in Color] [Color.black = 0, Color.maroon = 524288, Color.white = 16777215] >>> Color.maroon.name 'maroon' >>> Color.maroon.value 524288 >>> Color.maroon.describe() ('maroon', 524288) >>> [member.name for member in Color] ['black', 'maroon', 'white'] >>> Color.names() ['black', 'maroon', 'white'] >>> [member.value for member in Color] [0, 524288, 16777215] >>> Color.values() [0, 524288, 16777215] >>> Color['maroon'].value 524288 >>> Color.get_value('maroon') 524288 >>> Color(0).name 'black' >>> Color.get_name(0) 'black' >>> Color.get_member(0) Color.black = 0 >>> int(Color.black) 0 >>> 0 in Color.values() True >>> 'black' in Color.names() True
- describe() tuple[str, int] [source]#
Returns the name, value tuple to describe a specific Enumeration member.
Example:
>>> class Color(Enumeration): ... black = 0x000000 ... maroon = 0x080000 ... white = 0xffffff >>> Color.maroon.describe() ('maroon', 524288)
- classmethod names() list[str] [source]#
Returns a list of the member names of an Enumeration.
Example:
>>> class Color(Enumeration): ... black = 0x000000 ... maroon = 0x080000 ... white = 0xffffff >>> Color.names() ['black', 'maroon', 'white']
- classmethod values() list[int] [source]#
Returns a list of the member values of an Enumeration.
Example:
>>> class Color(Enumeration): ... black = 0x000000 ... maroon = 0x080000 ... white = 0xffffff >>> Color.values() [0, 524288, 16777215]
- classmethod get_name(value: int) str [source]#
Returns the name of the Enumeration member matches the value, or an empty string if no member match.
Example:
>>> class Color(Enumeration): ... black = 0x000000 ... maroon = 0x080000 ... white = 0xffffff >>> Color.get_name(0xffffff) 'white' >>> Color.get_name(0x777777) ''
- classmethod get_value(name: str) int | None [source]#
Returns the value of the Enumeration member matches the name, or
None
if no member match.Example:
>>> class Color(Enumeration): ... black = 0x000000 ... maroon = 0x080000 ... white = 0xffffff >>> Color.get_value('white') 16777215 >>> Color.get_value('red')
- classmethod get_member(value: int, default: Enumeration | None = None) Enumeration | None [source]#
Returns the first Enumeration member matches the value, or the specified default member if no member match.
Example:
>>> class Color(Enumeration): ... black = 0x000000 ... maroon = 0x080000 ... white = 0xffffff >>> Color.get_member(0) Color.black = 0 >>> Color.get_member(0x777777, None)
Categories#
- class konfoo.Category(value)[source]#
The
Category
class is a is a subclass of theEnum
class provided by the Python standard moduleenum
, and extends its base class with methodsto describe a specific Category member by its name, value tuple
to list the member names of a Category
to list the member values of a Category
to get the value of the Category member by its name
to get the name of the Category member by is value
to get the member of the Category by its value
Example:
>>> class Format(Category): ... hour = 'hh' ... minute = 'mm' ... second = 'ss' >>> Format <enum 'Format'> >>> type(Format.hour) <enum 'Format'> >>> isinstance(Format, Category) False >>> issubclass(Format, Category) True >>> isinstance(Format.hour, Format) True >>> print(Format.hour) (hour, hh) >>> str(Format.hour) '(hour, hh)' >>> Format.hour Format.hour = 'hh' >>> repr(Format.hour) "Format.hour = 'hh'" >>> list(Format) [Format.hour = 'hh', Format.minute = 'mm', Format.second = 'ss'] >>> [format for format in Format] [Format.hour = 'hh', Format.minute = 'mm', Format.second = 'ss'] >>> Format.hour.name 'hour' >>> Format.hour.value 'hh' >>> Format.hour.describe() ('hour', 'hh') >>> [member.name for member in Format] ['hour', 'minute', 'second'] >>> Format.names() ['hour', 'minute', 'second'] >>> [member.value for member in Format] ['hh', 'mm', 'ss'] >>> Format.values() ['hh', 'mm', 'ss'] >>> Format['hour'].value 'hh' >>> Format.get_value('hour') 'hh' >>> Format('hh').name 'hour' >>> Format.get_name('hh') 'hour' >>> Format.get_member('hh') Format.hour = 'hh' >>> 'hh' in Format.values() True >>> 'hour' in Format.names() True
- describe() tuple[str, Any] [source]#
Returns the name, value tuple to describe a specific Category member.
Example:
>>> class Format(Category): ... hour = 'hh' ... minute = 'mm' ... second = 'ss' >>> Format.hour.describe() ('hour', 'hh')
- classmethod names() list[str] [source]#
Returns a list of the member names of a Category.
Example:
>>> class Format(Category): ... hour = 'hh' ... minute = 'mm' ... second = 'ss' >>> Format.names() ['hour', 'minute', 'second']
- classmethod values() list[Any] [source]#
Returns a list of the member values of a Category.
Example:
>>> class Format(Category): ... hour = 'hh' ... minute = 'mm' ... second = 'ss' >>> Format.values() ['hh', 'mm', 'ss']
- classmethod get_name(value: Any) str [source]#
Returns the name of the Category member matches the value, or an empty string if no member match.
Example:
>>> class Format(Category): ... hour = 'hh' ... minute = 'mm' ... second = 'ss' >>> Format.get_name('hh') 'hour' >>> Format.get_name('dd') ''
- classmethod get_value(name: str) Any | None [source]#
Returns the value of the Category member matches the name, or
None
if no member match.Example:
>>> class Format(Category): ... hour = 'hh' ... minute = 'mm' ... second = 'ss' >>> Format.get_value('hour') 'hh' >>> Format.get_value('day')
- classmethod get_member(value: Any, default: Category | None = None) Category | None [source]#
Returns the first Category member matches the value, or the specified default member if no member match.
Example:
>>> class Format(Category): ... hour = 'hh' ... minute = 'mm' ... second = 'ss' >>> Format.get_member('hh') Format.hour = 'hh' >>> Format.get_member('day', None)
Exceptions#
- exception konfoo.ByteOrderTypeError(field: Field, byte_order: Any)[source]#
Raised if an inappropriate byte order type is assigned to a field class.
- exception konfoo.EnumTypeError(field: Field, enumeration: Type[Any])[source]#
Raised if an inappropriate enum type is assigned to a field class.
- exception konfoo.FactoryTypeError(field: Field | Structure | Sequence, factory, item: Field | Structure | Sequence, member: None = None, index: Index | None = None)[source]#
Raised if an inappropriate member type is produced by a factory class.
- exception konfoo.MemberTypeError(field: Structure | Sequence | Pointer, item: Any, member: str | int | None = None, index: Index | None = None)[source]#
Raised if an inappropriate member type is assigned to any container class.
- exception konfoo.ProviderTypeError(field: Field, provider: Any)[source]#
Raised if an inappropriate data provider type is assigned to a pointer class.
- exception konfoo.ContainerLengthError(field: Structure | Sequence | Pointer, length: tuple[int, int])[source]#
Raised if a container class has an inappropriate field length.
- exception konfoo.FieldAddressError(field: Field, index: Index, address: int)[source]#
Raised if an inappropriate address is assigned to a field class.
- exception konfoo.FieldAlignmentError(field: Field, index: Index, alignment: Alignment)[source]#
Raised if an inappropriate alignment value is assigned to a field class.
- exception konfoo.FieldByteOrderError(field: Field, index: Index, byte_order: Byteorder)[source]#
Raised if an inappropriate byte order value is assigned to a field class.
- exception konfoo.FieldIndexError(field: Field, index: Index)[source]#
Raised if an inappropriate index value is assigned to a field class.
- exception konfoo.FieldSizeError(field: Field, index: Index, size: int)[source]#
Raised if an inappropriate bit size value is assigned to a field class.
- exception konfoo.FieldTypeError(field: Field, index: Index, value: Any)[source]#
Raised if an inappropriate argument type is assigned to a field class.
- exception konfoo.FieldValueError(field: Field, index: Index, value)[source]#
Raised if an inappropriate argument value is assigned to a field class.
- exception konfoo.FieldValueEncodingError(field: Field, index: Index, encoding: Any)[source]#
Raised if an inappropriate value encoding is assigned to a field class.
- exception konfoo.FieldGroupByteOrderError(field: Field, index: Index, byte_order: Byteorder)[source]#
Raised if the byte order of a field contradicts its aligned field group.
Utilities#
Metadata Converter#
- konfoo.d3flare_json(metadata: dict[str, Any], file=None, **options: Any) str | None [source]#
Converts the metadata dictionary of a container or field into a
flare.json
formatted string or formatted stream written to the fileThe
flare.json
format is defined by the d3.js graphic library.The
flare.json
format looks like this:{ "class": "class of the field or container", "name": "name of the field or container", "size": "bit size of the field", "value": "value of the field", "children": [] }
Hexadecimal Viewer#
- class konfoo.HexViewer(columns: int = 16)[source]#
The
HexViewer
class writes or prints a source file or a byte stream as a hexadecimal dump to a output file or the console.- Parameters
columns (int) – number of output columns. Allowed values are
8
,16
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.
- file_dump(source: str, index: int = 0, count: int = 0, output: str = '') None [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.