mrcrowbar.fields module¶

Definition classes for common fields in binary formats.

class mrcrowbar.fields.Bits(offset=<Chain>, bits=0, *, default=0, size=1, enum=None, endian=None, **kwargs)[source]¶

Bases: mrcrowbar.fields.NumberField

get_element_from_buffer(offset, buffer, parent=None, index=None)[source]¶

repr¶: Plaintext summary of the Field.

serialised¶: Tuple containing the contents of the Field.

update_buffer_with_element(offset, element, buffer, parent=None, index=None)[source]¶

validate_element(value, parent=None, index=None)[source]¶

class mrcrowbar.fields.Bits16(offset=<Chain>, bits=0, **kwargs)[source]¶: Bases: mrcrowbar.fields.Bits

class mrcrowbar.fields.Bits32(offset=<Chain>, bits=0, **kwargs)[source]¶: Bases: mrcrowbar.fields.Bits

class mrcrowbar.fields.Bits64(offset=<Chain>, bits=0, **kwargs)[source]¶: Bases: mrcrowbar.fields.Bits

class mrcrowbar.fields.Bits8(offset=<Chain>, bits=0, **kwargs)[source]¶: Bases: mrcrowbar.fields.Bits

class mrcrowbar.fields.BlockField(block_klass, offset=<Chain>, *, block_kwargs=None, count=None, fill=None, block_type=None, default_klass=None, length=None, stream=False, alignment=1, transform=None, stream_end=None, stop_check=None, **kwargs)[source]¶

Bases: mrcrowbar.fields.StreamField

Field for inserting another Block into the parent class.

block_klass: Block class to use, or a dict mapping between type and block class.
offset: Position of data, relative to the start of the parent block. Defaults to the end offset of the previous field.
block_kwargs: Arguments to be passed to the constructor of the block class.
count: Load multiple Blocks. None implies a single value, non-negative numbers will return a Python list.
fill: Exact byte sequence that denotes an empty entry in a list.
block_type: Key to use with the block_klass mapping. (Usually a Ref for a property on the parent block)
default_klass: Fallback Block class to use if there’s no match with the block_klass mapping.
length: Maximum size of the buffer to read in.
stream: Read Blocks continuously until a stop condition is met.
alignment: Number of bytes to align the start of each Block to.
transform: Transform class to use for preprocessing the data before importing or exporting each Block.
stream_end: Byte pattern to denote the end of the stream.
stop_check: A function that takes a data buffer and an offset; should return True if the end of the data stream has been reached and False otherwise.

get_element_from_buffer(offset, buffer, parent=None, index=None)[source]¶

get_element_size(element, parent=None, index=None)[source]¶

get_klass(parent=None)[source]¶

serialise(value, parent=None)[source]¶

Return a value as basic Python types.

value: Input Python object to process.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.

update_buffer_with_element(offset, element, buffer, parent=None, index=None)[source]¶

update_deps(value, parent=None)[source]¶

Update all dependent variables derived from the value of the Field.

value: Input Python object to process.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.

validate_element(element, parent=None, index=None)[source]¶

class mrcrowbar.fields.Bytes(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.StringField

class mrcrowbar.fields.CString(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.StringField

class mrcrowbar.fields.CStringN(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.StringField

class mrcrowbar.fields.Chunk[source]¶

Bases: mrcrowbar.fields.Chunk

Create new instance of Chunk(id, obj)

serialised¶: Tuple containing the contents of the Chunk.

mrcrowbar.fields.ChunkBase¶: alias of mrcrowbar.fields.Chunk

class mrcrowbar.fields.ChunkField(chunk_map, offset=<Chain>, *, count=None, length=None, stream=True, alignment=1, stream_end=None, stop_check=None, default_klass=None, id_size=None, id_field=None, id_enum=None, length_field=None, fill=None, **kwargs)[source]¶

Bases: mrcrowbar.fields.StreamField

Field for inserting a tokenised Block stream into the parent class.

chunk_map: A dict mapping between the chunk ID and the Block class to interpret the payload as.
offset: Position of data, relative to the start of the parent block. Defaults to the end offset of the previous field.
count: Load multiple chunks. None implies a single value, non-negative numbers will return a Python list.
length: Maximum size of the buffer to read in.
stream: Read elements continuously until a stop condition is met. Defaults to True.
alignment: Number of bytes to align the start of each Chunk to.
stream_end: Byte pattern to denote the end of the stream.
stop_check: A function that takes a data buffer and an offset; should return True if the end of the data stream has been reached and False otherwise.
default_klass: Fallback Block class to use if there’s no match with the chunk_map mapping.
id_size: Size in bytes of the Chunk ID.
id_field: Field class used to parse Chunk ID. Defaults to Bytes.
id_enum: Restrict allowed values for Chunk ID to those provided by a Python enum type. Used for validation.
length_field: Field class used to parse the Chunk data length. For use when a Chunk consists of an ID followed by the size of the data.
fill: Exact byte sequence that denotes an empty Chunk object.

get_element_from_buffer(offset, buffer, parent=None, index=None)[source]¶

get_element_size(element, parent=None, index=None)[source]¶

serialise(value, parent=None)[source]¶

Return a value as basic Python types.

value: Input Python object to process.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.

update_buffer_with_element(offset, element, buffer, parent=None, index=None)[source]¶

validate_element(element, parent=None, index=None)[source]¶

exception mrcrowbar.fields.EmptyFieldError[source]¶: Bases: Exception

class mrcrowbar.fields.Field(*, default=None, **kwargs)[source]¶

Bases: object

Base class for Fields.

default: Default value to emit in the case of e.g. creating an empty Block.

get_end_offset(value, parent=None, index=None)[source]¶

Return the end offset of the Field’s data. Useful for chainloading.

value: Input Python object to process.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.
index: Index of the Python object to measure from. Used if the Field takes a list of objects.

get_from_buffer(buffer, parent=None)[source]¶

Create a Python object from a byte string, using the field definition.

buffer: Input byte string to process.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.

get_path(parent=None, index=None)[source]¶

Return the location in the Block tree.

parent: Parent block object where this Field is defined.
index: Index into the value of the Field.

get_size(value, parent=None, index=None)[source]¶

Return the size of the Field’s data (in bytes).

value: Input Python object to process.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.
index: Index of the Python object to measure from. Used if the Field takes a list of objects.

get_start_offset(value, parent=None, index=None)[source]¶

Return the start offset of where the Field’s data is to be stored in the Block.

value: Input Python object to process.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.
index: Index of the Python object to measure from. Used if the Field takes a list of objects.

get_strict(parent=None)[source]¶

Return whether the parent Block is loading in strict mode.

parent: Parent block object where this Field is defined.

repr¶: Plaintext summary of the Field.

scrub(value, parent=None)[source]¶

Return the value coerced to the correct type of the Field (if necessary).

value: Input Python object to process.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.

Throws FieldValidationError if value can’t be coerced.

serialise(value, parent=None)[source]¶

Return a value as basic Python types.

value: Input Python object to process.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.

serialised¶: Tuple containing the contents of the Field.

update_buffer_with_value(value, buffer, parent=None)[source]¶

Write a Python object into a byte array, using the field definition.

value: Input Python object to process.
buffer: Output byte array to encode value into.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.

update_deps(value, parent=None)[source]¶

Update all dependent variables derived from the value of the Field.

value: Input Python object to process.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.

validate(value, parent=None)[source]¶

Validate that a correctly-typed Python object meets the constraints for the Field.

value: Input Python object to process.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.

Throws FieldValidationError if a constraint fails.

exception mrcrowbar.fields.FieldValidationError[source]¶: Bases: Exception

class mrcrowbar.fields.Float32_BE(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.Float32_LE(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.Float32_P(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.Float64_BE(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.Float64_LE(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.Float64_P(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.Int16_BE(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.Int16_LE(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.Int16_P(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.Int24_BE(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.Int24_LE(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.Int24_P(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.Int32_BE(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.Int32_LE(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.Int32_P(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.Int64_BE(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.Int64_LE(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.Int64_P(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.Int8(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.NumberField(format_type, field_size, signedness, endian, format_range, offset=<Chain>, *, default=0, count=None, length=None, stream=False, alignment=1, stream_end=None, stop_check=None, bitmask=None, range=None, enum=None, **kwargs)[source]¶

Bases: mrcrowbar.fields.StreamField

Base class for numeric value Fields.

format_type: Python native type equivalent. Used for validation. (Usually defined by child class)
field_size: Size of field in bytes. (Usually defined by child class)
signedness: Signedness of the field. Should be ‘signed’ or ‘unsigned’. (Usually defined by child class)
endian: Endianness of the field. Should be ‘little’, ‘big’ or None. (Usually defined by child class)
format_range: Numeric bounds of format. Used for validation. (Usually defined by child class)
offset: Position of data, relative to the start of the parent block. Defaults to the end offset of the previous field.
default: Default value to emit in the case of e.g. creating an empty Block.
count: Load multiple numbers. None implies a single value, non-negative numbers will return a Python list.
length: Maximum size of the buffer to read in.
stream: Read elements continuously until a stop condition is met.
alignment: Number of bytes to align the start of each element to.
stream_end: Byte pattern to denote the end of the stream.
stop_check: A function that takes a data buffer and an offset; should return True if the end of the data stream has been reached and False otherwise.
bitmask: Apply AND mask (bytes) to data before reading/writing. Used for demultiplexing data to multiple fields, e.g. one byte with 8 flag fields.
range: Restrict allowed values to a list of choices. Used for validation
enum: Restrict allowed values to those provided by a Python enum type. Used for validation.

get_element_from_buffer(offset, buffer, parent=None, index=None)[source]¶

get_element_size(element, parent=None, index=None)[source]¶

repr¶: Plaintext summary of the Field.

serialise(value, parent=None)[source]¶

Return a value as basic Python types.

value: Input Python object to process.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.

serialised¶: Tuple containing the contents of the Field.

update_buffer_with_element(offset, element, buffer, parent=None, index=None)[source]¶

update_deps(value, parent=None)[source]¶

Update all dependent variables derived from the value of the Field.

value: Input Python object to process.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.

validate_element(element, parent=None, index=None)[source]¶

class mrcrowbar.fields.PString(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.StringField

exception mrcrowbar.fields.ParseError[source]¶: Bases: Exception

class mrcrowbar.fields.StreamField(offset=<Chain>, *, default=None, count=None, length=None, stream=False, alignment=1, stream_end=None, stop_check=None, **kwargs)[source]¶

Bases: mrcrowbar.fields.Field

Base class for accessing one or more streamable elements.

offset: Position of data, relative to the start of the parent block. Defaults to the end offset of the previous field.
default: Default value to emit in the case of e.g. creating an empty Block.
count: Load multiple elements. None implies a single value, non-negative numbers will return a Python list.
length: Maximum size of the buffer to read in.
stream: Read elements continuously until a stop condition is met. Defaults to False.
alignment: Number of bytes to align the start of each element to.
stream_end: Byte pattern to denote the end of the stream.
stop_check: A function that takes a data buffer and an offset; should return True if the end of the data stream has been reached and False otherwise.

get_element_from_buffer(offset, buffer, parent=None, index=None)[source]¶

get_element_size(element, parent=None, index=None)[source]¶

get_from_buffer(buffer, parent=None)[source]¶

Create a Python object from a byte string, using the field definition.

buffer: Input byte string to process.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.

get_size(value, parent=None, index=None)[source]¶

Return the size of the Field’s data (in bytes).

value: Input Python object to process.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.
index: Index of the Python object to measure from. Used if the Field takes a list of objects.

get_start_offset(value, parent=None, index=None)[source]¶

Return the start offset of where the Field’s data is to be stored in the Block.

value: Input Python object to process.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.
index: Index of the Python object to measure from. Used if the Field takes a list of objects.

update_buffer_with_element(offset, element, buffer, parent=None, index=None)[source]¶

update_buffer_with_value(value, buffer, parent=None)[source]¶

Write a Python object into a byte array, using the field definition.

value: Input Python object to process.
buffer: Output byte array to encode value into.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.

update_deps(value, parent=None)[source]¶

Update all dependent variables derived from the value of the Field.

value: Input Python object to process.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.

validate(value, parent=None)[source]¶

Validate that a correctly-typed Python object meets the constraints for the Field.

value: Input Python object to process.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.

Throws FieldValidationError if a constraint fails.

validate_element(element, parent=None, index=None)[source]¶

class mrcrowbar.fields.StringField(offset=<Chain>, *, default=None, count=None, length=None, stream=False, alignment=1, stream_end=None, stop_check=None, transform=None, encoding=False, length_field=None, fill=None, element_length=None, element_end=None, zero_pad=False, **kwargs)[source]¶

Bases: mrcrowbar.fields.StreamField

Field class for string data.

offset: Position of data, relative to the start of the parent block. Defaults to the end offset of the previous field.
default: Default value to emit in the case of e.g. creating an empty block.
count: Load multiple strings. None implies a single value, non-negative numbers will return a Python list.
length: Maximum size of the buffer to read in.
stream: Read strings continuously until a stop condition is met. Defaults to False.
alignment: Number of bytes to align the start of the next element to.
stream_end: Byte string to indicate the end of the data.
stop_check: A function that takes a data buffer and an offset; should return True if the end of the data stream has been reached and False otherwise.
transform: Transform class to use for preprocessing the data before importing or exporting each string.
encoding: Python string encoding to use for output, as accepted by bytes.decode().
length_field: Field class used to parse the string length. For use when a string is preceded by the size.
fill: Exact byte sequence that denotes an empty entry in a list.
element_length: Length of each string element to load.
element_end: Byte string to indicate the end of a single string element.
zero_pad: Pad each element with zeros to match the length. Only for use with fixed length elements. The data size must be up to or equal to the length. Defaults to False.

get_element_from_buffer(offset, buffer, parent=None, index=None)[source]¶

get_element_size(element, parent=None, index=None)[source]¶

get_from_buffer(buffer, parent=None)[source]¶

Create a Python object from a byte string, using the field definition.

buffer: Input byte string to process.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.

get_start_offset(value, parent=None, index=None)[source]¶

Return the start offset of where the Field’s data is to be stored in the Block.

value: Input Python object to process.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.
index: Index of the Python object to measure from. Used if the Field takes a list of objects.

repr¶: Plaintext summary of the Field.

serialise(value, parent=None)[source]¶

Return a value as basic Python types.

value: Input Python object to process.
parent: Parent block object where this Field is defined. Used for e.g. evaluating Refs.

update_buffer_with_element(offset, element, buffer, parent=None, index=None)[source]¶

validate_element(element, parent=None, index=None)[source]¶

class mrcrowbar.fields.UInt16_BE(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.UInt16_LE(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.UInt16_P(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.UInt24_BE(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.UInt24_LE(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.UInt24_P(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.UInt32_BE(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.UInt32_LE(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.UInt32_P(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.UInt64_BE(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.UInt64_LE(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.UInt64_P(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField

class mrcrowbar.fields.UInt8(offset=<Chain>, **kwargs)[source]¶: Bases: mrcrowbar.fields.NumberField