Utilities for making binary parsers¶
BinaryParser¶
-
class
satella.parsing.BinaryParser(b_stream: Union[bytes, bytearray], offset: int = 0, length: Optional[int] = None)¶ A class that allows parsing binary streams easily.
This supports __len__ to return the amount of bytes in the stream, and __bytes__ to return the bytes.
This is a zero-copy solution, and
get_parser()will be zero copy as well.Parameters: - b_stream – an object that allows subscripts to span ranges, which will return items parsable by struct
- offset – initial offset into the stream
- length – optional maximum length of byte count
Raises: NotEnoughBytes – offset larger than stream length
Variables: pointer – pointer to the next bytes. Can be read and modified at will to preserve the earlier state of the BinaryParser.
-
assert_has_bytes(n: int) → None¶ Assert that we have at least n bytes to consume.
This does not advance the pointer.
Parameters: n – amount of bytes to consume Raises: NotEnoughBytes – not enough bytes remain in the stream!
-
get_bytes(n: int) → bytes¶ Return this many bytes
Parameters: n – amount of bytes to return Returns: bytes returned Raises: NotEnoughBytes – not enough bytes remain in the stream!
-
get_parser(length: int) → satella.parsing.BinaryParser¶ Return a subclassed binary parser providing a window to another binary parser’s data.
This will advance the pointer by length bytes
Parameters: length – amount of bytes to view Returns: a BinaryParser Raises: NotEnoughBytes – not enough bytes remain in the stream!
-
get_remaining_bytes() → Union[bytes, bytearray]¶ Return the remaining bytes.
This will not advance the pointer
-
get_remaining_bytes_count() → int¶ Return the amount of bytes remaining. This will not advance the pointer
-
get_struct(st: Union[str, Struct]) → Union[int, float]¶ Try to obtain as many bytes as this struct requires and return them parsed.
This must be a single-character struct!
This will advance the pointer by size of st. Struct objects will be served from internal instance-specific cache.
Parameters: st – a single-character struct.Struct or a single character struct specification
Returns: a value returned from it
Raises: - NotEnoughBytes – not enough bytes remain in the stream!
- AssertionError – struct was not a single element one!
-
get_structs(st: Union[str, Struct]) → Tuple[Union[int, float], ...]¶ Try to obtain as many bytes as this struct requires and return them parsed.
This will advance the pointer by size of st. Struct objects will be served from internal instance-specific cache.
Parameters: st – a struct.Struct or a multi character struct specification Returns: a tuple of un-parsed values Raises: NotEnoughBytes – not enough bytes remain in the stream!
-
reset() → None¶ Reset the internal pointer to starting value :return:
-
skip(n: int) → None¶ Advance the pointer by n bytes
Parameters: n – bytes to advance Raises: NotEnoughBytes – not enough bytes remain in the stream!