mrcrowbar.blocks module

Definition classes for data blocks.

class mrcrowbar.blocks.Block(source_data=None, *, parent=None, preload_attrs=None, endian=None, cache_bytes=False, path_hint=None, strict=False)

Bases: object

Base class for Blocks.

source_data

Source data to construct Block with. Can be a byte string, dictionary of attribute: value pairs, or another Block object.

parent

Parent Block object where this Block is defined. Used for e.g. evaluating Refs.

preload_attrs

Attributes on the Block to set before importing the data. Used for linking in dependencies before loading.

endian

Platform endianness to use when interpreting the Block data. Useful for Blocks which have the same data layout but different endianness for stored numbers. Has no effect on fields with an predefined endianness.

cache_bytes

Cache the bytes equivalent of the Block. Useful for debugging the loading procedure. Defaults to False.

path_hint

Cache a string containing the path of the current Block, relative to the root.

strict

Throw an exception if parsing a BlockField fails, instead of logging a warning and returning an Unknown. Defaults to False.

clone_data(source)

Clone data from another Block.

source

Block instance to copy from.

diffdump(target, prefix='source', depth=None)

Find differences between this Block and another.

target

The second Block.

prefix

The name of the base element to display.

depth

Maximum number of levels to traverse.

dump()

Export data to a byte array.

export_data()

Export data to a byte array.

get_field_end_offset(field_name, index=None)

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

field_name

Name of the Field to inspect.

index

Index of the Python object to measure from. Used if the Field takes a list of objects.

get_field_name_by_obj(field)

Return a name associated with a Field object in this Block class.

field

Field object on the object to reference.

get_field_names()

Get the list of Fields associated with this Block class.

get_field_obj(field_name)

Return a Field object associated with this Block class.

field_name

Name of the Field.

get_field_path(field)

Return the path of this Block and a child Field in the current object tree.

Used for error messages.

field

Field object on the object to reference.

get_field_size(field_name, index=None)

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

field_name

Name of the Field to inspect.

index

Index of the Python object to measure from. Used if the Field takes a list of objects.

get_field_start_offset(field_name, index=None)

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

field_name

Name of the Field to inspect.

index

Index of the Python object to measure from. Used if the Field takes a list of objects.

get_path()

Return the path of this Block in the current object tree.

Used for error messages.

get_size()

Get the projected size (in bytes) of the exported data from this Block instance.

hexdump(start=None, end=None, length=None, major_len=8, minor_len=4, colour=True, address_base=None, show_offsets=True, show_glyphs=True)

Print the exported data in tabular hexadecimal/ASCII format.

start

Start offset to read from (default: start)

end

End offset to stop reading at (default: end)

length

Length to read in (optional replacement for end)

major_len

Number of hexadecimal groups per line

minor_len

Number of bytes per hexadecimal group

colour

Add ANSI colour formatting to output (default: true)

address_base

Base address to use for labels (default: start)

show_offsets

Display offsets at the start of each line (default: true)

show_glyphs

Display glyph map at the end of each line (default: true)

Raises ValueError if both end and length are defined.

histdump(start=None, end=None, length=None, samples=65536, width=64, address_base=None)

Print the histogram of the exported data.

start

Start offset to read from (default: start)

end

End offset to stop reading at (default: end)

length

Length to read in (optional replacement for end)

samples

Number of samples per histogram slice (default: 0x10000)

width

Width of rendered histogram (default: 64)

address_base

Base address to use for labelling (default: start)

import_data(raw_buffer)

Import data from a byte array.

raw_buffer

Byte array to import from.

load(raw_buffer)

Import data from a byte array.

raw_buffer

Byte array to import from.

repr

Plaintext summary of the Block.

scrub_field(field_name)

Return a Field’s data coerced to the correct type (if necessary).

field_name

Name of the Field to inspect.

Throws FieldValidationError if value can’t be coerced.

search(pattern, encoding='utf8', fixed_string=False, hex_format=False, ignore_case=False)

Find the Fields that match a byte pattern.

pattern

Pattern to match, as a Python string

encoding

Convert strings in the pattern to a specific Python encoding (default: utf8)

fixed_string

Interpret the pattern as a fixed string (disable regular expressions)

hex_format

Interpret the pattern as raw hexidecimal (default: false)

ignore_case

Perform a case-insensitive search

serialised

Tuple containing the contents of the Block.

update_data(source)

Update data from a dictionary.

source

Dictionary of attribute: value pairs.

update_deps()

Update dependencies on all the fields on this Block instance.

update_deps_on_check(check_name)

Update all dependent variables derived from a Check.

check_name

Name of the Check to inspect.

update_deps_on_field(field_name)

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

field_name

Name of the Field to inspect.

validate()

Validate all the fields on this Block instance.

validate_field(field_name)

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

field_name

Name of the Field to inspect.

Throws FieldValidationError if a constraint fails.

class mrcrowbar.blocks.BlockMeta

Bases: type

Metaclass for Block which detects and wraps attributes from the class definition.

checks

fields

refs

class mrcrowbar.blocks.FieldDescriptor(name)

Bases: object

Attribute wrapper class for Fields.

name

Name of the Field.

class mrcrowbar.blocks.RefDescriptor(name)

Bases: object

Attribute wrapper class for Refs.

name

Name of the Ref.

class mrcrowbar.blocks.Unknown(source_data=None, *, parent=None, preload_attrs=None, endian=None, cache_bytes=False, path_hint=None, strict=False)

Bases: mrcrowbar.blocks.Block

Base class for Blocks.

source_data

Source data to construct Block with. Can be a byte string, dictionary of attribute: value pairs, or another Block object.

parent

Parent Block object where this Block is defined. Used for e.g. evaluating Refs.

preload_attrs

Attributes on the Block to set before importing the data. Used for linking in dependencies before loading.

endian

Platform endianness to use when interpreting the Block data. Useful for Blocks which have the same data layout but different endianness for stored numbers. Has no effect on fields with an predefined endianness.

cache_bytes

Cache the bytes equivalent of the Block. Useful for debugging the loading procedure. Defaults to False.

path_hint

Cache a string containing the path of the current Block, relative to the root.

strict

Throw an exception if parsing a BlockField fails, instead of logging a warning and returning an Unknown. Defaults to False.

data = <Bytes: offset=0x0>

Raw data.