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