Utilities for making binary parsers¶
BinaryParser¶
- class satella.parsing.BinaryParser(b_stream: bytes | bytearray, offset: int = 0, length: int | None = 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) 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() 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: str | Struct) 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: str | Struct) Tuple[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!
NotEnoughBytes¶
- class satella.exceptions.NotEnoughBytes(*args, **kwargs)¶
Not enough bytes in the parser remain to satisfy this request