BaseRecord#

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

Record.

A record is the basic means to transfer data across systems. It is usually a line of text containing some binary data in hexadecimal representation, or some meta information (e.g. start address, record count), often allocated at some address into the target system.

Most formats also contain information for consistency checks, such as the amount of data/characters within the record itself (count), and their checksum.

The BaseRecord class should provide a very generic description of a common record (see Attributes). Wherever the format requires some additional special information, a child class can provide it.

The constructor (__init__()) allows direct assignment of attribute values, as well as skipping validation. This is considered an advanced feature, typically leveraged for testing or experimental purposes.

Instead, a BaseRecord child class should provide factory methods to create records of each specific nature (e.g. the mandatory create_data() for data records).

Variables:

tag (BaseTag) – The mandatory tag, indicating the nature of the record.
address (int) – The address usually tells the position in memory where the provided data must be stored. Some formats use this attribute to store other meta information, such as the start address of some program, or the record count.
data (bytes) – This attribute is most commonly used to store some chunk of binary data to be allocated at the specified address. Some formats might store some meta information within the data field of the serialized record, such as the header string.
count (int) – Most formats indicate the number of bytes or characters within the serialized record itself. Some might store other counting information, like the number of characters for the serialized address field.
checksum (int) – Most formats provide some kind of checksum to check for consistency of the serialized record itself.
before (bytes) – Some formats allow to serialize some data before the canonical syntax, like comments or custom/experimental data. This is a non-standard feature; please leave empty if in doubt.
after (bytes) – Some formats allow to serialize some data after the canonical syntax, like comments or custom/experimental data. This is a non-standard feature; please leave empty if in doubt.
coords (int couple) – Some parsers may use this attribute to store the coordinates of the parsed record, such as the line number, or the byte offset. This is a non-standard feature, useful for debug only.

Parameters:

tag (BaseTag) – See tag attribute.
address (int) – See address attribute.
data (bytes) – See data attribute.
count (int) – See count attribute. Ellipsis initializes count via compute_count(). None assigns None, skipping further validation.
checksum (int) – See checksum attribute. Ellipsis initializes checksum via compute_checksum(). None assigns None, skipping further validation.
before (bytes) – See before attribute.
after (bytes) – See after attribute.
coords (int couple) – See coords attribute.
validate (bool) – If true, validate() is called upon initialization.

Attributes

`EQUALITY_KEYS`	Meta keys for equality checks.
`META_KEYS`	Meta keys.
`Tag`	Tag object type.

Methods

`__init__`
`compute_checksum`	Computes the checksum field value.
`compute_count`	Compute the count field value.
`copy`	Shallow copy.
`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.

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.

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: Type[BaseTag] = None#

Tag object type.

This class attribute indicates the BaseTag class used by this BaseRecord class.

__bytes__()[source]#

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)[source]#

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)[source]#

__ne__(other)[source]#

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__()[source]#

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__()[source]#

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)[source]#

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

abstract classmethod create_data(address, data)[source]#

Creates a data record.

This is a mandatory class method to instantiate a data record.

Parameters:

address (int) – Record address. If not supported, set zero.
data (bytes) – Record byte data.

Returns:

BaseRecord – Data record object.

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')
>>> str(record)
':0312340061626391\r\n'

data_to_int(byteorder='big', signed=False)[source]#

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()[source]#

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>}

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

Parses a record from bytes.

Please refer to the actual implementation provided by the record format for more details.

Parameters:

line (bytes) – String of bytes to parse.
validate (bool) – Perform validation checks.

Returns:

BaseRecord – Parsed record.

Raises:

ValueError – Syntax error.

Examples

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

>>> from hexrec import IhexFile
>>> record = IhexFile.Record.parse(b':00000001FF\r\n')
>>> record.tag
<IhexTag.END_OF_FILE: 1>
>>> IhexFile.Record.parse(b'::00000001FF\r\n')
Traceback (most recent call last):
    ...
ValueError: syntax error

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

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)[source]#

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'

abstract to_bytestr(*args, **kwargs)[source]#

Converts into a byte string.

Parameters:

args – Implementation specific.
kwargs – Implementation specific.

Returns:

bytes – Byte 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_data(0x1234, b'abc')
>>> record.to_bytestr(end=b'\n')
b':0312340061626391\n'

abstract to_tokens(*args, **kwargs)[source]#

Converts into byte string tokens.

Parameters:

args – Implementation specific.
kwargs – Implementation specific.

Returns:

bytes – Mapping of token keys to token byte strings.

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.to_tokens(end=b'\n')  
{'before': b'', 'begin': b':', 'count': b'03', 'address': b'1234',
 'tag': b'00', 'data': b'616263', 'checksum': b'91', 'after': b'',
 'end': b'\n'}

update_checksum()[source]#

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()[source]#

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