Framework

Namespace: exbip.framework

Descriptors

EndianPairDescriptor #

Instantiate this class to create an endian-aware descriptor.

Functions:

__init__(name, little_endian, big_endian):

When installed on a parser, this will create an operation called name that is set to the operation with name little_endian in little-endian mode and with name big_endian when in big-endian mode.

Parsers

IBinaryParser #

A base class for exbip parsers.

Descriptor Method: undefined

Additional Functions:

_get_rw_method(descriptor):

Pure virtual method. Must be implemented by an inheriting class. Intended to return a function on descriptor matching the theme of the parser.

global_seek(position):

Pure virtual method. Must be implemented by an inheriting class. Intended to set the stream offset to the given offset.

global_tell():

Pure virtual method. Must be implemented by an inheriting class. Intended to return the stream offset.

[classmethod] extended_with(descriptors, endian_inlined):

Returns a class derived from the current class that has the operators defined in descriptors defined on it, using the rw_method for that class. Also installs the endian-aware descriptors in endian_inlined.

execute_descriptor(descriptor, \*args, \*\*kwargs):

Fetches the required method from descriptor for this parser and executes it.

__call__(descriptor, \*args, \*\*kwargs):

Equal to execute_descriptor.

[staticmethod] bytes_to_alignment(position, alignment):

Calculates how many bytes are required to round position up to the nearest multiple of alignmente.

is_unaligned(alignment):

Returns True if the current stream position is not a multiple of alignment, else, False.

relative_global_seek(offset, base_position):

Seeks to offset + base_position relative to the stream origin.

seek(offset):

Seeks to offset relative to the context origin.

relative_seek(offset, base_position):

Seeks to offset + base_position relative to the context origin.

relative_global_tell(base_position):

Returns global_tell() - base_position.

tell():

Returns global_tell() relative to the context origin.

relative_tell(base_position):

Returns global_tell() - base_position relative to the context origin.

local_to_global_offset(offset):

Transforms offset from a local (context) offset to a global (stream) offset.

global_to_local_offset(offset):

Transforms offset from a global (stream) offset to a local (context) offset.

current_origin():

Returns the current stream position corresponding to the context origin.

push_origin(offset):

Sets offset as the current context origin.

pop_origin():

Restores the context origin to the previous context's origin.

new_origin():

Returns a context manager that will call push_origin when entered, and pop_origin when exited.

[property] endianness():

Returns the current context's endianness.

set_endianness(endianness):

Sets the current context's endianness. Valid values are '<' and '>'.

as_littleendian():

Returns a context manager that sets the context endianness to little endian for the scope of the context.

as_bigendian():

Returns a context manager that sets the context endianness to big endian for the scope of the context.

as_endian(endianness):

Returns a context manager that sets the context endianness to the provided endianness for the scope of the context. Valid values are '<', '>', 'little', and 'big'.

assert_equal(input_value, reference_value[, value_name=None, formatter=None]):

Throws an exception if input_value does not equal reference_value. The name of the value is included in the exception if it is not None, and formatter is used to format the values if it is not None.

ReaderBase #

Inherits from IBinaryParser . A base class for a parser that deserializes bytes to Python objects.

Descriptor Method: deserialize

Additional Functions:

FileIO(filepath):

Constructs the Reader with an io.BufferedReader stream context. Sets read_bytes to the read method of the stream.

BytestreamIO(initializer):

Constructs the Reader with an io.BytesIO stream context. Sets read_bytes to the read method of the stream.

_default_read_bytes(length):

The default function assigned to read_bytes when not in a stream context.

read_bytes(length):

A label that which the bytes-reading method of the stream is intended to be monkey-patched onto to avoid an extra attribute lookup and provide a unified API over different streams, i.e. rw.read_bytes vs. rw._bytestream.read.

peek_bytestring(length):

Reads up to length bytes from the stream without advancing the stream offset.

ValidatorBase #

Inherits from IBinaryParser . A base class for a parser that verifies whether two bytestreams deserialize to identical Python objects, and if not, to raises an error that originates at the first pair of read calls that deserialize to different values.

Descriptor Method: deserialize

Additional Functions:

PrimaryFileIO(filepath):

Constructs the Validator's primary stream with an io.BufferedReader stream context.

PrimaryBytestreamIO(initializer):

Constructs the Validator's primary stream with an io.BytesIO stream context.

ReferenceFileIO(filepath):

Constructs the Validator's reference stream with an io.BufferedReader stream context.

ReferenceBytestreamIO(initializer):

Constructs the Validator's reference stream with an io.BytesIO stream context.

_default_read_bytes(length):

The default function assigned to read_bytes when not in a stream context.

read_bytes(length):

A label that which the bytes-reading method of the stream is intended to be monkey-patched onto to avoid an extra attribute lookup and provide a unified API over different streams, i.e. rw.read_bytes vs. rw._bytestream.read.

peek_bytestring(length):

Reads up to length bytes from the stream without advancing the stream offset.

WriterBase #

Inherits from IBinaryParser . A base class for a parser that serializes Python objects to bytes.

Descriptor Method: serialize

Additional Functions:

FileIO(filepath):

Constructs the Writer with an io.BufferedReader stream context.

BytestreamIO(initializer):

Constructs the Writer with an io.BytesIO stream context.

write_bytes(length):

A label that which the bytes-reading method of the stream is intended to be monkey-patched onto to avoid an extra attribute lookup and provide a unified API over different streams, i.e. rw.write_bytes vs. rw._bytestream.write.

CounterBase #

Inherits from IBinaryParser . A base class for a parser that counts how many bytes a stream pointer will advance for each operator call.

Descriptor Method: count

Additional Functions:

advance_offset(value):

Increments the stream offset by value.

OffsetCalculatorBase #

Inherits from CounterBase . A base class for a parser that counts how many bytes a stream pointer will advance for each operator call, and using this calculates the value of stream-offset variables within a structure.

Descriptor Method: calculate_offsets if it exists. Else, count

Streams

ValidatorStream #

A stream used by ValidatorBase.

Functions:

set_primary_stream(stream):

Sets the primary stream of the ValidatorStream.

set_reference_stream(stream):

Sets the reference stream of the ValidatorStream.

close():

Closes the primary and reference streams, if they are not None.

seek(offset):

Seeks both the primary and reference streams to the given offset.

tell():

Returns the position of the primary stream, which should be synchronised with the reference stream.

read(count):

Reads count from both streams and raises a ValidationError if they are not equal.

write(data):

Raises NotImplementedError.