RawFile#

class hexrec.formats.raw.RawFile[source]#

Raw binary file object.

Attributes

`DEFAULT_DATALEN`	Default data attribute length.
`FILE_EXT`	Supported filename extensions.
`META_KEYS`	Meta information key names.
`maxdatalen`	Maximum byte size of the data field.
`memory`	Memory object stored by records role.
`records`	Records stored by records role.

Methods

`__init__`
`align`	Pads blocks to align their boundaries.
`append`	Appends a byte.
`apply_records`	Applies records to memory and meta.
`clear`	Clears data within a range.
`convert`	Converts a file object to another format.
`copy`	Copies within a range.
`crop`	Clears data outside a range.
`cut`	Cuts data within a range.
`delete`	Deletes data within a range.
`discard_memory`	Discards underlying memory.
`discard_records`	Discards underlying records.
`extend`	Concatenates data.
`fill`	Fills a range.
`find`	Finds a substring.
`flood`	Floods a range.
`from_blocks`	Creates a file object from a memory object.
`from_bytes`	Creates a file object from a byte string.
`from_memory`	Creates a file object from a memory object.
`from_records`	Creates a file object from records.
`get_address_max`	Maximum address within memory.
`get_address_min`	Minimum address within memory.
`get_holes`	List of memory holes.
`get_meta`	Meta information.
`get_spans`	List of memory block spans.
`index`	Finds a substring.
`load`	Loads a file object from the filesystem.
`merge`	Merges data onto the file.
`parse`	Parses records from a byte stream.
`print`	Prints record content to stdout.
`read`	Extracts a substring.
`save`	Saves a file object into the filesystem.
`serialize`	Serializes records onto a byte stream.
`set_meta`	Sets meta information.
`shift`	Shifts data addresses by an offset.
`split`	Splits into parts.
`update_records`	Applies memory and meta to records.
`validate_records`	Validates records.
`view`	Memory view.
`write`	Writes data into the file.

DEFAULT_DATALEN: int = 9223372036854775807#

Default data attribute length.

Default value for the maxdatalen meta, which sets the maximum size of BaseRecord.data field values.

FILE_EXT: Sequence[str] = ['.bin', '.dat', '.eep', '.raw']#

Supported filename extensions.

Sequence of file name extension substrings (e.g. .hex). This list is used by functions like guess_format_name() to manage mapping of file formats.

META_KEYS: Sequence[str] = ['maxdatalen']#

Meta information key names.

Sequence of key strings listing the supported meta information of this file format.

Record#: alias of RawRecord

__add__(other)#

Concatenates with another file.

Equivalent to copy() then extend().

Parameters:: other (BaseFile or bytes) – Other file or bytes to concatenate.
Returns:: BaseFile – Concatenation of self and other.

See also

copy() extend()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file1 = SrecFile.from_bytes(b'abc', offset=123)
>>> file2 = SrecFile.from_bytes(b'xyz', offset=456)
>>> file3 = file1 + file2
>>> file3.memory.to_blocks()
[[123, b'abc'], [582, b'xyz']]
>>> file4 = file3 + b'789'
>>> file4.memory.to_blocks()
[[123, b'abc'], [582, b'xyz789']]

__bool__()#

bool: Has data records or memory.

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import IhexFile
>>> file = IhexFile()
>>> bool(file)
False
>>> _ = file.append(0)
>>> bool(file)
True

>>> from hexrec import IhexFile
>>> IhexRecord = IhexFile.Record
>>> file = IhexFile.from_records([IhexRecord.create_end_of_file()])
>>> bool(file)
False
>>> file.records.insert(0, IhexRecord.create_data(0, b'\0'))
>>> bool(file)
True

__delitem__(key)#

Deletes a range.

Parameters:: key (slice or int) – Range to delete.

See also

bytesparse.base.MutableMemory.__delitem__()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file = SrecFile.from_blocks([[123, b'abc'], [456, b'xyz']])
>>> del file[457]
>>> file.memory.to_blocks()
[[123, b'abc'], [456, b'xz']]
>>> del file[125:457]
>>> file.memory.to_blocks()
[[123, b'abz']]

__eq__(other)#

Equality test.

The file objects self and other are considered equal if the inequality tests of __ne__() result false.

Returns:: bool – self and other are equal.

See Also: __ne__()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file1 = SrecFile.from_bytes(b'abc', offset=123)
>>> file2 = SrecFile.from_bytes(b'abc', offset=123)
>>> file1 is file2
False
>>> file1 == file2
True
>>> file3 = SrecFile.from_bytes(b'xyz', offset=123)
>>> file1 == file3
False
>>> file4 = SrecFile.from_bytes(b'abc', offset=456)
>>> file1 == file4
False

>>> from hexrec import SrecFile, IhexFile
>>> srec_file = SrecFile.from_bytes(b'abc', offset=123)
>>> ihex_file = IhexFile.from_bytes(b'abc', offset=123)
>>> srec_file == ihex_file
False
>>> srec_file.memory == ihex_file.memory
True
>>> set(srec_file.META_KEYS) - set(ihex_file.META_KEYS)
{'header'}

__getitem__(key)#

Extracts a range.

Parameters:: key (slice or int) – Range to extract.
Raises:: ValueError – invalid range.

See also

bytesparse.base.ImmutableMemory.__getitem__()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file = SrecFile.from_blocks([[123, b'abc'], [456, b'xyz']])
>>> chr(file[457])
'y'
>>> repr(file[333])
'None'
>>> file[123:125]
b'ab'
>>> file[125:457]
Traceback (most recent call last):
    ...
ValueError: non-contiguous data within range

__hash__ = None#

__iadd__(other)#

Concatenates data.

Equivalent to extend().

It concatenates other to the underlyng memory.

Any stored records are discarded upon return.

Parameters:: other (BaseFile or bytes) – Other file or bytes to concatenate.
Returns:: BaseFile – self.

See also

memory extend() discard_records() bytesparse.base.MutableMemory.extend()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file1 = SrecFile.from_bytes(b'abc', offset=123)
>>> file2 = SrecFile.from_bytes(b'xyz', offset=456)
>>> file1 += file2
>>> file1.memory.to_blocks()
[[123, b'abc'], [582, b'xyz']]
>>> file1 += b'789'
>>> file1.memory.to_blocks()
[[123, b'abc'], [582, b'xyz789']]

__init__()#

__ior__(other)#

Merges with another file.

Equivalent to merge().

Any stored records are discarded upon return.

Parameters:: other (BaseFile or bytes) – Other file or bytes to merge.
Returns:: BaseFile – self.

See also

merge() discard_records()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file1 = SrecFile.from_bytes(b'abc', offset=123)
>>> file2 = SrecFile.from_bytes(b'xyz', offset=456)
>>> file1 |= file2
>>> file1.memory.to_blocks()
[[123, b'abc'], [456, b'xyz']]
>>> file1 |= b'789'
>>> file1.memory.to_blocks()
[[0, b'789'], [123, b'abc'], [456, b'xyz']]

__ne__(other)#

Inequality test.

The file objects self and other are considered unequal if any of the following tests result true:

Both have memory role (i.e. memory), resulting unequal;
Both have records role (i.e. records), resulting unequal;
other does not have a meta listed by META_KEYS;
A meta value (among those of META_KEYS) is different.

Returns:: bool – self and other are unequal.

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file1 = SrecFile.from_bytes(b'abc', offset=123)
>>> file2 = SrecFile.from_bytes(b'abc', offset=123)
>>> file1 is file2
False
>>> file1 != file2
False
>>> file3 = SrecFile.from_bytes(b'xyz', offset=123)
>>> file1 != file3
True
>>> file4 = SrecFile.from_bytes(b'abc', offset=456)
>>> file1 != file4
True

>>> from hexrec import SrecFile, IhexFile
>>> srec_file = SrecFile.from_bytes(b'abc', offset=123)
>>> ihex_file = IhexFile.from_bytes(b'abc', offset=123)
>>> srec_file != ihex_file
True
>>> srec_file.memory != ihex_file.memory
False
>>> set(srec_file.META_KEYS) - set(ihex_file.META_KEYS)
{'header'}

__or__(other)#

Merges with another file.

Equivalent to copy() then merge().

Parameters:: other (BaseFile or bytes) – Other file or bytes to merge.
Returns:: BaseFile – self merged with other.

See also

copy() merge()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file1 = SrecFile.from_bytes(b'abc', offset=123)
>>> file2 = SrecFile.from_bytes(b'xyz', offset=456)
>>> file3 = file1 | file2
>>> file3.memory.to_blocks()
[[123, b'abc'], [456, b'xyz']]
>>> file4 = file3 | b'789'
>>> file4.memory.to_blocks()
[[0, b'789'], [123, b'abc'], [456, b'xyz']]

__setitem__(key, value)#

Sets a range.

Parameters:

key (slice or int) – Range to set.
value (bytes, bytesparse.base.ImmutableMemory, None) – Value(s) to set. None acts like clear().

Raises:

ValueError – invalid range.

See also

bytesparse.base.MutableMemory.__setitem__() clear()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file = SrecFile.from_blocks([[123, b'abc'], [456, b'xyz']])
>>> file[124] = b'?'
>>> file.memory.to_blocks()
[[123, b'a?c'], [456, b'xyz']]
>>> file[:125] = None
>>> file.memory.to_blocks()
[[125, b'c'], [456, b'xyz']]
>>> file[457:458] = b'789'
>>> file.memory.to_blocks()
[[125, b'c'], [456, b'x789z']]

__weakref__#: list of weak references to the object (if defined)

classmethod _is_line_empty(line)[source]#

Empty line check.

Tells whether a line has no meaningful content (e.g. all whitespace). The check itself depends on the implementing file format. It may be used internally to skip empty lines, e.g. by parse().

Parameters:: line (bytes) – A line, byte string.
Returns:: bool: The line is empty.

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import IhexFile
>>> IhexFile._is_line_empty(b'')
True
>>> IhexFile._is_line_empty(b' \t\v\r\n')
True
>>> IhexFile._is_line_empty(b':00000001FF\r\n')
False

align(modulo, start=None, endex=None, pattern=0)#

Pads blocks to align their boundaries.

It fills memory holes of the underlying memory within the specified range with a pattern, so that memory blocks are aligned to the required modulo.

Any stored records are discarded upon return.

Parameters:

modulo (int) – Alignment modulo.
start (int) – Inclusive start address of the specified range. If None, start from the beginning of the memory.
endex (int) – Exclusive end address of the specified range. If None, extend after the end of the memory.
pattern (bytes or int) – Byte pattern for flooding.

Returns:

BaseFile – self.

See also

memory discard_records() bytesparse.base.MutableMemory.align()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file = SrecFile.from_blocks([[123, b'abc'], [134, b'xyz']])
>>> _ = file.align(4, pattern=b'.')
>>> file.memory.to_blocks()
[[120, b'...abc..'], [132, b'..xyz...']]

append(item)#

Appends a byte.

It appends the item to the underlyng memory.

Any stored records are discarded upon return.

Parameters:: item (byte or int) – Byte to append.
Returns:: BaseFile – self.

See also

memory discard_records() bytesparse.base.MutableMemory.append()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file = SrecFile.from_bytes(b'abc', offset=123)
>>> _ = file.append(b'.')
>>> _ = file.append(0)
>>> file.memory.to_blocks()
[[123, b'abc.\x00']]

apply_records()#

Applies records to memory and meta.

This method processes the stored records, converting data as memory, and special records into their meta counterparts.

This effectively converts the records role into the memory role (keeping both).

The memory and meta are assigned upon return. Any exceptions being raised should not alter the file object.

Returns:: BaseFile – self.
Raises:: ValueError – records attribute not populated.

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import IhexFile
>>> IhexRecord = IhexFile.Record
>>> records = [IhexRecord.create_data(123, b'abc'),
...            IhexRecord.create_start_linear_address(456),
...            IhexRecord.create_end_of_file()]
>>> file = IhexFile.from_records(records, maxdatalen=16)
>>> _ = file.apply_records()
>>> file.memory.to_blocks()
[[123, b'abc']]
>>> file.get_meta()
{'linear': True, 'maxdatalen': 16, 'startaddr': 456}

clear(start=None, endex=None)#

Clears data within a range.

It clears the specified range of underlying memory object, making a memory hole.

Any stored records are discarded upon return.

Parameters:

start (int) – Inclusive start address of the specified range. If None, start from the beginning of the memory.
endex (int) – Exclusive end address of the specified range. If None, extend after the end of the memory.

Returns:

BaseFile – self.

See also

memory discard_records() bytesparse.base.MutableMemory.clear()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file = SrecFile.from_blocks([[123, b'abc'], [130, b'xyz']])
>>> _ = file.clear(start=124, endex=132)
>>> file.memory.to_blocks()
[[123, b'a'], [132, b'z']]

classmethod convert(source, meta=True)#

Converts a file object to another format.

It copies the memory and meta of the source file object, creating a new one of the target BaseFile format type.

Parameters:

source (BaseFile) – Source file object to convert.
meta (bool) – Copy meta information to the target file object. Only the keys of the target META_KEYS are processed.

Returns:

BaseFile – Converted copy of source to the target format.

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import IhexFile, SrecFile
>>> blocks = [[123, b'abc'], [456, b'xyz']]
>>> source = IhexFile.from_blocks(blocks, startaddr=789)
>>> target = SrecFile.convert(source)
>>> target.memory is source.memory
False
>>> target.memory == source.memory
True
>>> target.get_meta()
{'header': b'', 'maxdatalen': 16, 'startaddr': 789}

copy(start=None, endex=None, meta=True)#

Copies within a range.

It copied data within the specified range of the file object, creating a new one carrying the inner slice.

Parameters:

start (int) – Inclusive start address of the specified range. If None, start from the beginning of the memory.
endex (int) – Exclusive end address of the specified range. If None, extend after the end of the memory.
meta (bool) – Copy meta information to the created file object.

Returns:

BaseFile – self.

See also

memory get_meta() discard_records() bytesparse.base.MutableMemory.cut()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file = SrecFile.from_blocks([[123, b'abc'], [130, b'xyz']])
>>> inner = file.copy(start=124, endex=132)
>>> inner.memory.to_blocks()
[[124, b'bc'], [130, b'xy']]
>>> file.memory.to_blocks()
[[123, b'abc'], [130, b'xyz']]

crop(start=None, endex=None)#

Clears data outside a range.

It clears outside the specified range of underlying memory object, timming it.

Any stored records are discarded upon return.

Parameters:

start (int) – Inclusive start address of the specified range. If None, start from the beginning of the memory.
endex (int) – Exclusive end address of the specified range. If None, extend after the end of the memory.

Returns:

BaseFile – self.

See also

memory discard_records() bytesparse.base.MutableMemory.crop()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file = SrecFile.from_blocks([[123, b'abc'], [130, b'xyz']])
>>> _ = file.crop(start=124, endex=132)
>>> file.memory.to_blocks()
[[124, b'bc'], [130, b'xy']]

cut(start=None, endex=None, meta=False)#

Cuts data within a range.

It takes data within the specified range away from the file object, creating a new one carrying the inner slice. The inner slice is cleared from self.

Any stored records are discarded upon return.

Parameters:

start (int) – Inclusive start address of the specified range. If None, start from the beginning of the memory.
endex (int) – Exclusive end address of the specified range. If None, extend after the end of the memory.
meta (bool) – Copy meta information to the created file object.

Returns:

BaseFile – self.

See also

memory clear() get_meta() discard_records() bytesparse.base.MutableMemory.cut()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file = SrecFile.from_blocks([[123, b'abc'], [130, b'xyz']])
>>> inner = file.cut(start=124, endex=132)
>>> inner.memory.to_blocks()
[[124, b'bc'], [130, b'xy']]
>>> file.memory.to_blocks()
[[123, b'a'], [132, b'z']]

delete(start=None, endex=None)#

Deletes data within a range.

It deletes the specified range of underlying memory object, shifting all subsequent data towards the collapsed range.

Any stored records are discarded upon return.

Parameters:

start (int) – Inclusive start address of the specified range. If None, start from the beginning of the memory.
endex (int) – Exclusive end address of the specified range. If None, extend after the end of the memory.

Returns:

BaseFile – self.

See also

memory discard_records() bytesparse.base.MutableMemory.delete()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file = SrecFile.from_blocks([[123, b'abc'], [130, b'xyz']])
>>> _ = file.delete(start=124, endex=132)
>>> file.memory.to_blocks()
[[123, b'az']]

discard_memory()#

Discards underlying memory.

The underlying memory object is assigned None.

If the underlying records object is None, it is assigned a new empty memory object.

Returns:: BaseFile – self.

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import IhexFile
>>> file = IhexFile.from_bytes(b'abc', offset=123)
>>> _ = file.update_records()
>>> _ = file.discard_memory()
>>> _ = file.update_records()
Traceback (most recent call last):
    ...
ValueError: memory instance required

discard_records()#

Discards underlying records.

The underlying records object is assigned None.

If the underlying memory object is None, it is assigned a new empty memory object.

Returns:: BaseFile – self.

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import IhexFile
>>> IhexRecord = IhexFile.Record
>>> records = [IhexRecord.create_data(123, b'abc'),
...            IhexRecord.create_end_of_file()]
>>> file = IhexFile.from_records(records)
>>> _ = file.validate_records()
>>> _ = file.discard_records()
>>> _ = file.validate_records()
Traceback (most recent call last):
    ...
ValueError: records required

extend(other)#

Concatenates data.

It concatenates other to the underlyng memory.

Any stored records are discarded upon return.

Parameters:: other (BaseFile or bytes) – Other file or bytes to concatenate.
Returns:: BaseFile – self.

See also

memory discard_records() bytesparse.base.MutableMemory.extend()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file1 = SrecFile.from_bytes(b'abc', offset=123)
>>> file2 = SrecFile.from_bytes(b'xyz', offset=456)
>>> _ = file1.extend(file2)
>>> file1.memory.to_blocks()
[[123, b'abc'], [582, b'xyz']]
>>> _ = file1.extend(b'789')
>>> file1.memory.to_blocks()
[[123, b'abc'], [582, b'xyz789']]

fill(start=None, endex=None, pattern=0)#

Fills a range.

It writes a pattern of bytes onto the underlying memory object, overwriting anything within the specified range.

Any stored records are discarded upon return.

Parameters:

start (int) – Inclusive start address of the specified range. If None, start from the beginning of the memory.
endex (int) – Exclusive end address of the specified range. If None, extend after the end of the memory.
pattern (bytes or int) – Byte pattern for filling.

Returns:

BaseFile – self.

See also

memory discard_records() bytesparse.base.MutableMemory.fill()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file = SrecFile.from_blocks([[123, b'abc'], [130, b'xyz']])
>>> _ = file.fill(start=124, endex=132, pattern=b'.')
>>> file.memory.to_blocks()
[[123, b'a........z']]

find(item, start=None, endex=None)#

Finds a substring.

It searches the provided item within the specified address range, returning the first matching address.

If not found, it returns -1.

Parameters:

item (bytes or int) – Byte pattern to find.
start (int) – Inclusive start address of the specified range. If None, start from the beginning of the memory.
endex (int) – Exclusive end address of the specified range. If None, extend after the end of the memory.

Returns:

int – item beginning address; -1 if not found.

See also

index bytesparse.base.ImmutableMemory.find()

Notes

The internal memory might allow negative addresses for its stored data. In that case, index() would be more appropriate, because it raises an exception when the item is not found.

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file = SrecFile.from_blocks([[123, b'abc'], [456, b'xyz']])
>>> file.find(b'yz')
457
>>> file.find(ord('b'))
124
>>> file.find(b'?')
-1

flood(start=None, endex=None, pattern=0)#

Floods a range.

It fills memory holes of the underlying memory within the specified range with a pattern.

Any stored records are discarded upon return.

Parameters:

start (int) – Inclusive start address of the specified range. If None, start from the beginning of the memory.
endex (int) – Exclusive end address of the specified range. If None, extend after the end of the memory.
pattern (bytes or int) – Byte pattern for flooding.

Returns:

BaseFile – self.

See also

memory discard_records() bytesparse.base.MutableMemory.flood()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file = SrecFile.from_blocks([[123, b'abc'], [130, b'xyz']])
>>> file.get_holes()
[(126, 130)]
>>> _ = file.flood(start=124, endex=132, pattern=b'.')
>>> file.memory.to_blocks()
[[123, b'abc....xyz']]

classmethod from_blocks(blocks, **meta)#

Creates a file object from a memory object.

The blocks are put into the memory of the created file object.

This method creates a file object in memory role. This means that only its memory is internally instanced, while the records requires manual or lazy instancing (i.e. either via direct call to update_records(), or any other methods indirectly calling it).

Parameters:

blocks (list of blocks) – Memory blocks to put into memory.
meta – Meta attributes to set, among META_KEYS.

Returns:

BaseFile – The created file object.

Raises:

KeyError – invalid meta key.

See also

META_KEYS from_memory() bytesparse.base.ImmutableMemory.from_blocks()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> blocks = [[123, b'abc'], [456, b'xyz']]
>>> file = SrecFile.from_blocks(blocks, maxdatalen=8)
>>> file.memory.to_blocks()
[[123, b'abc'], [456, b'xyz']]
>>> file.maxdatalen
8

classmethod from_bytes(data, offset=0, **meta)#

Creates a file object from a byte string.

The byte string makes a single data block, placed at some offset within the memory of the created file object.

Parameters:

data (bytes) – A byte string used to make a single data block.
offset (int) – Offset of the single data block within memory.
meta – Meta attributes to set, among META_KEYS.

Returns:

BaseFile – The created file object.

Raises:

KeyError – invalid meta key.

See also

META_KEYS from_memory() bytesparse.base.ImmutableMemory.from_bytes()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file = SrecFile.from_bytes(b'abc', offset=123, maxdatalen=8)
>>> file.memory.to_blocks()
[[123, b'abc']]
>>> file.maxdatalen
8

classmethod from_memory(memory=None, **meta)#

Creates a file object from a memory object.

The memory is set as the memory of the created file object.

Parameters:

memory (bytesparse.base.MutableMemory) – Memory object to set as memory. If None, an empty memory object is automatically created.
meta – Meta attributes to set, among META_KEYS.

Returns:

BaseFile – The created file object.

Raises:

KeyError – invalid meta key.

See also

META_KEYS bytesparse.base.MutableMemory

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from bytesparse import Memory
>>> blocks = [[123, b'abc'], [456, b'xyz']]
>>> memory = Memory.from_blocks(blocks)
>>> from hexrec import SrecFile
>>> file = SrecFile.from_memory(memory, maxdatalen=8)
>>> file.memory.to_blocks()
[[123, b'abc'], [456, b'xyz']]
>>> file.maxdatalen
8

classmethod from_records(records, maxdatalen=None)#

Creates a file object from records.

The records sequence is set as the record attribute of the created file object.

This method creates a file object in records role. This means that only its records is internally instanced, while the memory requires manual or lazy instancing (i.e. either via direct call to apply_records(), or any other methods indirectly calling it).

Parameters:

records (list of BaseRecord) – Record sequence to set as records.
maxdatalen (Optional[int]) – Maximum record data field size. If None, the maximum non-zero size of the data field from the records sequence is used. If all the records have zero sized data field, the class attribute DEFAULT_DATALEN is used.

Returns:

BaseFile – The created file object.

Raises:

ValueError – invalid meta values.

See also

BaseRecord

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import IhexFile
>>> IhexRecord = IhexFile.Record
>>> records = [IhexRecord.create_data(123, b'abc'),
...            IhexRecord.create_end_of_file()]
>>> file = IhexFile.from_records(records)
>>> file.memory.to_blocks()
[[123, b'abc']]
>>> file.maxdatalen
3

get_address_max()#

Maximum address within memory.

It returns the maximum address of the underlying memory object.

Returns:: int – Maximum address.

See also

bytesparse.base.ImmutableMemory.endin

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file = SrecFile.from_blocks([[123, b'abc'], [456, b'xyz']])
>>> file.get_address_max()
458

get_address_min()#

Minimum address within memory.

It returns the minimum address of the underlying memory object.

Returns:: int – Minimum address.

See also

bytesparse.base.ImmutableMemory.start

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file = SrecFile.from_blocks([[123, b'abc'], [456, b'xyz']])
>>> file.get_address_min()
123

get_holes()#

List of memory holes.

It scans the underlying memory and returns the list of memory holes/gaps.

Each hole is a couple of (start, stop) addresses (as per slice or range()).

Returns:: list of couples – List of memory hole boundaries.

See also

bytesparse.base.ImmutableMemory.gaps()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> blocks = [[123, b'abc'], [456, b'xyz'], [789, b'?!']]
>>> file = SrecFile.from_blocks(blocks)
>>> file.get_holes()
[(126, 456), (459, 789)]

get_meta()#

Meta information.

It builds and returns a dictionary of meta information. Meta keys are taken from the META_KEYS class attribute.

Returns:: dict – Meta information dictionary.

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> blocks = [[123, b'abc'], [456, b'xyz'], [789, b'?!']]
>>> file = SrecFile.from_blocks(blocks, header=b'HDR\0')
>>> file.get_meta()
{'header': b'HDR\x00', 'maxdatalen': 16, 'startaddr': 0}

get_spans()#

List of memory block spans.

It scans the underlying memory and returns the list of memory block spans/intervals.

Each span is a couple of (start, stop) addresses (as per slice or range()).

Returns:: list of couples – List of memory block boundaries.

See also

bytesparse.base.ImmutableMemory.intervals()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> blocks = [[123, b'abc'], [456, b'xyz'], [789, b'?!']]
>>> file = SrecFile.from_blocks(blocks)
>>> file.get_spans()
[(123, 126), (456, 459), (789, 791)]

index(item, start=None, endex=None)#

Finds a substring.

It searches the provided item within the specified address range, returning the first matching address.

If not found, it raises ValueError.

Parameters:

item (bytes or int) – Byte pattern to find.
start (int) – Inclusive start address of the specified range. If None, start from the beginning of the memory.
endex (int) – Exclusive end address of the specified range. If None, extend after the end of the memory.

Returns:

int – item beginning address.

Raises:

ValueError – item not found.

See also

find bytesparse.base.ImmutableMemory.index()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file = SrecFile.from_blocks([[123, b'abc'], [456, b'xyz']])
>>> file.index(b'yz')
457
>>> file.index(ord('b'))
124
>>> file.index(b'?')
Traceback (most recent call last):
    ...
ValueError: subsection not found

classmethod load(path, *args, **kwargs)#

Loads a file object from the filesystem.

The open() function creates a stream from the filesystem, allowing parse() to load a file object.

Parameters:

path (str) – Path of the file within the filesystem. If None, sys.stdin.buffer is used.
args – Forwarded to parse().
kwargs – Forwarded to parse().

Returns:

BaseFile – Loaded file object.

See also

save() parse() open() sys.stdin.buffer

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import IhexFile
>>> file = IhexFile.load('data.hex')
>>> file.memory.to_blocks()
[[55930, b'abc']]
>>> file.get_meta()
{'linear': True, 'maxdatalen': 3, 'startaddr': 51966}

property maxdatalen: int#

Maximum byte size of the data field.

This property sets the maximum byte size of the data field of a serialized record.

This is usually taken into account by update_records() while splitting memory into records.

Setting a different value triggers discard_records().

Raises:: ValueError – Invalid maximum data length.

See also

update_records() discard_records()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> buffer = bytes(range(64))
>>> file = SrecFile.from_bytes(buffer)
>>> file.maxdatalen
16
>>> _ = file.print()
S0030000FC
S1130000000102030405060708090A0B0C0D0E0F74
S1130010101112131415161718191A1B1C1D1E1F64
S1130020202122232425262728292A2B2C2D2E2F54
S1130030303132333435363738393A3B3C3D3E3F44
S5030004F8
S9030000FC
>>> file.maxdatalen = 8
>>> _ = file.print()
S0030000FC
S10B00000001020304050607D8
S10B000808090A0B0C0D0E0F90
S10B0010101112131415161748
S10B001818191A1B1C1D1E1F00
S10B00202021222324252627B8
S10B002828292A2B2C2D2E2F70
S10B0030303132333435363728
S10B003838393A3B3C3D3E3FE0
S5030008F4
S9030000FC
>>> file.maxdatalen = 0
Traceback (most recent call last):
    ...
ValueError: invalid maximum data length

Type:: int

property memory: MutableMemory#

Memory object stored by records role.

This readonly property exposes the memory object stored by the file object while in memory role.

If this property is accessed while the file object is not in memory role, it automatically activates it by an implicit call to apply_records(), with default arguments.

For more control activating the memory role, please call apply_records() manually, providing the desired arguments.

Notes

Most methods acting on the records role (i.e. altering content of records) would implicitly discard memory via discard_memory().

See also

apply_records() discard_memory()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> blocks = [[123, b'abc'], [456, b'xyz']]
>>> file = SrecFile.from_blocks(blocks)
>>> file.memory.to_blocks()
[[123, b'abc'], [456, b'xyz']]
>>> _ = file.write(789, b'?!')
>>> file.memory.to_blocks()
[[123, b'abc'], [456, b'xyz'], [789, b'?!']]

Type:: bytesparse.Memory

merge(*files, clear=False)#

Merges data onto the file.

It writes the provided files onto self, in the provided order. Any common address ranges are overwritten.

Any stored records are discarded upon return.

Parameters:

files (BaseFile) – Files to merge.
clear (bool) – clear() the target address range before writing.

Returns:

BaseFile – self.

See also

clear() discard_records() write()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file1 = SrecFile.from_bytes(b'abc', offset=123)
>>> file2 = SrecFile.from_bytes(b'xyz', offset=456)
>>> file3 = SrecFile.from_bytes(b'<<<?????>>>', offset=450)
>>> _ = file3.merge(file1, file2)
>>> file3.memory.to_blocks()
[[123, b'abc'], [450, b'<<<???xyz>>']]

classmethod parse(stream, ignore_errors=False, maxdatalen=9223372036854775807, address=0)[source]#

Parses records from a byte stream.

It executes RawRecord.parse() for each line of the incoming stream, creating a new file object with the collected records calling from_records().

Notes

Please refer to the actual implementation of each record file format, because it may be more specialized.

Parameters:

stream (bytes IO) – Stream to serialize records onto.
ignore_errors (bool) – Ignore Exception raised by RawRecord.parse().
maxdatalen (int) – Maximum data record data size, to chop the incoming stream.
address (int) – Initial address.

Returns:

RawFile – self.

See also

parse() BaseRecord.parse() from_records()

Examples

>>> from hexrec import RawFile
>>> import io
>>> stream = io.BytesIO(b'Hello, World!')
>>> file = RawFile.parse(stream, maxdatalen=5, address=1000)
>>> for record in file.records:
...     print(f'{record.address}: {record.data!r}')
1000: b'Hello'
1005: b', Wor'
1010: b'ld!'
>>> file.get_meta()
{'maxdatalen': 5}

print(*args, stream=None, color=False, start=None, stop=None, **kwargs)#

Prints record content to stdout.

This helper method prints each record of records via BaseRecord.print(). As such, it also supports colored tokens and streams different from stdout.

It is possible to print subset of the records by specifying the record index range.

Warning

This method is NOT equivalent to serialize(), because it just prints each record from records. Please use serialize() for an actual serialization of the whole file.

Parameters:

args – Forwarded to the underlying call to to_tokens().
stream (byte stream) – Stream to print onto. If None, stdout is used.
color (bool) – Colorize record tokens with ANSI color codes.
start (int) – Inclusive start record index of the specified range. If None, start from the first record.
stop (int) – Exclusive end record index of the specified range. If negative, look back from the last index. If None, print up to the last record.
kwargs – Forwarded to the underlying call to to_tokens().

Returns:

BaseFile – self.

See also

BaseRecord.print()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> buffer = bytes(range(64))
>>> file = SrecFile.from_bytes(buffer)
>>> _ = file.print()
S0030000FC
S1130000000102030405060708090A0B0C0D0E0F74
S1130010101112131415161718191A1B1C1D1E1F64
S1130020202122232425262728292A2B2C2D2E2F54
S1130030303132333435363738393A3B3C3D3E3F44
S5030004F8
S9030000FC
>>> _ = file.print(color=True, start=1, stop=-2)
S1130000000102030405060708090A0B0C0D0E0F74
S1130010101112131415161718191A1B1C1D1E1F64
S1130020202122232425262728292A2B2C2D2E2F54
S1130030303132333435363738393A3B3C3D3E3F44

read(start=None, endex=None, fill=0)#

Extracts a substring.

It extracts a byte string from the specified range, filling any memory holes/gaps (without altering memory).

Parameters:

start (int) – Inclusive start address of the specified range. If None, start from the beginning of the memory.
endex (int) – Exclusive end address of the specified range. If None, extend after the end of the memory.
fill (bytes or int) – Byte pattern for filling.

Returns:

BaseFile – self.

See also

memory bytesparse.base.MutableMemory.extract() bytesparse.base.MutableMemory.to_bytes()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file = SrecFile.from_blocks([[123, b'abc'], [130, b'xyz']])
>>> file.read(start=124, endex=132)
b'bc\x00\x00\x00\x00xy'
>>> file.read(start=124, endex=132, fill=b'.')
b'bc....xy'
>>> file.memory.to_blocks()
[[123, b'abc'], [130, b'xyz']]

property records: MutableSequence[BaseRecord]#

Records stored by records role.

This readonly property exposes the list of records stored by the file object while in records role.

If this property is accessed while the file object is not in records role, it automatically activates it by an implicit call to update_records(), with default arguments.

For more control activating the records role, please call update_records() manually, providing the desired arguments.

Notes

Most methods acting on the memory role (i.e. altering content of memory) would implicitly discard records via discard_records().

See also

update_records() discard_records()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> blocks = [[123, b'abc'], [456, b'xyz']]
>>> file = SrecFile.from_blocks(blocks, startaddr=789)
>>> len(file.records)
5
>>> _ = file.print()
S0030000FC
S106007B61626358
S10601C878797AC5
S5030002FA
S9030315E4
>>> _ = file.update_records(data_tag=SrecFile.Record.Tag.DATA_32)
>>> _ = file.print()
S0030000FC
S3080000007B61626356
S308000001C878797AC3
S5030002FA
S70500000315E2

Type:: list of BaseRecord

save(path, *args, **kwargs)#

Saves a file object into the filesystem.

The open() function creates a stream from the filesystem, allowing serialize() to save a file object.

Parameters:

path (str) – Path of the file within the filesystem. If None, sys.stdout.buffer is used.
args – Forwarded to serialize().
kwargs – Forwarded to serialize().

Returns:

BaseFile – self.

See also

load() serialize() open() sys.stdout.buffer

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import IhexFile
>>> file = IhexFile.from_blocks([[0xDA7A, b'abc']], startaddr=0xCAFE)
>>> _ = file.save('data.hex')

serialize(stream, *args, **kwargs)#

Serializes records onto a byte stream.

It executes BaseRecord.serialize() for each of the stored records.

Parameters:

stream (bytes IO) – Stream to serialize records onto.
args – Forwarded to BaseRecord.serialize() of each record.
kwargs – Forwarded to BaseRecord.serialize() of each record.

Returns:

BaseFile – self.

See also

parse() BaseRecord.serialize()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import IhexFile
>>> file = IhexFile.from_blocks([[0xDA7A, b'abc']], startaddr=0xCAFE)
>>> import sys
>>> _ = file.serialize(sys.stdout.buffer, end=b'\n')
:03DA7A0061626383
:040000050000CAFE2F
:00000001FF

set_meta(meta, strict=True)#

Sets meta information.

It sets the provided kwargs to their matching meta attributes, as listed by META_KEYS.

Parameters:

meta (dict) – Mapping of the meta information to set.
strict (bool) – All the keys within meta must exist within META_KEYS.

Returns:

dict – Attribute values listed by META_KEYS.

Raises:

KeyError – invalid meta key.

See also

META_KEYS get_meta()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> blocks = [[123, b'abc'], [456, b'xyz'], [789, b'?!']]
>>> file = SrecFile.from_blocks(blocks)
>>> file.get_meta()
{'header': b'', 'maxdatalen': 16, 'startaddr': 0}
>>> _ = file.set_meta(dict(header=b'HDR\0', startaddr=456))
>>> file.get_meta()
{'header': b'HDR\x00', 'maxdatalen': 16, 'startaddr': 456}

shift(offset)#

Shifts data addresses by an offset.

It shifts addresses of the underlying memory object data blocks by the provided offset amount.

Any stored records are discarded upon return.

Parameters:: offset (int) – Offset to apply to the underlying data block addresses.
Returns:: BaseFile – self.

See also

memory discard_records() bytesparse.base.MutableMemory.shift()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file = SrecFile.from_blocks([[123, b'abc'], [456, b'xyz']])
>>> _ = file.shift(1000)
>>> file.memory.to_blocks()
[[1123, b'abc'], [1456, b'xyz']]

split(*addresses, meta=True)#

Splits into parts.

The provided addresses are sorted and used as markers to split self into parts.

Each part is the copy() of self within the range of that part, in memory role (i.e., records is not populated).

Parameters:

addresses (int) – Split points.
meta (bool) – Each part inherits meta from self.

Returns:

list of BaseFile – Parts after splitting.

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file = SrecFile.from_bytes(b'Hello, World!', offset=123)
>>> parts = file.split(128, 130)
>>> for part in parts: print(part.memory.to_blocks())
[[123, b'Hello']]
[[128, b', ']]
[[130, b'World!']]
>>> file.memory.to_blocks()
[[123, b'Hello, World!']]

update_records(align=False)[source]#

Applies memory and meta to records.

This method processes the stored memory and meta information to generate the sequence of records.

This effectively converts the memory role into the records role (keeping both).

The records is assigned upon return. Any exceptions being raised should not alter the file object.

Parameters:: align (bool) – Aligns data record chunk address bounds to maxdatalen.
Returns:: RawFile – self.
Raises:: ValueError – memory attribute not populated.

Examples

>>> from hexrec import RawFile
>>> blocks = [[123, b'abc']]
>>> file = RawFile.from_blocks(blocks, maxdatalen=16)
>>> file.memory.to_blocks()
[[123, b'abc']]
>>> file.get_meta()
{'maxdatalen': 16}
>>> _ = file.update_records()
>>> len(file.records)
1
>>> _ = file.print()
abc

validate_records(data_start=True, data_contiguity=True, data_ordering=True)[source]#

Validates records.

It performs consistency checks for the underlying records.

Parameters:

data_start (bool) – Data records must start from address zero.
data_contiguity (bool) – Requires data records be ordered and contiguous.
data_ordering (bool) – Checks that the data record sequence has monotonically increasing addresses, without any overlapping.

Returns:

RawFile – self.

Raises:

ValueError – Invalid record sequence.

Examples

>>> from hexrec import RawFile
>>> records = [RawFile.Record.create_data(123, b'abc')]
>>> file = RawFile.from_records(records)
>>> _ = file.validate_records()
Traceback (most recent call last):
    ...
ValueError: first record address not zero

view(start=None, endex=None)#

Memory view.

It returns a memoryview over the specified range, which must cover a contiguous data region (i.e. no memory holes within).

Parameters:

start (int) – Inclusive start address of the specified range. If None, start from the beginning of the memory.
endex (int) – Exclusive end address of the specified range. If None, extend after the end of the memory.

Returns:

memoryview – View of the specified range.

Raises:

ValueError – non-contiguous data within range.

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file = SrecFile.from_blocks([[123, b'abc'], [456, b'xyz']])
>>> bytes(file.view(start=456, endex=458))
b'xy'
>>> bytes(file.view())
Traceback (most recent call last):
    ...
ValueError: non-contiguous data within range

write(address, data, clear=False)#

Writes data into the file.

It writes the provided data into the underlying memory object.

Any stored records are discarded upon return.

Parameters:

address (int) – Address where data has to be written.
data (bytes or memory) – Byte data to write.
clear (bool) – clear() the target address range before writing.

Returns:

BaseFile – self.

See also

memory clear() discard_records() bytesparse.base.MutableMemory.write()

Examples

NOTE: These examples are provided by BaseFile. Inherited classes for specific formats may require an adaptation.

>>> from hexrec import SrecFile
>>> file = SrecFile()
>>> _ = file.write(123, b'abc')
>>> _ = file.write(555, ord('?'))
>>> _ = file.write(1000, SrecFile.from_bytes(b'xyz', offset=456))
>>> file.memory.to_blocks()
[[123, b'abc'], [555, b'?'], [1456, b'xyz']]