Utilities for making binary parsers

BinaryParser

class satella.parsing.BinaryParser(b_stream, offset=0, length=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 (Union[bytes, bytearray]) – an object that allows subscripts to span ranges, which will return items parsable by struct

  • offset (int) – initial offset into the stream

  • length (Optional[int]) – 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)

Assert that we have at least n bytes to consume.

This does not advance the pointer.

Parameters:

n (int) – amount of bytes to consume

Raises:

NotEnoughBytes – not enough bytes remain in the stream!

Return type:

None

get_bytes(n)

Return this many bytes

Parameters:

n (int) – amount of bytes to return

Returns:

bytes returned

Raises:

NotEnoughBytes – not enough bytes remain in the stream!

Return type:

bytes

get_parser(length)

Return a subclassed binary parser providing a window to another binary parser’s data.

This will advance the pointer by length bytes

Parameters:

length (int) – amount of bytes to view

Returns:

a BinaryParser

Raises:

NotEnoughBytes – not enough bytes remain in the stream!

Return type:

BinaryParser

get_remaining_bytes()

Return the remaining bytes.

This will not advance the pointer

Return type:

Union[bytes, bytearray]

get_remaining_bytes_count()

Return the amount of bytes remaining. This will not advance the pointer

Return type:

int

get_struct(st)

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 (Union[str, Struct]) – 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!

Return type:

Union[int, float]

get_structs(st)

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 (Union[str, Struct]) – 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!

Return type:

Tuple[Union[int, float], …]

reset()

Reset the internal pointer to starting value :return:

Return type:

None

skip(n)

Advance the pointer by n bytes

Parameters:

n (int) – bytes to advance

Raises:

NotEnoughBytes – not enough bytes remain in the stream!

Return type:

None

NotEnoughBytes

class satella.exceptions.NotEnoughBytes(*args, **kwargs)

Not enough bytes in the parser remain to satisfy this request