Hexadecimal Record File Handler

0.5.1 · active · verified Thu Apr 16

hexrec is a Python library designed to handle hexadecimal record files, such as Intel HEX and Motorola S-records. It provides tools for parsing, creating, and manipulating these records and converting between raw data blocks and record formats. The current version is 0.5.1, and it maintains an active release cadence with periodic updates to support newer Python versions and improve features.

Common errors

```
ModuleNotFoundError: No module named 'hexrec.base'
```
cause The module `hexrec.base` was renamed to `hexrec.blocks` in version 0.2.0.

fix Update your import statements: change `from hexrec.base import ...` to `from hexrec.blocks import ...`.
```
AttributeError: type object 'IntelHexRecord' has no attribute 'max_data_len'
```
cause The attribute `max_data_len` was renamed to `max_data_length` in version 0.3.0.

fix Replace `.max_data_len` with `.max_data_length` in your code.
```
TypeError: type 'hexrec.records.Record' is not an acceptable base type
```
cause The `Record` base class was removed in version 0.3.0. You are trying to subclass a removed class.

fix If you need a base class for custom records, use `hexrec.records.BaseRecord` instead of `hexrec.records.Record`.
```
RuntimeError: You are using Python 3.8. hexrec requires Python 3.9 or newer.
```
cause Attempting to install or run hexrec v0.5.0 or later on an unsupported Python version.

fix Upgrade your Python environment to version 3.9 or higher. If you must use Python 3.8, install an older version of hexrec: `pip install 'hexrec<0.5.0'`.

Warnings

breaking Python 3.8 support was dropped in hexrec v0.5.0. The minimum required Python version is now 3.9.
Fix: Upgrade your Python environment to 3.9 or newer, or pin hexrec to a version <0.5.0 if Python 3.8 is required (e.g., `pip install 'hexrec<0.5.0'`).
breaking The `Record` base class was removed in hexrec v0.3.0. Users subclassing `Record` should now use `BaseRecord`.
Fix: Change `from hexrec.records import Record` to `from hexrec.records import BaseRecord` and update your class inheritance if you were directly subclassing `Record`.
breaking The `max_data_len` attribute on record classes was renamed to `max_data_length` in hexrec v0.3.0.
Fix: Update all references from `.max_data_len` to `.max_data_length` when accessing the maximum data length for record types.
breaking The `hexrec.base` module was renamed to `hexrec.blocks` in hexrec v0.2.0.
Fix: Update all imports from `from hexrec.base import ...` to `from hexrec.blocks import ...`.

Install

pip install hexrec Install stable version

Imports

IntelHexRecord

from hexrec.records import IntelHexRecord

MotorolaSrecRecord

from hexrec.records import MotorolaSrecRecord

Block
wrong:
```
from hexrec.base import Block
```
correct:
```
from hexrec.blocks import Block
```
The 'base' module was renamed to 'blocks' in v0.2.0.
RecordBlock
wrong:
```
from hexrec.base import RecordBlock
```
correct:
```
from hexrec.blocks import RecordBlock
```
The 'base' module was renamed to 'blocks' in v0.2.0.

Quickstart

This quickstart demonstrates how to create a data Block, convert it into a list of Intel HEX records, and parse a single Intel HEX record line back into a `IntelHexRecord` object using `hexrec.blocks` and `hexrec.records`.

from hexrec.blocks import Block
from hexrec.records import IntelHexRecord

# Create a Block instance with an address and data
data = b'\x00\x01\x02\x03\x04\x05\x06\x07'
block = Block(address=0x1000, data=data)
print(f"Created Block: Address=0x{block.address:04X}, Data={block.data.hex()}")

# Convert the Block to IntelHexRecord instances
records = block.to_records(record_type=IntelHexRecord)

print("Generated Intel HEX Records:")
for record in records:
    print(record.to_line())

# Example of parsing an Intel HEX record line
line = ':10100000000102030405060708090A0B0C0D0E0F00'
parsed_record = IntelHexRecord.from_line(line)
print(f"\nParsed Record: Address=0x{parsed_record.address:04X}, Data={parsed_record.data.hex()}")

view raw JSON →