AsciiHexRecord#

class hexrec.formats.asciihex.AsciiHexRecord(tag, address=0, data=b'', count=Ellipsis, checksum=Ellipsis, before=b'', after=b'', coords=(-1, -1), validate=True)[source]#

ASCII-HEX record object.

Attributes

`DATA_EXECHARS`	Supported execution characters.
`EQUALITY_KEYS`	Meta keys for equality checks.
`LINE_REGEX`	Line parser regex.
`META_KEYS`	Meta keys.

Methods

`__init__`
`compute_checksum`	Computes the checksum field value.
`compute_count`	Compute the count field value.
`copy`	Shallow copy.
`create_address`	Creates an address record.
`create_checksum`	Creates a checksum record.
`create_data`	Creates a data record.
`data_to_int`	Interprets data bytes as integer.
`get_meta`	Gets meta information.
`parse`	Parses a record from bytes.
`print`	Prints a record.
`serialize`	Serializes onto a stream.
`to_bytestr`	Converts into a byte string.
`to_tokens`	Converts into byte string tokens.
`update_checksum`	Updates the checksum field.
`update_count`	Updates the count field.
`validate`	Validates consistency of attribute values.

DATA_EXECHARS: bytes = b" \t\x0b\x0c\r%',"#: Supported execution characters.

EQUALITY_KEYS: Sequence[str] = ['address', 'checksum', 'count', 'data', 'tag']#

Meta keys for equality checks.

Equality methods (__eq__() and __ne__()) check against these meta keys only. Any other meta keys are just ignored.

LINE_REGEX = re.compile(b"\\s*((?P<data>([0-9A-Fa-f]{2}[ \t\x0b\x0c\r%',]?)+)|(\\$[Aa](?P<address>[0-9A-Fa-f]+)[,.])|(\\$[Ss](?P<checksum>[0-9A-Fa-f]+)[,.]))\\s*")#: Line parser regex.

META_KEYS: Sequence[str] = ['address', 'after', 'before', 'checksum', 'coords', 'count', 'data', 'tag']#

Meta keys.

This sequence holds the meta keys for copying (see copy()).

Tag#: alias of AsciiHexTag

__bytes__()#

Serializes the record into bytes.

Returns:: bytes – Byte serialization.

See also

to_bytestr()

Examples

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

>>> from hexrec import IhexFile
>>> record = IhexFile.Record.create_end_of_file()
>>> bytes(record)
b':00000001FF\r\n'

>>> from hexrec import RawFile
>>> record = RawFile.Record.create_data(0, b'abc')
>>> bytes(record)
b'abc'

__eq__(other)#

Equality test.

This method returns true if self is considered equal to other.

As inequality is usually easier to check, this method is usually implemented as a trivial not self != other (__ne__()).

Parameters:: other (BaseRecord) – Record to compare to.
Returns:: bool – self equals other.

See also

__ne__()

Examples

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

>>> from hexrec import IhexFile, RawFile
>>> ihex1 = IhexFile.Record.create_data(0, b'abc')
>>> ihex2 = IhexFile.Record.create_data(0, b'abc')
>>> ihex1 is ihex2
False
>>> ihex1 == ihex2
True
>>> ihex3 = IhexFile.Record.create_data(0, b'xyz')
>>> ihex1 == ihex3
False
>>> raw = RawFile.Record.create_data(0, b'abc')
>>> ihex1 == raw
False

__hash__ = None#

__init__(tag, address=0, data=b'', count=Ellipsis, checksum=Ellipsis, before=b'', after=b'', coords=(-1, -1), validate=True)#

__ne__(other)#

Ineuality test.

This method returns true if self is considered unequal to other.

Each attribute listed by EQUALITY_KEYS is compared between self and other. This method returns whether any attributes do not match.

Parameters:: other (BaseRecord) – Record to compare to.
Returns:: bool – self and other are unequal.

See also

__eq__()

Examples

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

>>> from hexrec import IhexFile, RawFile
>>> ihex1 = IhexFile.Record.create_data(0, b'abc')
>>> ihex2 = IhexFile.Record.create_data(0, b'abc')
>>> ihex1 is ihex2
False
>>> ihex1 != ihex2
False
>>> ihex3 = IhexFile.Record.create_data(0, b'xyz')
>>> ihex1 != ihex3
True
>>> raw = RawFile.Record.create_data(0, b'abc')
>>> ihex1 != raw
True

__repr__()#

String representation.

It returns a string representation of the record content, for human understanding only.

Returns:: str – String representation.

Examples

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

>>> from hexrec import IhexFile
>>> record = IhexFile.Record.create_end_of_file()
>>> repr(record)  
"<<class 'hexrec.formats.ihex.IhexRecord'> @...
  address:=0 after:=b'' before:=b'' checksum:=255 coords:=(-1, -1)
  count:=0 data:=b'' tag:=<IhexTag.END_OF_FILE: 1>>"

__str__()#

Serializes the record into a string.

Returns:: str – String serialization.

See also

to_bytestr()

Examples

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

>>> from hexrec import IhexFile
>>> record = IhexFile.Record.create_end_of_file()
>>> str(record)
':00000001FF\r\n'

>>> from hexrec import RawFile
>>> record = RawFile.Record.create_data(0, b'abc')
>>> str(record)
'abc'

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

compute_checksum()[source]#

Computes the checksum field value.

It computes and returns the format-specific checksum value of a record.

When not specialized, it returns None by default.

Returns:: int – Computed checksum value.

Examples

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

>>> from hexrec import IhexFile
>>> record = IhexFile.Record.create_data(0, b'abc')
>>> record.compute_checksum()
215

>>> from hexrec import RawFile
>>> record = RawFile.Record.create_data(0, b'abc')
>>> repr(record.compute_checksum())
'None'

compute_count()[source]#

Compute the count field value.

It computes and returns the format-specific count value of a record.

When not specialized, it returns None by default.

Returns:: int – Computed checksum value.

Examples

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

>>> from hexrec import IhexFile
>>> record = IhexFile.Record.create_data(0, b'abc')
>>> record.compute_count()
3

>>> from hexrec import RawFile
>>> record = RawFile.Record.create_data(0, b'abc')
>>> repr(record.compute_count())
'None'

copy(validate=True)#

Shallow copy.

It calls the record constructor, passing meta to it.

Parameters:: validate (bool) – Performs validation on instantiation (__init__()).
Returns:: BaseRecord – Shallow copy.

See also

__init__() get_meta()

Examples

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

>>> from hexrec import IhexFile
>>> record1 = IhexFile.Record.create_data(0x1234, b'abc')
>>> record2 = record1.copy()
>>> record1 is record2
False
>>> record1 == record2
True

classmethod create_address(address, addrlen=8)[source]#

Creates an address record.

Parameters:

address (int) – Address value.
addrlen (int) – Address length, in nibbles (4-bit units).

Returns:

AsciiHexRecord – Address record object.

Raises:

ValueError – invalid parameter.

Examples

>>> from hexrec import AsciiHexFile
>>> record = AsciiHexFile.Record.create_address(0x1234, addrlen=4)
>>> str(record)
'$A1234,\r\n'

classmethod create_checksum(checksum)[source]#

Creates a checksum record.

Parameters:: checksum (int) – 16-bit checksum value.
Returns:: AsciiHexRecord – Checksum record object.
Raises:: ValueError – invalid parameter.

Examples

>>> from hexrec import AsciiHexFile
>>> record = AsciiHexFile.Record.create_checksum(0x1234)
>>> str(record)
'$S1234,\r\n'

classmethod create_data(address, data)[source]#

Creates a data record.

Parameters:

address (int) – Ignored; please provide zero.
data (bytes) – Record byte data.

Returns:

AsciiHexRecord – Data record object.

Raises:

ValueError – invalid parameter.

Examples

>>> from hexrec import AsciiHexFile
>>> record = AsciiHexFile.Record.create_data(0, b'abc')
>>> str(record)
'61 62 63 \r\n'

data_to_int(byteorder='big', signed=False)#

Interprets data bytes as integer.

It creates an integer from bytes of the data field.

Parameters:

byteorder ('big' or 'little') – Byte order (endianness): either 'big' (default) or 'little'.
signed (bool) – Signed integer (2-complement); default false.

Returns:

int – Interpreted integer value.

See also

int.from_bytes()

Examples

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

>>> from hexrec import IhexFile
>>> record = IhexFile.Record.create_extended_linear_address(0xABCD)
>>> record.data
b'\xab\xcd'
>>> addrext = record.data_to_int()
>>> addrext, hex(addrext)
(43981, '0xabcd')

get_meta()#

Gets meta information.

It returns all the object attributes whose keys are listed by META_KEYS.

Returns:: dict – Attribute values listed by META_KEYS.

See also

META_KEYS set_meta()

Examples

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

>>> from hexrec import IhexFile
>>> record = IhexFile.Record.create_end_of_file()
>>> record.get_meta()  
{'address': 0, 'after': b'', 'before': b'', 'checksum': 255,
 'coords': (-1, -1), 'count': 0, 'data': b'',
 'tag': <IhexTag.END_OF_FILE: 1>}

classmethod parse(line, address=0, validate=True)[source]#

Parses a record from bytes.

Parameters:

line (bytes) – String of bytes to parse.
address (int) – Default record address for data records.
validate (bool) – Perform validation checks.

Returns:

BaseRecord – Parsed record.

Raises:

ValueError – Syntax error.

Examples

>>> from hexrec import AsciiHexFile
>>> record = AsciiHexFile.Record.parse(b'$A1234,\r\n')
>>> record.tag
<AsciiHexTag.ADDRESS: 1>
>>> record = AsciiHexFile.Record.parse(b'61 62 63\r\n', address=123)
>>> record.address, record.data
(123, b'abc')
>>> AsciiHexFile.Record.parse(b'@ABCD\r\n')
Traceback (most recent call last):
    ...
ValueError: syntax error

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

Prints a record.

The record is converted into tokens (eventually colorized) then joined and written onto a byte stream (stdout by default).

Parameters:

args – Forwarded to the underlying call to to_tokens().
stream (io.BytesIO) – The byte stream where the record tokens are printed. If None, stdout is selected.
color (bool) – Tokens are colorized before printing.
kwargs – Forwarded to the underlying call to to_tokens().

Returns:

BaseRecord – self.

See also

to_tokens() colorize_tokens() io.BytesIO

Examples

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

>>> from hexrec import IhexFile
>>> record = IhexFile.Record.create_data(0x1234, b'abc')
>>> _ = record.print()
:0312340061626391
>>> import io
>>> stream = io.BytesIO()
>>> _ = record.print(stream=stream, color=True)
>>> stream.getvalue()
b'\x1b[0m\x1b[33m:\x1b[34m03\x1b[31m1234\x1b[32m00\x1b[36m61\x1b[96m62\x1b[36m63\x1b[35m91\x1b[0m\r\n\x1b[0m'

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

Serializes onto a stream.

This wraps a call to to_bytestr() and stream.write.

Parameters:

stream (io.BytesIO) – Stream to write.
args – Forwarded to to_bytestr().
kwargs – Forwarded to to_bytestr().

Returns:

BaseRecord – self.

See also

to_bytestr() io.BytesIO

Examples

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

>>> from hexrec import IhexFile
>>> record = IhexFile.Record.create_data(0x1234, b'abc')
>>> import io
>>> stream = io.BytesIO()
>>> _ = record.serialize(stream, end=b'\n')
>>> stream.getvalue()
b':0312340061626391\n'

to_bytestr(exechar=b' ', exelast=True, dollarend=b',', end=b'\\r\\n')[source]#

Converts into a byte string.

Parameters:

exechar (byte) – Execution character value.
exelast (bool) – Append execution character also to the last byte of the serialized record.
dollarend (byte) – End character of dollar records (i.e. address and checksum records).
end (bytes) – End of record termination bytes.

Returns:

bytes – Byte string representation.

Examples

>>> from hexrec import AsciiHexFile
>>> record = AsciiHexFile.Record.create_data(0, b'abc')
>>> record.to_bytestr(exechar=b"'", exelast=False, end=b'\n')
b'61.62.63\n'
>>> record = AsciiHexFile.Record.create_address(0x1234)
>>> record.to_bytestr(dollarend=b'.')
b'$A00001234.\r\n'

to_tokens(exechar=b' ', exelast=True, dollarend=b',', end=b'\\r\\n')[source]#

Converts into byte string tokens.

Parameters:

exechar (byte) – Execution character value.
exelast (bool) – Append execution character also to the last byte of the serialized record.
dollarend (byte) – End character of dollar records (i.e. address and checksum records).
end (bytes) – End of record termination bytes.

Returns:

bytes – Mapping of token keys to token byte strings.

Examples

>>> from hexrec import AsciiHexFile
>>> record = AsciiHexFile.Record.create_data(0, b'abc')
>>> record.to_tokens(exechar=b"'", exelast=False, end=b'\n')  
{'before': b'', 'address': b'', 'data': b"61'62'63",
 'checksum': b'', 'after': b'', 'end': b'\n'}
>>> record = AsciiHexFile.Record.create_address(0x1234)
>>> record.to_tokens(dollarend=b'.')  
{'before': b'', 'address': b'$A00001234.', 'data': b'',
 'checksum': b'', 'after': b'', 'end': b'\r\n'}

update_checksum()#

Updates the checksum field.

It updates the checksum attribute, assigning to it the value returned by compute_checksum().

Returns:: BaseRecord – self.

See also

checksum compute_checksum()

Examples

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

>>> from hexrec import IhexFile
>>> IhexRecord = IhexFile.Record
>>> record = IhexRecord(IhexRecord.Tag.END_OF_FILE, checksum=None)
>>> record.compute_checksum()
255
>>> record.checksum is None
True
>>> _ = record.update_checksum()
>>> record.checksum
255

update_count()#

Updates the count field.

It updates the count attribute, assigning to it the value returned by compute_count().

Returns:: BaseRecord – self.

See also

count compute_count()

Examples

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

>>> from hexrec import IhexFile
>>> Record = IhexFile.Record
>>> Tag = Record.Tag
>>> record = Record(Tag.DATA, data=b'abc', count=None, checksum=None)
>>> record.compute_count()
3
>>> record.count is None
True
>>> _ = record.update_count()
>>> record.count
3

validate(checksum=True, count=True)[source]#

Validates consistency of attribute values.

All the record attributes are checked for consistency.

Please refer to the implementation for more details.

Parameters:

checksum (bool) – Check the consistency of the checksum attribute.
count (bool) – Check the consistency of the count attribute.

Returns:

BaseRecord – self.

Raises:

ValueError – Some targeted attributes are inconsistent.

Examples

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

>>> from hexrec import IhexFile
>>> record = IhexFile.Record.create_end_of_file()
>>> _ = record.validate()
>>> record.data = b'abc'
>>> _ = record.update_count().update_checksum().validate()
Traceback (most recent call last):
    ...
ValueError: unexpcted data