{ "info": { "author": "Cameron Simpson", "author_email": "cs@cskk.id.au", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "Environment :: Console", "Intended Audience :: Developers", "License :: OSI Approved :: GNU General Public License v3 (GPLv3)", "Operating System :: OS Independent", "Programming Language :: Python :: 3", "Topic :: Software Development :: Libraries :: Python Modules" ], "description": "Facilities associated with binary data parsing and transcription.\n\nNote: this module requires Python 3 and recommends Python 3.6+\nbecause it uses abc.ABC, because a Python 2 bytes object is too\nweak (just a str) as also is my cs.py3.bytes hack class and\nbecause the keyword based Packet initiialisation benefits from\nkeyword argument ordering.\n\nIn the description below I use the word \"chunk\" to mean a piece\nof binary data obeying the buffer protocol, almost always a\n`bytes` instance or a `memoryview`, but in principle also things\nlike `bytearray`.\n\nThe classes in this module support easy parsing of binary data\nstructures.\n\nThe functions and classes in this module include:\n* `PacketField`: an abstract class for a binary field, with a\n factory method to parse it, a transcription method to transcribe\n it back out in binary form and usually a `.value` attribute\n holding the parsed value.\n* several presupplied subclasses for common basic types such\n as `UInt32BE` (an unsigned 32 bit big endian integer).\n* `struct_field`: a factory for making PacketField classes for\n `struct` formats with a single value field.\n* `multi_struct_field` and `structtuple`: factories for making\n `PacketField`s from `struct` formats with multiple value\n fields;\n `structtuple` makes `PacketFields` which are also `namedtuple`s,\n supporting trivial access to the parsed values.\n* `Packet`: a `PacketField` subclass for parsing multiple\n `PacketFields` into a larger structure with ordered named\n fields.\n The fields themselves may be `Packet`s for complex structures.\n\nYou don't need to make fields only from binary data; because\n`PacketField.__init__` takes a post parse value, you can also\nconstruct `PacketField`s from scratch with their values and\ntranscribe the resulting binary form.\n\nEach `PacketField` subclass has the following methods:\n* `transcribe`: easily return the binary transcription of this field,\n either directly as a chunk (or for convenience, also None or\n an ASCII str) or by yielding successive binary data.\n* `from_buffer`: a factory to parse this field from a\n `cs.buffer.CornuCopyBuffer`.\n* `from_bytes`: a factory to parse this field from a chunk with\n an optional starting offset; this is a convenience wrapper for\n `from_buffer`.\n\nThat may sound a little arcane, but we also supply:\n* `flatten`: a recursive function to take the return from any\n `transcribe` method and yield chunks, so copying a packet to\n a file or elsewhere can always be done by iterating over\n `flatten(field.transcribe())` or via the convenience\n `field.transcribe_flat()` method which calls `flatten` itself.\n* a `CornuCopyBuffer` is an easy to use wrapper for parsing any\n iterable of chunks, which may come from almost any source.\n It has a bunch of convenient factories including:\n `from_bytes`, make a buffer from a chunk;\n `from_fd`, make a buffer from a file descriptor;\n `from_file`, make a buffer from a file-like object;\n `from_mmap`, make a buffer from a file descriptor using a\n memory map (the `mmap` module) of the file, so that chunks\n can use the file itself as backing store instead of allocating\n and copying memory.\n See the `cs.buffer` module for further detail.\n\nWhen parsing a complex structure\none must choose between subclassing `PacketField` or `Packet`.\nAn effective guideline is the degree of substructure.\n\nA `Packet` is designed for deeper structures;\nall of its attributes are themselves `PacketField`s\n(or `Packets`, which are `PacketField` subclasses).\nThe leaves of this hierarchy will be `PacketFields`,\nwhose attributes are ordinary types.\n\nBy contrast, a `PacketField`'s attributes are \"flat\" values:\nthe plain post-parse value, such as a `str` or an `int`\nor some other conventional Python type.\n\nThe base case for `PacketField`\nis a single such value, named `.value`,\nand the natural implementation\nis to provide a `.value_from_buffer` method\nwhich returns the basic single value\nand the corresponding `.transcribe_value` method\nto return or yield its binary form\n(directly or in pieces respectively).\n\nHowever,\nyou can handle multiple attributes with this class\nby instead implementing:\n* `__init__`: to compose an instance from post-parse values\n (and thus from scratch rather than parsed from existing binary data)\n* `from_buffer`: class method to parse the values\n from a ` CornuCopyBuffer` and call the class constructor\n* `transcribe`: to return or yield the binary form of the attributes\n\nCameron Simpson 22jul2018\n\n## Class `BSData`\n\nMRO: `PacketField`, `abc.ABC` \nA run length encoded data chunk, with the length encoded as a BSUInt.\n\n## Class `BSSFloat`\n\nMRO: `PacketField`, `abc.ABC` \nA float transcribed as a BSString of str(float).\n\n## Class `BSString`\n\nMRO: `PacketField`, `abc.ABC` \nA run length encoded string, with the length encoded as a BSUInt.\n\n## Class `BSUInt`\n\nMRO: `PacketField`, `abc.ABC` \nA binary serialsed unsigned int.\n\nThis uses a big endian byte encoding where continuation octets\nhave their high bit set. The bits contributing to the value\nare in the low order 7 bits.\n\n## Class `BytesesField`\n\nMRO: `PacketField`, `abc.ABC` \nA field containing a list of bytes chunks.\n\nThe following attributes are defined:\n* `value`: the gathered data as a list of bytes instances,\n or None if the field was gathered with `discard_data` true.\n* `offset`: the starting offset of the data.\n* `end_offset`: the ending offset of the data.\n\nThe `offset` and `end_offset` values are recorded during the\nparse, and may become irrelevant if the field's contents are\nchanged.\n\n## Class `BytesField`\n\nMRO: `PacketField`, `abc.ABC` \nA field of bytes.\n\n## Class `BytesRunField`\n\nMRO: `PacketField`, `abc.ABC` \nA field containing a continuous run of a single bytes value.\n\nThe following attributes are defined:\n* `length`: the length of the run\n* `bytes_value`: the repeated bytes value\n\nThe property `value` is computed on the fly on every reference\nand returns a value obeying the buffer protocol: a bytes or\nmemoryview object.\n\n## Class `EmptyPacketField`\n\nMRO: `PacketField`, `abc.ABC` \nAn empty data field, used as a placeholder for optional\nfields when they are not present.\n\nThe singleton `EmptyField` is a predefined instance.\n\n## Function `fixed_bytes_field(length, class_name=None)`\n\nFactory for BytesField subclasses built from fixed length byte strings.\n\n## Function `flatten(chunks)`\n\nFlatten `chunks` into an iterable of `bytes` instances.\n\nThis exists to allow subclass methods to easily return ASCII\nstrings or bytes or iterables or even `None`, in turn allowing\nthem simply to return their superclass' chunks iterators\ndirectly instead of having to unpack them.\n\n## Class `Float64BE`\n\nMRO: `PacketField`, `abc.ABC` \nA PacketField which parses and transcribes the struct format `'>d'`.\n\n## Class `Float64LE`\n\nMRO: `PacketField`, `abc.ABC` \nA PacketField which parses and transcribes the struct format `'h'`.\n\n## Class `Int16LE`\n\nMRO: `PacketField`, `abc.ABC` \nA PacketField which parses and transcribes the struct format `'l'`.\n\n## Class `Int32LE`\n\nMRO: `PacketField`, `abc.ABC` \nA PacketField which parses and transcribes the struct format `'>> UInt16BE = struct_field('>H', class_name='UInt16BE')\n >>> UInt16BE.__name__\n 'UInt16BE'\n >>> UInt16BE.format\n '>H'\n >>> UInt16BE.struct #doctest: +ELLIPSIS\n \n >>> field, offset = UInt16BE.from_bytes(bytes((2,3,4)))\n >>> field\n UInt16BE(515)\n >>> offset\n 2\n >>> field.value\n 515\n\n## Function `structtuple(class_name, struct_format, subvalue_names)`\n\nConvenience wrapper for multi_struct_field.\n\n## Class `UInt16BE`\n\nMRO: `PacketField`, `abc.ABC` \nA PacketField which parses and transcribes the struct format `'>H'`.\n\n## Class `UInt16LE`\n\nMRO: `PacketField`, `abc.ABC` \nA PacketField which parses and transcribes the struct format `'L'`.\n\n## Class `UInt32LE`\n\nMRO: `PacketField`, `abc.ABC` \nA PacketField which parses and transcribes the struct format `'Q'`.\n\n## Class `UInt64LE`\n\nMRO: `PacketField`, `abc.ABC` \nA PacketField which parses and transcribes the struct format `'