AvrFile#
- class hexrec.formats.avr.AvrFile[source]#
Atmel Generic file object.
Attributes
Default data attribute length.
Supported filename extensions.
Meta information key names.
Maximum byte size of the data field.
Memory object stored by records role.
Records stored by records role.
Methods
Pads blocks to align their boundaries.
Appends a byte.
Applies records to memory and meta.
Clears data within a range.
Converts a file object to another format.
Copies within a range.
Clears data outside a range.
Cuts data within a range.
Deletes data within a range.
Discards underlying memory.
Discards underlying records.
Concatenates data.
Fills a range.
Finds a substring.
Floods a range.
Creates a file object from a memory object.
Creates a file object from a byte string.
Creates a file object from a memory object.
Creates a file object from records.
Maximum address within memory.
Minimum address within memory.
List of memory holes.
Meta information.
List of memory block spans.
Finds a substring.
Loads a file object from the filesystem.
Merges data onto the file.
Parses records from a byte stream.
Prints record content to stdout.
Extracts a substring.
Saves a file object into the filesystem.
Serializes records onto a byte stream.
Sets meta information.
Shifts data addresses by an offset.
Splits into parts.
Applies memory and meta to records.
Validates records.
Memory view.
Writes data into the file.
-
DEFAULT_DATALEN:
int
= 2# Default data attribute length.
Default value for the
maxdatalen
meta, which sets the maximum size ofBaseRecord.data
field values.
-
FILE_EXT:
Sequence
[str
] = ['.rom']# Supported filename extensions.
Sequence of file name extension substrings (e.g.
.hex
). This list is used by functions likeguess_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.
- __add__(other)#
Concatenates with another file.
Equivalent to
copy()
thenextend()
.- Parameters:
other (
BaseFile
or bytes) – Other file or bytes to concatenate.- Returns:
BaseFile
– Concatenation of self and other.
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
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
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()
thenmerge()
.- Parameters:
other (
BaseFile
or bytes) – Other file or bytes to merge.- Returns:
BaseFile
– self merged with other.
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 likeclear()
.
- 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)#
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 thememory
.endex (int) – Exclusive end address of the specified range. If
None
, extend after the end of thememory
.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()[source]#
Applies records to memory and meta.
This method processes the stored
records
, converting data asmemory
, 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.
See also
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:
- 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 targetBaseFile
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:
- 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:
- 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:
- 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:
- 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 assignedNone
.If the underlying
records
object isNone
, 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 assignedNone
.If the underlying
memory
object isNone
, 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:
- 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:
- 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:
- 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 therecords
requires manual or lazy instancing (i.e. either via direct call toupdate_records()
, or any other methods indirectly calling it).- Parameters:
- 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.This method creates a file object in memory role. This means that only its
memory
is internally instanced, while therecords
requires manual or lazy instancing (i.e. either via direct call toupdate_records()
, or any other methods indirectly calling it).- Parameters:
- 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.This method creates a file object in memory role. This means that only its
memory
is internally instanced, while therecords
requires manual or lazy instancing (i.e. either via direct call toupdate_records()
, or any other methods indirectly calling it).- Parameters:
- 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 thememory
requires manual or lazy instancing (i.e. either via direct call toapply_records()
, or any other methods indirectly calling it).- Parameters:
records (list of
BaseRecord
) – Record sequence to set asrecords
.maxdatalen (
Optional
[int
]) – Maximum record data field size. IfNone
, 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 attributeDEFAULT_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 perslice
orrange()
).- 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 perslice
orrange()
).- 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:
- 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, allowingparse()
to load a file object.- Parameters:
- Returns:
BaseFile
– Loaded file object.
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 splittingmemory
intorecords
.Setting a different value triggers
discard_records()
.- Raises:
ValueError – Invalid maximum data length.
See also
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 discardmemory
viadiscard_memory()
.See also
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
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, ignore_after_termination=True)#
Parses records from a byte stream.
It executes
BaseRecord.parse()
for each line of the incoming stream, creating a new file object with the collected records callingfrom_records()
.Lines resulting empty by
_is_empty_line()
are just discarded.Notes
Please refer to the actual implementation of each record file format, because it may be more specialized.
- Parameters:
stream (bytes IO or buffer) – Stream or byte buffer to parse records from.
ignore_errors (bool) – Ignore
Exception
raised byBaseRecord.parse()
.ignore_after_termination (bool) – Ignore anything after the termination record was parsed, if supported (e.g. End Of File or start address record, depending on the specific file format).
- Returns:
BaseFile
– self.
See also
parse()
BaseRecord.parse()
from_records()
_is_empty_line()
Examples
NOTE: These examples are provided by
BaseFile
. Inherited classes for specific formats may require an adaptation.>>> from hexrec import IhexFile >>> buffer = b''' ... :03DA7A0061626383 ... :040000050000CAFE2F ... :00000001FF ... ''' >>> import io >>> stream = io.BytesIO(buffer) >>> file = IhexFile.parse(stream) >>> file.memory.to_blocks() [[55930, b'abc']] >>> file.get_meta() {'linear': True, 'maxdatalen': 3, 'startaddr': 51966} >>> file = IhexFile.parse(buffer) >>> file.memory.to_blocks() [[55930, b'abc']] >>> file.get_meta() {'linear': True, 'maxdatalen': 3, 'startaddr': 51966}
- print(*args, stream=None, color=False, start=None, stop=None, **kwargs)#
Prints record content to stdout.
This helper method prints each record of
records
viaBaseRecord.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 fromrecords
. Please useserialize()
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:
- 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 discardrecords
viadiscard_records()
.See also
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, allowingserialize()
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 storedrecords
.- 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
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()[source]#
Applies memory and meta to records.
This method processes the stored
memory
and meta information to generate the sequence ofrecords
.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.See also
Examples
>>> from hexrec import AvrFile >>> blocks = [[124, b'abcd']] >>> file = AvrFile.from_blocks(blocks) >>> file.memory.to_blocks() [[124, b'abcd']] >>> file.get_meta() {'maxdatalen': 2} >>> _ = file.update_records() >>> len(file.records) 2 >>> _ = file.print() 00003E:6162 00003F:6364
- validate_records(data_ordering=False)[source]#
Validates records.
It performs consistency checks for the underlying
records
.- Parameters:
data_ordering (bool) – Checks that the data record sequence has monotonically increasing addresses, without any overlapping.
- Returns:
AvrFile
– self.- Raises:
ValueError – Invalid record sequence.
Examples
>>> from hexrec import AvrFile >>> records = [AvrFile.Record.create_data(62, b'ab'), ... AvrFile.Record.create_data(61, b'cd')] >>> file = AvrFile.from_records(records) >>> _ = file.validate_records(data_ordering=True) Traceback (most recent call last): ... ValueError: unordered data record
- 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:
- 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']]
-
DEFAULT_DATALEN: