Metadata-Version: 2.1
Name: generic-struct
Version: 1.0.3
Summary: A simple package to simplify conversion between binary data and python objects
Home-page: UNKNOWN
Author: Ori Pardo
Author-email: pardooori@gmail.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Requires-Python: >=3.6
Description-Content-Type: text/markdown

This package allows quick and simple creation of protocol-handling classes. It consists of two maintypes -
`Struct` and `Parser` - where `Struct` represent an object with fields and a `Parser` is used to parse said
fields from and into binary buffers; the package also includes some basic `Parser`s and `Struct`s which can
be dynamically built to fit the developer's needs.

# Usage

## Structs

The class `generic_struct.structs.Struct` is the basic protocol-handling class. it has members to represent the
different fields in the protocol and the API to write buffers from its fields and read its fields from buffers.
All protocol-handling classes created using `generic_struct` are derived from `Struct`.

The methods of `Struct`:
* `get_buffer()` - create a binary buffer (a `bytes` object) representing the current fields of the struct
* `read_buffer(buffer)` - read a binary buffer into the fields of the struct
* `get_buffer_size()` - get the length of the corresponding binary buffer


### How to create a `Struct` class

The current version includes two types of `Struct`s which can be created  

#### generic_struct.structs.GenericStruct

This type of `Struct` has fields of varying types and generates buffers using each field's 
corresponding `Parser`.

To create a `Struct` of that type you can use the class-decorator `generic_struct.structs.GenericStruct.build_struct`:
```python
from generic_struct.structs.GenericStruct import build_struct

@build_struct
class MyStruct():
    <field_name> = <field_parser>
    <field_name> = <field_parser>   
    ...
```

object of this type of `Struct` can be converted to `dict`


#### generic_struct.structs.Flags

This type of `Struct` handles flags fields. Each field is a `bool` object and has a designated
bit in the serialized buffer. 

A `Struct` of this type is created usnig the class-decorator `generic_struct.structs.Flags.build_flags`:

```python
from generic_struct.structs.Flags import build_flags

@build_flags
class MyFlags():
    FIELDS = ['list', 'of', 'field', 'names']
```

Where The first element in the FIELDS list is the most significant bit of the first byte in the buffer, and so on.

To have more control over the positions of the bits in the buffer, you can insert
`generic_struct.structs.Flags.RESERVED` to represent one unused bit or `generic_struct.structs.Flags.ReservedBits(n)`
to represent `n` unused bits. unused bits in the buffer are Always 0. 

```python
from generic_struct.structs.Flags import build_flags, RESERVED, ReservedBits

@build_flags
class MyFlags():
    FIELDS = [ReservedBits(5), 'some', 'bits', 'are', RESERVED , 'bits']
```

object of this type of `Struct` can be converted to `dict`

## Parsers
A `Parser` class is responsible to converting between a specific `type` and a binary buffer in a specific way;
_converting between `int` and an unsigned big-endian 4-bytes integer, for example._

`Parser`s are mainly used in the creation of `Struct` classes.

The more complicated `Parser`s use other `Parser`s in order to do their work. 

This package contains a bunch of common useful `Parser`s:

|Parser |Supported Types |Buffer type    |
|------ |------          |-----------    |
|generic_struct.parsers.StaticField.StaticFieldParser|`int`, `bool`, `float`, `bytes`|simple conversion using the `struct` module|
|generic_struct.parsers.StaticSizeBuffer.StaticSizeBufferParser|`str`|a buffer with a pre-determined size|
|generic_struct.parsers.DynamicSizeBuffer.DynamicSizeBufferParser|`str`|length of the buffer, then the buffer|
|generic_struct.parsers.StaticSizeList.StaticSizeListParser|`list`|every element of a pre-defined size list, parsed with a `Parser` for the elements|
|generic_struct.parsers.DynamicSizeList.DynamicSizeListParser|`list`|length of the list, then the elements of the list|
|generic_struct.parsers.DelimitedBuffer.DelimitedBufferParser|`str`|a buffer with a delimiter buffer/byte at its end|
|generic_struct.parsers.DelimitedList.DelimitedListParser|`str`|a list with a delimiter object at its end|
|generic_struct.parsers.StructParser|`Struct`|a parser for a specific type of `Struct`|
|generic_struct.parsers.Union.UnionParser|any one of a list of `Struct`s|a number which defines the parsed type, then the parsed object|

### generic_struct.parsers.StaticField.StaticFieldParser
The most simple `Parser` is ``. This `Parser` wraps the
functionality of `struct.pack()` and `struct.unpack_from()`, although meant to handle mainly `int` and `float`.

The `generic_struct.parsers.StaticField` module also contains wrappers for the different types `StaticFieldParser`
can handle: `SignedIntFormats`, `UnsignedIntFormats`, `FloatFormats`, `CHAR_FORMAT`, and `BOOL_FORMAT`. 

_Example_: The parser `StaticFieldParser(SignedIntFormats.BE_DWORD)` would serialize `11` as `b'\x00\x00\x00\x11'`

### generic_struct.parsers.StaticSizeBuffer.StaticSizeBufferParser
This parser packs a `str` into a buffer of a static size. Too short strings are padded with `b'\x00'`.
For example, the string `'some txt'` will be converted to `b'some txt\x00\x00'`.

**Note**: trailing `b'\x00'`s are not automatically removed by `StaticSizeBufferParser.parse()`. The buffer 
`b'some txt\x00\x00'` is parsed as the string `'some txt\x00\x00'`. 

### generic_struct.parsers.DynamicSizeBuffer.DynamicSizeBufferParser

This parser packs a `str` into a dynamic sized buffer. The buffer begins with the length of the string, serialized
by a `Parser` that can serialize the type `int`, and then the string itself.

_Example_: the parser `DynamicSizeBufferParser(StaticFieldParser(UnsignedIntFormats.BYTE))` serializes the string
`'some string'` as the buffer `b'\x0bsome string'`, while the parser
`DynamicSizeBufferParser(StaticFieldParser(UnsignedIntFormats.LE_DWORD))` serializes it as
`b'\x0b\x00\x00\x00some string'` 

### generic_struct.parsers.StaticSizeList.StaticSizeListParser

This parser packs a static-sized `list` into a buffer, with the elements packed by a `Parser`
that can parse all the elements in the list.

_Example_: the parser `StaticSizeListParser(element_parser=StaticFieldParser(SignedIntFormats.LE_WORD), size=3)`
serializes the list `[3,-1,5]` as `b'\x03\x00\xff\xff\x05\x00'`

### generic_struct.parsers.DynamicSizeList.DynamicSizeListParser

This parser packs a dynamic-sized list into a buffer similarly to
`generic_struct.parsers.StaticSizeList.StaticSizeListParser`, except that the size of the list is added at the beginning
of the buffer

_Example_: the parser
```
DynamicSizeListParser(element_parser=StaticFieldParser(SignedIntFormats.LE_WORD),
                      size_parser=StaticFieldParser(SignedIntFormats.BYTE))
```
serializes the list `[3,-1,5]` as `b'\x03\x03\x00\xff\xff\x05\x00'`

### generic_struct.parsers.DelimitedBuffer.DelimitedBufferParser

This parser packs a string as a buffer with a delimiter. The delimiter is a `bytes` of any length

_Example_: the parser `DelimitedBufferParser(b'\x93)` serializes the string `'some_string'` as `b'some_string\x93'`

### generic_struct.parsers.DelimitedList.DelimitedListParser

This parser packs a `list` as a buffer with a delimiter: The elements packed by a `Parser`
that can parse all the elements in the list, and then a delimiter with its own `Parser`

_Example_: the parser
```
DelimitedListParser(element_parser=StaticFieldParser(SignedIntFormats.LE_WORD),
                    delimiter=700,
                    delimiter_parser=StaticFieldParser(UnsignedIntFormats.BE_DWORD))
```
serializes the list `[3,-1,5]` as `b'\x03\x00\xff\xff\x05\x00\x00\x00\x02\xbc'`

### generic_struct.parsers.StructParser

This parser packs a child-class of `Struct`. it is useful when one wishes one of the fields in their `Struct` to be 
a `Struct`. 

### generic_struct.parsers.Union.UnionParser

This parser packs one of a list of types, and adds a type identifier field packed with its own parser
at the beginning of the buffer.

_Example_: The parser
```
UnionParser(type_enum_parser=StaticFieldParser(UnsignedIntFormats.BYTE),
            type_parsers=[StaticFieldParser(FloatFormats.BE_QWORD),
            DelimitedBufferParser(b'\x00')])
```

serializes:
* `124.34` as `b'\x00@_\x15\xc2\x8f\\(\xf6'`
* `'some string'` as `b'\x01some string\x00'`


## Example

```python
from generic_struct.parsers import StructParser
from generic_struct.parsers.DelimitedBuffer import DelimitedBufferParser
from generic_struct.parsers.DelimitedList import DelimitedListParser
from generic_struct.parsers.DynamicSizeBuffer import DynamicSizeBufferParser
from generic_struct.parsers.StaticField import StaticFieldParser, UnsignedIntFormats, CHAR_FORMAT
from generic_struct.parsers.StaticSizeList import StaticSizeListParser
from generic_struct.parsers.Union import UnionParser
from generic_struct.structs.Flags import ReservedBits, build_flags
from generic_struct.structs.GenericStruct import build_struct


@build_flags
class MyFlags(object):
    FIELDS = [ReservedBits(5), 'bool_a', 'bool_b', 'bool_c']


@build_struct
class MyStruct(object):
    word_int = StaticFieldParser(UnsignedIntFormats.BE_WORD)
    byte_int = DynamicSizeBufferParser(StaticFieldParser(UnsignedIntFormats.BYTE))
    delim_list = DelimitedListParser(element_parser=DelimitedBufferParser(b'::'),
                                     delimiter=b'$',
                                     delimiter_parser=StaticFieldParser(CHAR_FORMAT))
    union = UnionParser(StaticFieldParser(UnsignedIntFormats.BYTE),
                        [StructParser(MyFlags),
                         StaticSizeListParser(StaticFieldParser(UnsignedIntFormats.BE_DWORD), 4),
                         DelimitedBufferParser(b';')])


def main():
    struct1 = MyStruct(word_int=4,
                       byte_int='some_ string',
                       delim_list=['some', 'list', 'of', 'strings'],
                       union=MyFlags(bool_a=False, bool_b=False, bool_c=True))

    print('struct1:', dict(struct1))
    print('struct1.union:', dict(struct1.union))

    buffer1 = struct1.get_buffer()
    print('serialized:', buffer1)
    print()
    struct2 = MyStruct()
    struct2.read_buffer(buffer1)

    struct2.union = 'this is a string now'
    buffer2 = struct2.get_buffer()
    print('struct2:', dict(struct2))
    print('serialized:', buffer2)


if __name__ == '__main__':
    main()
```

the output would be:

```
struct1: {'word_int': 4, 'byte_int': 'some_ string', 'delim_list': ['some', 'list', 'of', 'strings'], 'union': <generic_struct.structs.Flags.flags.<locals>.Flags object at 0x03304810>}
struct1.union: {'bool_a': False, 'bool_b': False, 'bool_c': True}
serialized: b'\x00\x04\x0csome_ stringsome::list::of::strings::$\x00\x01'

struct2: {'word_int': 4, 'byte_int': 'some_ string', 'delim_list': ['some', 'list', 'of', 'strings'], 'union': 'this is a string now'}
serialized: b'\x00\x04\x0csome_ stringsome::list::of::strings::$\x02this is a string now;'
```

