{ "info": { "author": "Ori Pardo", "author_email": "pardooori@gmail.com", "bugtrack_url": null, "classifiers": [ "Intended Audience :: Developers", "Operating System :: OS Independent", "Programming Language :: Python :: 3" ], "description": "This package allows quick and simple creation of protocol-handling classes. It consists of two maintypes -\n`Struct` and `Parser` - where `Struct` represent an object with fields and a `Parser` is used to parse said\nfields from and into binary buffers; the package also includes some basic `Parser`s and `Struct`s which can\nbe dynamically built to fit the developer's needs.\n\n# Usage\n\n## Structs\n\nThe class `generic_struct.structs.Struct` is the basic protocol-handling class. it has members to represent the\ndifferent fields in the protocol and the API to write buffers from its fields and read its fields from buffers.\nAll protocol-handling classes created using `generic_struct` are derived from `Struct`.\n\nThe methods of `Struct`:\n* `get_buffer()` - create a binary buffer (a `bytes` object) representing the current fields of the struct\n* `read_buffer(buffer)` - read a binary buffer into the fields of the struct\n* `get_buffer_size()` - get the length of the corresponding binary buffer\n\n\n### How to create a `Struct` class\n\nThe current version includes two types of `Struct`s which can be created \n\n#### generic_struct.structs.GenericStruct\n\nThis type of `Struct` has fields of varying types and generates buffers using each field's \ncorresponding `Parser`.\n\nTo create a `Struct` of that type you can use the class-decorator `generic_struct.structs.GenericStruct.build_struct`:\n```python\nfrom generic_struct.structs.GenericStruct import build_struct\n\n@build_struct\nclass MyStruct():\n = \n = \n ...\n```\n\nobject of this type of `Struct` can be converted to `dict`\n\n\n#### generic_struct.structs.Flags\n\nThis type of `Struct` handles flags fields. Each field is a `bool` object and has a designated\nbit in the serialized buffer. \n\nA `Struct` of this type is created usnig the class-decorator `generic_struct.structs.Flags.build_flags`:\n\n```python\nfrom generic_struct.structs.Flags import build_flags\n\n@build_flags\nclass MyFlags():\n FIELDS = ['list', 'of', 'field', 'names']\n```\n\nWhere The first element in the FIELDS list is the most significant bit of the first byte in the buffer, and so on.\n\nTo have more control over the positions of the bits in the buffer, you can insert\n`generic_struct.structs.Flags.RESERVED` to represent one unused bit or `generic_struct.structs.Flags.ReservedBits(n)`\nto represent `n` unused bits. unused bits in the buffer are Always 0. \n\n```python\nfrom generic_struct.structs.Flags import build_flags, RESERVED, ReservedBits\n\n@build_flags\nclass MyFlags():\n FIELDS = [ReservedBits(5), 'some', 'bits', 'are', RESERVED , 'bits']\n```\n\nobject of this type of `Struct` can be converted to `dict`\n\n## Parsers\nA `Parser` class is responsible to converting between a specific `type` and a binary buffer in a specific way;\n_converting between `int` and an unsigned big-endian 4-bytes integer, for example._\n\n`Parser`s are mainly used in the creation of `Struct` classes.\n\nThe more complicated `Parser`s use other `Parser`s in order to do their work. \n\nThis package contains a bunch of common useful `Parser`s:\n\n|Parser |Supported Types |Buffer type |\n|------ |------ |----------- |\n|generic_struct.parsers.StaticField.StaticFieldParser|`int`, `bool`, `float`, `bytes`|simple conversion using the `struct` module|\n|generic_struct.parsers.StaticSizeBuffer.StaticSizeBufferParser|`str`|a buffer with a pre-determined size|\n|generic_struct.parsers.DynamicSizeBuffer.DynamicSizeBufferParser|`str`|length of the buffer, then the buffer|\n|generic_struct.parsers.StaticSizeList.StaticSizeListParser|`list`|every element of a pre-defined size list, parsed with a `Parser` for the elements|\n|generic_struct.parsers.DynamicSizeList.DynamicSizeListParser|`list`|length of the list, then the elements of the list|\n|generic_struct.parsers.DelimitedBuffer.DelimitedBufferParser|`str`|a buffer with a delimiter buffer/byte at its end|\n|generic_struct.parsers.DelimitedList.DelimitedListParser|`str`|a list with a delimiter object at its end|\n|generic_struct.parsers.StructParser|`Struct`|a parser for a specific type of `Struct`|\n|generic_struct.parsers.Union.UnionParser|any one of a list of `Struct`s|a number which defines the parsed type, then the parsed object|\n\n### generic_struct.parsers.StaticField.StaticFieldParser\nThe most simple `Parser` is ``. This `Parser` wraps the\nfunctionality of `struct.pack()` and `struct.unpack_from()`, although meant to handle mainly `int` and `float`.\n\nThe `generic_struct.parsers.StaticField` module also contains wrappers for the different types `StaticFieldParser`\ncan handle: `SignedIntFormats`, `UnsignedIntFormats`, `FloatFormats`, `CHAR_FORMAT`, and `BOOL_FORMAT`. \n\n_Example_: The parser `StaticFieldParser(SignedIntFormats.BE_DWORD)` would serialize `11` as `b'\\x00\\x00\\x00\\x11'`\n\n### generic_struct.parsers.StaticSizeBuffer.StaticSizeBufferParser\nThis parser packs a `str` into a buffer of a static size. Too short strings are padded with `b'\\x00'`.\nFor example, the string `'some txt'` will be converted to `b'some txt\\x00\\x00'`.\n\n**Note**: trailing `b'\\x00'`s are not automatically removed by `StaticSizeBufferParser.parse()`. The buffer \n`b'some txt\\x00\\x00'` is parsed as the string `'some txt\\x00\\x00'`. \n\n### generic_struct.parsers.DynamicSizeBuffer.DynamicSizeBufferParser\n\nThis parser packs a `str` into a dynamic sized buffer. The buffer begins with the length of the string, serialized\nby a `Parser` that can serialize the type `int`, and then the string itself.\n\n_Example_: the parser `DynamicSizeBufferParser(StaticFieldParser(UnsignedIntFormats.BYTE))` serializes the string\n`'some string'` as the buffer `b'\\x0bsome string'`, while the parser\n`DynamicSizeBufferParser(StaticFieldParser(UnsignedIntFormats.LE_DWORD))` serializes it as\n`b'\\x0b\\x00\\x00\\x00some string'` \n\n### generic_struct.parsers.StaticSizeList.StaticSizeListParser\n\nThis parser packs a static-sized `list` into a buffer, with the elements packed by a `Parser`\nthat can parse all the elements in the list.\n\n_Example_: the parser `StaticSizeListParser(element_parser=StaticFieldParser(SignedIntFormats.LE_WORD), size=3)`\nserializes the list `[3,-1,5]` as `b'\\x03\\x00\\xff\\xff\\x05\\x00'`\n\n### generic_struct.parsers.DynamicSizeList.DynamicSizeListParser\n\nThis parser packs a dynamic-sized list into a buffer similarly to\n`generic_struct.parsers.StaticSizeList.StaticSizeListParser`, except that the size of the list is added at the beginning\nof the buffer\n\n_Example_: the parser\n```\nDynamicSizeListParser(element_parser=StaticFieldParser(SignedIntFormats.LE_WORD),\n size_parser=StaticFieldParser(SignedIntFormats.BYTE))\n```\nserializes the list `[3,-1,5]` as `b'\\x03\\x03\\x00\\xff\\xff\\x05\\x00'`\n\n### generic_struct.parsers.DelimitedBuffer.DelimitedBufferParser\n\nThis parser packs a string as a buffer with a delimiter. The delimiter is a `bytes` of any length\n\n_Example_: the parser `DelimitedBufferParser(b'\\x93)` serializes the string `'some_string'` as `b'some_string\\x93'`\n\n### generic_struct.parsers.DelimitedList.DelimitedListParser\n\nThis parser packs a `list` as a buffer with a delimiter: The elements packed by a `Parser`\nthat can parse all the elements in the list, and then a delimiter with its own `Parser`\n\n_Example_: the parser\n```\nDelimitedListParser(element_parser=StaticFieldParser(SignedIntFormats.LE_WORD),\n delimiter=700,\n delimiter_parser=StaticFieldParser(UnsignedIntFormats.BE_DWORD))\n```\nserializes the list `[3,-1,5]` as `b'\\x03\\x00\\xff\\xff\\x05\\x00\\x00\\x00\\x02\\xbc'`\n\n### generic_struct.parsers.StructParser\n\nThis parser packs a child-class of `Struct`. it is useful when one wishes one of the fields in their `Struct` to be \na `Struct`. \n\n### generic_struct.parsers.Union.UnionParser\n\nThis parser packs one of a list of types, and adds a type identifier field packed with its own parser\nat the beginning of the buffer.\n\n_Example_: The parser\n```\nUnionParser(type_enum_parser=StaticFieldParser(UnsignedIntFormats.BYTE),\n type_parsers=[StaticFieldParser(FloatFormats.BE_QWORD),\n DelimitedBufferParser(b'\\x00')])\n```\n\nserializes:\n* `124.34` as `b'\\x00@_\\x15\\xc2\\x8f\\\\(\\xf6'`\n* `'some string'` as `b'\\x01some string\\x00'`\n\n\n## Example\n\n```python\nfrom generic_struct.parsers import StructParser\nfrom generic_struct.parsers.DelimitedBuffer import DelimitedBufferParser\nfrom generic_struct.parsers.DelimitedList import DelimitedListParser\nfrom generic_struct.parsers.DynamicSizeBuffer import DynamicSizeBufferParser\nfrom generic_struct.parsers.StaticField import StaticFieldParser, UnsignedIntFormats, CHAR_FORMAT\nfrom generic_struct.parsers.StaticSizeList import StaticSizeListParser\nfrom generic_struct.parsers.Union import UnionParser\nfrom generic_struct.structs.Flags import ReservedBits, build_flags\nfrom generic_struct.structs.GenericStruct import build_struct\n\n\n@build_flags\nclass MyFlags(object):\n FIELDS = [ReservedBits(5), 'bool_a', 'bool_b', 'bool_c']\n\n\n@build_struct\nclass MyStruct(object):\n word_int = StaticFieldParser(UnsignedIntFormats.BE_WORD)\n byte_int = DynamicSizeBufferParser(StaticFieldParser(UnsignedIntFormats.BYTE))\n delim_list = DelimitedListParser(element_parser=DelimitedBufferParser(b'::'),\n delimiter=b'$',\n delimiter_parser=StaticFieldParser(CHAR_FORMAT))\n union = UnionParser(StaticFieldParser(UnsignedIntFormats.BYTE),\n [StructParser(MyFlags),\n StaticSizeListParser(StaticFieldParser(UnsignedIntFormats.BE_DWORD), 4),\n DelimitedBufferParser(b';')])\n\n\ndef main():\n struct1 = MyStruct(word_int=4,\n byte_int='some_ string',\n delim_list=['some', 'list', 'of', 'strings'],\n union=MyFlags(bool_a=False, bool_b=False, bool_c=True))\n\n print('struct1:', dict(struct1))\n print('struct1.union:', dict(struct1.union))\n\n buffer1 = struct1.get_buffer()\n print('serialized:', buffer1)\n print()\n struct2 = MyStruct()\n struct2.read_buffer(buffer1)\n\n struct2.union = 'this is a string now'\n buffer2 = struct2.get_buffer()\n print('struct2:', dict(struct2))\n print('serialized:', buffer2)\n\n\nif __name__ == '__main__':\n main()\n```\n\nthe output would be:\n\n```\nstruct1: {'word_int': 4, 'byte_int': 'some_ string', 'delim_list': ['some', 'list', 'of', 'strings'], 'union': .Flags object at 0x03304810>}\nstruct1.union: {'bool_a': False, 'bool_b': False, 'bool_c': True}\nserialized: b'\\x00\\x04\\x0csome_ stringsome::list::of::strings::$\\x00\\x01'\n\nstruct2: {'word_int': 4, 'byte_int': 'some_ string', 'delim_list': ['some', 'list', 'of', 'strings'], 'union': 'this is a string now'}\nserialized: b'\\x00\\x04\\x0csome_ stringsome::list::of::strings::$\\x02this is a string now;'\n```\n\n", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "", "keywords": "", "license": "", "maintainer": "", "maintainer_email": "", "name": "generic-struct", "package_url": "https://pypi.org/project/generic-struct/", "platform": "", "project_url": "https://pypi.org/project/generic-struct/", "project_urls": null, "release_url": "https://pypi.org/project/generic-struct/1.0.2/", "requires_dist": null, "requires_python": ">=3.6", "summary": "A simple package to simplify conversion between binary data and python objects", "version": "1.0.2" }, "last_serial": 5927085, "releases": { "1.0.2": [ { "comment_text": "", "digests": { "md5": "40b6df79e8a999e872fa9f7e9aa7747d", "sha256": "bc69875aef84eb12fb0a30aac31b63c863dfda93dec239d75a876837b569cee0" }, "downloads": -1, "filename": "generic_struct-1.0.2-py3-none-any.whl", "has_sig": false, "md5_digest": "40b6df79e8a999e872fa9f7e9aa7747d", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=3.6", "size": 13660, "upload_time": "2019-10-04T07:33:12", "url": "https://files.pythonhosted.org/packages/a1/ef/f68dd4b351378476f01f07b036b838ffbddf2d18ffc266185aca146294d6/generic_struct-1.0.2-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "ee06074d61470860d0913be2473bdae6", "sha256": "87cac3c008e4a7604f34f89966f3dbad13e7b430d714e28ff27c0b21bd61bf4a" }, "downloads": -1, "filename": "generic-struct-1.0.2.tar.gz", "has_sig": false, "md5_digest": "ee06074d61470860d0913be2473bdae6", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.6", "size": 11841, "upload_time": "2019-10-04T07:33:14", "url": "https://files.pythonhosted.org/packages/1b/1a/c697792bf34d6692f0c24e23b0022914b21167ce4dd5f36d9836bffc82ca/generic-struct-1.0.2.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "40b6df79e8a999e872fa9f7e9aa7747d", "sha256": "bc69875aef84eb12fb0a30aac31b63c863dfda93dec239d75a876837b569cee0" }, "downloads": -1, "filename": "generic_struct-1.0.2-py3-none-any.whl", "has_sig": false, "md5_digest": "40b6df79e8a999e872fa9f7e9aa7747d", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=3.6", "size": 13660, "upload_time": "2019-10-04T07:33:12", "url": "https://files.pythonhosted.org/packages/a1/ef/f68dd4b351378476f01f07b036b838ffbddf2d18ffc266185aca146294d6/generic_struct-1.0.2-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "ee06074d61470860d0913be2473bdae6", "sha256": "87cac3c008e4a7604f34f89966f3dbad13e7b430d714e28ff27c0b21bd61bf4a" }, "downloads": -1, "filename": "generic-struct-1.0.2.tar.gz", "has_sig": false, "md5_digest": "ee06074d61470860d0913be2473bdae6", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.6", "size": 11841, "upload_time": "2019-10-04T07:33:14", "url": "https://files.pythonhosted.org/packages/1b/1a/c697792bf34d6692f0c24e23b0022914b21167ce4dd5f36d9836bffc82ca/generic-struct-1.0.2.tar.gz" } ] }