hexformat package

Submodules

hexformat.base module

Provide base class for hexformat classes.

License:

MIT License

Copyright (c) 2015-2023 by Martin Scharrer <martin.scharrer@web.de>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software
and associated documentation files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
exception hexformat.base.DecodeError[source]

Bases: HexformatError

Exception is raised if errors during the decoding of a hex file occur.

exception hexformat.base.EncodeError[source]

Bases: HexformatError

Exception is raised if errors during the encoding of a hex file occur.

class hexformat.base.HexFormat[source]

Bases: MultiPartBuffer

classmethod fromother(other, shallow_copy=False)[source]
settings(**settings)[source]
exception hexformat.base.HexformatError[source]

Bases: Exception

General hexformat exception. Base class for all other exceptions of this module.

hexformat.fillpattern module

Provide auto-scaling fill patterns including a random pattern.

License:

MIT License

Copyright (c) 2015-2023 by Martin Scharrer <martin.scharrer@web.de>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software
and associated documentation files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
class hexformat.fillpattern.FillPattern(pattern=255, length=None)[source]

Bases: object

General fill pattern class which instances contain a underlying pattern with is automatically repeated if required.

The underlying pattern is a bytearray which is repeated on demand to fit into a given official length or a slice of any length. An internal start offset for the underlying pattern is used when an instance is produced as slice with a non-zero start offset.

Parameters:

  • pattern (byte or iterable of bytes) – The basic fill pattern which will be repeated. Either a byte sized integer (0..255) or an iterable of such integers (usually a bytearray, str or suitable list or tuple).

  • length (None or int, optional) – Official length of FillPattern. Only used if used with len() or str() etc. If None then the length of the pattern is used instead.

Raises:

ValueError – if pattern argument is numeric but outside of the byte range of 0..255.

classmethod fromnumber(number, width=4, byteorder='big', length=None, signed=False)[source]

Generate instance from integer number. (Python 3 only)

Parameters:

  • number (int) – a numerical value which will be used for the pattern.

  • width (int) – byte width of the number. Usually 1 till 4. If number is narrower than this width it is zero padded.

  • byteorder ('big'|'little') – If ‘big’ (default) the number will be turned into a list of bytes from most to least significant byte (“MSB first”, “Motorola” style). Otherwise the byte order will be from least to most significant byte (“LSB first”, “Intel” style). For any other byte order the method frompattern() must be used with a byte list.

  • length (None or int, optional) – Official length of FillPattern. Only used if used with len() or str() etc. If None then the length of the pattern is used instead.

  • signed (bool; optional) – determines if number is represented in two’s complement. If False and number is negative an OverflowError is raised.

Returns:

New instance of the same class.

classmethod frompattern(pattern, length=None)[source]

Returns instance by either returning existing one or generate new instance from pattern list. The intended use of this method is as filter of user input, so that an instance or pattern can be passed.

Parameters:

  • pattern (cls, byte or iterable of bytes) – If pattern is already an instance of the same class it is used, either directly or as a length adjusted copy if the length argument differs from its length. Otherwise it must be a byte or iterable of bytes which is simply passed to the class constructor. If None then the length of the pattern is used instead.

  • length (int) – Official length of pattern. If None the length of the pattern is used. If smaller than the pattern length, only the first length bytes are used from the pattern.

Returns:

Instance of class based on the given pattern and length.

setlength(length)[source]

Set official length.

Parameters:

length (int) – Official length of FillPattern. Only used if used with len() or str() etc.

class hexformat.fillpattern.RandomContent(length=1)[source]

Bases: FillPattern

Specific FillPattern subclass to produce random content.

Return random content instead any given pattern. Every call produces a different random content. For this the Python random.randint() method is used.

Parameters:

length (int) – Official length. Only used if used with len() etc.

Raises:

AttributeError – May be raised by len(pattern) if input is not as requested above.

hexformat.fillpattern.int_to_bytes(self, /, length, byteorder, *, signed=False)

Return an array of bytes representing an integer.

length

Length of bytes object to use. An OverflowError is raised if the integer is not representable with the given number of bytes.

byteorder

The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value.

signed

Determines whether two’s complement is used to represent the integer. If signed is False and a negative integer is given, an OverflowError is raised.

hexformat.hexdump module

Provide class for HexDump content.

License:

MIT License

Copyright (c) 2015-2023 by Martin Scharrer <martin.scharrer@web.de>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software
and associated documentation files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
class hexformat.hexdump.HexDump[source]

Bases: HexFormat

Hex dump representation class.

The HexDump class is able to generate and parse hex dumps of binary data.

classmethod fromhexdumpfh(fh, bigendian=True)[source]

Generates HexDump instance from file handle which must point to hex dump lines.

Creates new instance and calls loadhexdumpfh() on it.

Parameters:

  • fh (file handle or compatible) – Source of Intel-Hex lines.

  • bigendian (bool) – If True the bytes in a group will be interpreted in big endian (Motorola style, MSB first) order, otherwise in little endian (Intel style, LSB first) order.

Returns:

New instance of class with loaded data.

classmethod fromhexdumpfile(filename, bigendian=True)[source]

Generates HexDump instance from hex dump file.

Opens filename for reading and calls fromhexdumpfh() with the file handle.

Parameters:

  • filename (str) – Name of file to be loaded.

  • bigendian (bool) – If True the bytes in a group will be interpreted in big endian (Motorola style, MSB first) order, otherwise in little endian (Intel style, LSB first) order.

Returns:

New instance of class with loaded data.

loadhexdumpfh(fh, bigendian=True)[source]

Loads hex dump lines from file handle.

Parameters:

  • fh (file handle or compatible) – Source of Intel-Hex lines.

  • bigendian (bool) – If True the bytes in a group will be interpreted in big endian (Motorola style, MSB first) order, otherwise in little endian (Intel style, LSB first) order.

Returns:

self

loadhexdumpfile(filename, bigendian=True)[source]

Loads hex dump lines from named file.

Parameters:

  • filename (str) – Name of file to be loaded.

  • bigendian (bool) – If True the bytes in a group will be interpreted in big endian (Motorola style, MSB first) order, otherwise in little endian (Intel style, LSB first) order.

Returns:

self

tohexdumpfh(fh, bytesperline=16, groupsize=1, bigendian=True, ascii=True)[source]

Writes hex dump to file handle.

Parameters:

  • fh (file handle or compatible) – File handle to be written to.

  • bytesperline (int) – Number of data bytes per line.

  • groupsize (int) – Number of data bytes to be grouped together.

  • bigendian (bool) – If True the bytes in a group are written in big endian (Motorola style, MSB first) order, otherwise in little endian (Intel style, LSB first) order.

  • ascii (bool) – If True the ASCII representation is written after the hex values.

Returns:

self

tohexdumpfile(filename, bytesperline=16, groupsize=1, bigendian=True, ascii=True)[source]

Writes hex dump to named file.

Opens filename for writing and calls tohexdumpfh() on it.

Parameters:

  • filename (str) – Name of file to be written.

  • bytesperline (int) – Number of data bytes per line.

  • groupsize (int) – Number of data bytes to be grouped together.

  • bigendian (bool) – If True the bytes in a group are written in big endian (Motorola style, MSB first) order, otherwise in little endian (Intel style, LSB first) order.

  • ascii (bool) – If True the ASCII representation is written after the hex values.

Returns:

self

hexformat.intelhex module

Provide class to handle IntelHex content.

License:

MIT License

Copyright (c) 2015-2023 by Martin Scharrer <martin.scharrer@web.de>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software
and associated documentation files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
hexformat.intelhex.RT_DATA

Intel-Hex record type number for data record.

Type:

int constant=0

hexformat.intelhex.RT_END_OF_FILE

Intel-Hex record type number for end of file record.

Type:

int constant=1

hexformat.intelhex.RT_EXTENDED_SEGMENT_ADDRESS

Intel-Hex record type number for extend segment address record.

Type:

int constant=2

hexformat.intelhex.RT_START_SEGMENT_ADDRESS

Intel-Hex record type number for start segment address record.

Type:

int constant=3

hexformat.intelhex.RT_EXTENDED_LINEAR_ADDRESS

Intel-Hex record type number for extended linear address record.

Type:

int constant=4

hexformat.intelhex.RT_START_LINEAR_ADDRESS

Intel-Hex record type number for start linear address record.

Type:

int constant=5

class hexformat.intelhex.IntelHex(**settings)[source]

Bases: HexFormat

Intel-Hex file representation class.

The IntelHex class is able to parse and generate binary data in the Intel-Hex representation.

Parameters:

  • bytesperline (int) – Number of bytes per line.

  • variant – Variant of Intel-Hex format. Must be one out of (‘I08HEX’, ‘I8HEX’, ‘I16HEX’, ‘I32HEX’, 8, 16, 32).

  • cs_ip (int, 32-bit) – Value of CS:IP starting address used for I16HEX variant.

  • eip (int, 32-bit) – Value of EIP starting address used for I32HEX variant.

_DATALENGTH

Data length according to record type.

Type:

tuple

_VARIANTS

Mapping dict from variant name to number.

Type:

dict

_DEFAULT_BYTES_PER_LINE

Default number of bytes per line.

Type:

int

_DEFAULT_VARIANT

Default variant.

_bytesperline

Number of bytes per line of this instance. If None the default value will be used.

Type:

None or int

_cs_ip

CS:IP address for I16HEX variant. If None no CS:IP address will be written.

Type:

None or int

_eip

EIP address for I32HEX variant. If None no CS:IP address will be written.

Type:

None or int

_variant

Numeric file format variant. If None the default variant is used.

Type:

None or 8, 16 or 32

property bytesperline
property cs_ip
property eip
classmethod fromihexfh(fh, ignore_checksum_errors=False)[source]

Generates IntelHex instance from file handle which must point to Intel-Hex lines.

Creates new instance and calls loadihexfh() on it.

Parameters:

  • fh (file handle or compatible) – Source of Intel-Hex lines.

  • ignore_checksum_errors (bool) – If True no error is raised on checksum failures.

Returns:

New instance of class with loaded data.

classmethod fromihexfile(filename, ignore_checksum_errors=False)[source]

Generates IntelHex instance from Intel-Hex file.

Opens filename for reading and calls fromihexfh() with the file handle.

Parameters:

  • filename (str) – input filename

  • ignore_checksum_errors (bool) – If True no error is raised on checksum failures

Returns:

New instance of class with loaded data.

loadihexfh(fh, ignore_checksum_errors=False)[source]

Loads Intel-Hex lines from file handle.

Parameters:

  • fh (file handle or compatible) – Source of Intel-Hex lines.

  • ignore_checksum_errors (bool) – If True no error is raised on checksum failures.

Returns:

self

Raises:

  • DecodeError – on checksum mismatch if ignore_checksum_errors is False.

  • DecodeError – on unsupported record type.

loadihexfile(filename, ignore_checksum_errors=False)[source]

Loads Intel-Hex lines from named file.

Creates new instance and calls loadihexfh() on it.

Parameters:

  • filename (str) – Name of Intel-Hex file.

  • ignore_checksum_errors (bool) – If True no error is raised on checksum failures.

Returns:

self

toihexfh(fh, **settings)[source]

Writes content as Intel-Hex file to given file handle.

Parameters:

  • fh (file handle or compatible) – Destination of S-Record lines.

  • bytesperline (int) – Number of bytes per line.

  • variant ('I08HEX', 'I8HEX', 'I16HEX', 'I32HEX', 8, 16, 32) – Variant of Intel-Hex format.

  • cs_ip (int, 32-bit) – Value of CS:IP starting address used for I16HEX variant.

  • eip (int, 32-bit) – Value of EIP starting address used for I32HEX variant.

Returns:

self

Raises:

EncodeError – if selected address length is not wide enough to fit all addresses.

toihexfile(filename, **settings)[source]

Writes content as Intel-Hex file to given file name.

Opens filename for writing and calls toihexfh() with the file handle and all arguments. See toihexfh() for description of the arguments.

Parameters:

  • filename (str) – Input file name.

  • bytesperline (int) – Number of bytes per line.

  • variant ('I08HEX', 'I8HEX', 'I16HEX', 'I32HEX', 8, 16, 32) – Variant of Intel-Hex format.

  • cs_ip (int, 32-bit) – Value of CS:IP starting address used for I16HEX variant.

  • eip (int, 32-bit) – Value of EIP starting address used for I32HEX variant.

Returns:

self

property variant

hexformat.multipartbuffer module

Provide class to handle a data buffer with multiple disconnected parts.

License:

MIT License

Copyright (c) 2015-2023 by Martin Scharrer <martin.scharrer@web.de>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software
and associated documentation files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
class hexformat.multipartbuffer.MultiPartBuffer[source]

Bases: object

Class to handle disconnected binary data.

Each segment (simply called “part”) is identified by its starting address and its content (a Buffer instance).

_STANDARD_FORMAT

The standard format used by fromfh() and fromfile() if no format was given.

Type:

str

_padding

Standard fill pattern.

Type:

int, iterable or FillPattern

add(other, overwrite=True)[source]

Add content of other instance to itself, overwriting or keeping existing data if parts overlap.

Parameters:

  • other (MultiPartBuffer, dict or iterable) – Second summand. If a dict then the keys must be address and the values a buffer. If an iterable it must yield (address, data) combinations.

  • overwrite (bool) – If True existing data will be overwritten if parts overlap.

blockfill(blocksize, address=None, size=None, fillpattern=None, overwrite=False)[source]

Fill with <fillpattern> blockwise with given <blocksize>. Skipping empty blocks.

blockfilter(blocksize, filterfunc, address=None, size=None, skipempty=False)[source]

Execute op(address, blocksize) for each block of <blocksize>.

blockunfill(blocksize, address=None, size=None, unfillpattern=None, mingapsize=None, unfillboundaries=False)[source]

Unfill with <unfillpattern> blockwise with given <blocksize>.

copy()[source]

Return a deep copy of the instance.

crop(address, size=None)[source]

Crop content to range <address>+<size> by deleting all other content.

delete(address, size=None)[source]

Deletes <size> bytes starting from <address>. Does nothing if <size> is non-positive.

end()[source]

Get end address, i.e. the address one after the very last byte of data. An empty buffer will return 0.

extract(address, size=None, keep=True)[source]

Extract given range and return it as new instance. Gaps in the range are preserved. The <keep> argument controls if the range is kept in the original instance or deleted.

fill(address=None, size=None, fillpattern=None, overwrite=False)[source]

Fill with <fillpattern> from <address> for <size> bytes. Filling pattern can be a single byte (0..255) or list-like object. If <overwrite> is False (default) then only gaps are filled. If <address> is None the first existing address is used. If <size> is None the remaining size is used.

fillend(endaddress, fillpattern=None)[source]

Fill the data range after the buffer up to the given address.

fillfront(startaddress=0, fillpattern=None)[source]

Fill the data range in front starting from the given address (0 by default) to the beginning of the buffer.

fillgaps(fillpattern=None)[source]

Fill all gaps with given fillpattern.

filter(filterfunc, address=None, size=None, fillpattern=None)[source]

Call filterfunc(bufferaddr, buffer, bufferstartindex, buffersize) on all parts matching <address> and <size>. If <address> is None the first existing address is used. If <size> is None the remaining size is used. If fillpattern is NOT None the given range is filled and the filter function will be called with the resulting single part.

classmethod frombinfh(fh, address=0, size=-1, offset=0)[source]
classmethod frombinfile(filename, address=0, size=-1, offset=0)[source]
classmethod fromfh(fh, fformat=None, *args, **kvargs)[source]
classmethod fromfile(filename, fformat=None, *args, **kvargs)[source]
gaps()[source]

Return a list with (address,length) tuples for all gaps between the existing parts.

get(address, size, fillpattern=None)[source]

Get <size> bytes from <address>. Fill missing bytes with <fillpattern>.

Where <fillpattern> can be:

  1. A byte-sized integer, i.e. in range 0..255.

  2. A list-like object which has all of the following properties:

    • can be converted to a list of bytes

    • is indexable

    • should be multipliable

  3. A type which produces a list-like object as mentioned in 2) if instanciated with no argument or with the requested size as only argument.

  4. An exception class or instance. If given then no filling is performed but the exception is raised if filling would be required.

hasdata(address=None, size=None)[source]

Returns True if there is data in area (address, size).

includesgaps(address=None, size=None)[source]
loadbinfh(fh, address=0, size=-1, offset=0)[source]
loadbinfile(filename, address=0, size=-1, offset=0)[source]
loaddict(d, overwrite=True)[source]

Load data from dictionary where each key must be numeric and represent an address and the corresponding value the byte value.

loadfh(fh, fformat=None, *args, **kvargs)[source]
loadfile(filename, fformat=None, *args, **kvargs)[source]
offset(offset)[source]

Add an offset to all addresses. A ValueError is raised if offset < -start, as this would lead to negative addresses. If offset is None, the negative start address is used, i.e. the first byte is moved to address 0.

parts()[source]

Return a list with (address,length) tuples for all parts.

range()[source]

Get range of content as (start address, size) tuple. The range may contain unfilled gaps. An empty buffer with return (0, 0).

relocate(newaddress, address=None, size=None, overwrite=True)[source]

Relocate given range to new address. If address is None the start address is used. If size is None the remaining size from address to the endaddress is used. The <overwrite> argument determines if existing data in the new range is overwritten or if the overlapping bytes of the relocated data are discarded.

set(address, newdata, datasize=None, dataoffset=0, overwrite=True)[source]

Add <newdata> starting at <address>. The data size can be given explicitly, otherwise it is taken as len(newdata). Additionally a data offset can be specified to read the data starting from this index from <newdata>.

setint(address, intvalue, datasize, byteorder='big', signed=False, overwrite=True)[source]

Set integer value at given address.

start()[source]

Get start address. An empty buffer with return 0.

tobinfh(fh, address=None, size=None, fillpattern=None)[source]
tobinfile(filename, address=None, size=None, fillpattern=None)[source]
todict()[source]

Return a dictionary with a numeric key for all used bytes like intelhex.IntelHex does it.

tofh(fh, fformat=None, *args, **kvargs)[source]
tofile(filename, fformat=None, *args, **kvargs)[source]
unfill(address=None, size=None, unfillpattern=None, mingapsize=16, unfillboundaries=True)[source]

Removes <unfillpattern> and leaves a gap, as long a resulting new gap would be least <mingapsize> large.

usedsize()[source]

Returns used data size, i.e. without the size of any gaps

hexformat.multipartbuffer.ensurebuffer(buforint)[source]
hexformat.multipartbuffer.int_to_bytes(self, /, length, byteorder, *, signed=False)

Return an array of bytes representing an integer.

length

Length of bytes object to use. An OverflowError is raised if the integer is not representable with the given number of bytes.

byteorder

The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value.

signed

Determines whether two’s complement is used to represent the integer. If signed is False and a negative integer is given, an OverflowError is raised.

hexformat.srecord module

Provide class to handle Motorola SRecord content.

License:

MIT License

Copyright (c) 2015-2023 by Martin Scharrer <martin.scharrer@web.de>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software
and associated documentation files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
class hexformat.srecord.RECORD_TYPE[source]

Bases: object

COUNT_16 = 5
COUNT_24 = 6
DATA_16 = 1
DATA_24 = 2
DATA_32 = 3
FOOTER_16 = 9
FOOTER_24 = 8
FOOTER_32 = 7
HEADER = 0
S0 = 0
S1 = 1
S2 = 2
S3 = 3
S5 = 5
S6 = 6
S7 = 7
S8 = 8
S9 = 9
class hexformat.srecord.SRecord(**settings)[source]

Bases: HexFormat

Motorola S-Record hex file representation class.

The SRecord class is able to parse and generate binary data in the S-Record representation.

_SRECORD_ADDRESSLENGTH

Address length in bytes for each record type.

Type:

tuple

_STANDARD_FORMAT

The standard format used by fromfh() and fromfile() if no format was given.

Type:

str

_startaddress

Starting execution location. This tells the programmer which address contains the start routine. Default: 0.

Type:

int

_header

Header data written using record type 0 if not None. The content is application specific.

Type:

data buffer or None

property addresslength
property bytesperline
classmethod fromsrecfh(fh, raise_error_on_miscount=True)[source]

Generates SRecord instance from file handle which must point to S-Record lines.

Creates new instance and calls loadsrecfh() on it.

Parameters:

  • fh (file handle or compatible) – Source of S-Record lines.

  • raise_error_on_miscount (bool) – If True a DecodeError is raised if the number of records read differs from stored number of records.

Returns:

New instance of class with loaded data.

classmethod fromsrecfile(filename, raise_error_on_miscount=True)[source]

Generates SRecord instance from S-Record file.

Opens filename for reading and calls fromsrecfh() with the file handle.

Parameters:

  • filename (str) – Name of S-Record file.

  • raise_error_on_miscount (bool) – If True a DecodeError is raised if the number of records read differs from stored number of records.

Returns:

New instance of class with loaded data.

property header
loadsrecfh(fh, overwrite_metadata=False, overwrite_data=True, raise_error_on_miscount=True)[source]

Loads data from S-Record file over file handle.

Parses every source line using _parsesrecline() and processes the decoded elements according to the record type.

Parameters:

  • fh (file handle or compatible) – Source of S-Record lines.

  • overwrite_metadata (bool) – If True existing metadata will be overwritten.

  • overwrite_data (bool) – If True existing data will be overwritten.

  • raise_error_on_miscount (bool) – If True a DecodeError is raised if the number of records read differs from stored number of records.

Returns:

self

Raises:

  • DecodeError – If decoded record type is outside of range 0..9.

  • DecodeError – If raise_error_on_miscount is True and number of records read differ from stored number of records.

loadsrecfile(filename, overwrite_metadata=False, overwrite_data=True, raise_error_on_miscount=True)[source]

Loads S-Record lines from named file.

Creates new instance and calls loadsrecfh() on it.

Parameters:

  • filename (str) – Name of S-Record file.

  • overwrite_metadata (bool) – If True existing metadata will be overwritten.

  • overwrite_data (bool) – If True existing data will be overwritten.

  • raise_error_on_miscount (bool) – If True a DecodeError is raised if the number of records read differs from stored number of records.

Returns:

self

property startaddress
tosrecfh(fh, **settings)[source]

Writes content as S-Record file to given file handle.

Parameters:

  • fh (file handle or compatible) – Destination of S-Record lines.

  • bytesperline (int) – Number of data bytes per line.

  • addresslength (None or int in range 2..4) – Address length in bytes. This determines the used file format variant. If None then the shortest possible address length large enough to encode the highest address present is used.

  • write_number_of_records (bool) – If True then the number of data records is written as a record type 5 or 6. This adds an additional verification method if the S-Record file is consistent.

Returns:

self

tosrecfile(filename, **settings)[source]

Writes content as S-Record file to given file name.

Opens filename for writing and calls tosrecfh() with the file handle and all arguments. See tosecfh() for description of the arguments.

Returns:

self

property write_number_of_records

hexformat.tektronix module

Provide class to handle Tektronix Extended Hex content.

License:

MIT License

Copyright (c) 2015-2023 by Martin Scharrer <martin.scharrer@web.de>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software
and associated documentation files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
class hexformat.tektronix.TektronixExtHex(**settings)[source]

Bases: HexFormat

Tektronix Extended Hex file representation class.

The TektronixExtHex class is able to parse and generate binary data in the Tektronix Extended Hex representation.

Attributes:

property addresslength
property bytesperline
classmethod fromtekfh(fh)[source]

Generates instance from file handle which must point to Tektronix Extended Hex lines.

Creates new instance and calls loadtekfh() on it.

Parameters:

fh (file handle or compatible) – Source of Tektronix Extended Hex lines.

Returns:

New instance of class with loaded data.

classmethod fromtekfile(filename)[source]

Generates instance from Tektronix Extended Hex file.

Opens filename for reading and calls fromtekfh() with the file handle.

Parameters:

filename (str) – Name of Tektronix Extended Hex file.

Returns:

New instance of class with loaded data.

loadtekfh(fh, overwrite_metadata=False, overwrite_data=True, raise_error_on_miscount=True)[source]

Loads data from Tektronix Extended Hex file over file handle.

Parses every source line using _parsetekline() and processes the decoded elements according to the record type.

Parameters:

  • fh (file handle or compatible) – Source of Tektronix Extended Hex lines.

  • overwrite_metadata (bool) – If True existing metadata will be overwritten.

  • overwrite_data (bool) – If True existing data will be overwritten.

  • raise_error_on_miscount (bool) – If True a DecodeError is raised if the number of records read differs from stored number of records.

Returns:

self

Raises:

  • DecodeError – If decoded record type is outside of range 0..9.

  • DecodeError – If raise_error_on_miscount is True and number of records read differ from stored number of records.

loadtekfile(filename, overwrite_metadata=False, overwrite_data=True, raise_error_on_miscount=True)[source]

Loads Tektronix Extended Hex lines from named file.

Creates new instance and calls loadtekfh() on it.

Parameters:

  • filename (str) – Name of Tektronix Extended Hex file.

  • overwrite_metadata (bool) – If True existing metadata will be overwritten.

  • overwrite_data (bool) – If True existing data will be overwritten.

  • raise_error_on_miscount (bool) – If True a DecodeError is raised if the number of records read differs from stored number of records.

Returns:

self

property startaddress
totekfh(fh, **settings)[source]

Writes content as Tektronix Extended Hex file to given file handle.

Parameters:

  • fh (file handle or compatible) – Destination of Tektronix Extended Hex lines.

  • settings –

Returns:

self

totekfile(filename, **settings)[source]

Writes content as Tektronix Extended Hex file to given file name.

Opens filename for writing and calls totekfh() with the file handle and all arguments. See totekfh() for description of the arguments.

Returns:

self

Module contents

Provide classes for popular hex formats as well as auxiliary classes to generate fill patterns.

License::

MIT License

Copyright (c) 2015-2023 by Martin Scharrer <martin.scharrer@web.de>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

exception hexformat.DecodeError[source]

Bases: HexformatError

Exception is raised if errors during the decoding of a hex file occur.

exception hexformat.EncodeError[source]

Bases: HexformatError

Exception is raised if errors during the encoding of a hex file occur.

class hexformat.FillPattern(pattern=255, length=None)[source]

Bases: object

General fill pattern class which instances contain a underlying pattern with is automatically repeated if required.

The underlying pattern is a bytearray which is repeated on demand to fit into a given official length or a slice of any length. An internal start offset for the underlying pattern is used when an instance is produced as slice with a non-zero start offset.

Parameters:

  • pattern (byte or iterable of bytes) – The basic fill pattern which will be repeated. Either a byte sized integer (0..255) or an iterable of such integers (usually a bytearray, str or suitable list or tuple).

  • length (None or int, optional) – Official length of FillPattern. Only used if used with len() or str() etc. If None then the length of the pattern is used instead.

Raises:

ValueError – if pattern argument is numeric but outside of the byte range of 0..255.

classmethod fromnumber(number, width=4, byteorder='big', length=None, signed=False)[source]

Generate instance from integer number. (Python 3 only)

Parameters:

  • number (int) – a numerical value which will be used for the pattern.

  • width (int) – byte width of the number. Usually 1 till 4. If number is narrower than this width it is zero padded.

  • byteorder ('big'|'little') – If ‘big’ (default) the number will be turned into a list of bytes from most to least significant byte (“MSB first”, “Motorola” style). Otherwise the byte order will be from least to most significant byte (“LSB first”, “Intel” style). For any other byte order the method frompattern() must be used with a byte list.

  • length (None or int, optional) – Official length of FillPattern. Only used if used with len() or str() etc. If None then the length of the pattern is used instead.

  • signed (bool; optional) – determines if number is represented in two’s complement. If False and number is negative an OverflowError is raised.

Returns:

New instance of the same class.

classmethod frompattern(pattern, length=None)[source]

Returns instance by either returning existing one or generate new instance from pattern list. The intended use of this method is as filter of user input, so that an instance or pattern can be passed.

Parameters:

  • pattern (cls, byte or iterable of bytes) – If pattern is already an instance of the same class it is used, either directly or as a length adjusted copy if the length argument differs from its length. Otherwise it must be a byte or iterable of bytes which is simply passed to the class constructor. If None then the length of the pattern is used instead.

  • length (int) – Official length of pattern. If None the length of the pattern is used. If smaller than the pattern length, only the first length bytes are used from the pattern.

Returns:

Instance of class based on the given pattern and length.

setlength(length)[source]

Set official length.

Parameters:

length (int) – Official length of FillPattern. Only used if used with len() or str() etc.

class hexformat.IntelHex(**settings)[source]

Bases: HexFormat

Intel-Hex file representation class.

The IntelHex class is able to parse and generate binary data in the Intel-Hex representation.

Parameters:

  • bytesperline (int) – Number of bytes per line.

  • variant – Variant of Intel-Hex format. Must be one out of (‘I08HEX’, ‘I8HEX’, ‘I16HEX’, ‘I32HEX’, 8, 16, 32).

  • cs_ip (int, 32-bit) – Value of CS:IP starting address used for I16HEX variant.

  • eip (int, 32-bit) – Value of EIP starting address used for I32HEX variant.

_DATALENGTH

Data length according to record type.

Type:

tuple

_VARIANTS

Mapping dict from variant name to number.

Type:

dict

_DEFAULT_BYTES_PER_LINE

Default number of bytes per line.

Type:

int

_DEFAULT_VARIANT

Default variant.

_bytesperline

Number of bytes per line of this instance. If None the default value will be used.

Type:

None or int

_cs_ip

CS:IP address for I16HEX variant. If None no CS:IP address will be written.

Type:

None or int

_eip

EIP address for I32HEX variant. If None no CS:IP address will be written.

Type:

None or int

_variant

Numeric file format variant. If None the default variant is used.

Type:

None or 8, 16 or 32

property bytesperline
property cs_ip
property eip
classmethod fromihexfh(fh, ignore_checksum_errors=False)[source]

Generates IntelHex instance from file handle which must point to Intel-Hex lines.

Creates new instance and calls loadihexfh() on it.

Parameters:

  • fh (file handle or compatible) – Source of Intel-Hex lines.

  • ignore_checksum_errors (bool) – If True no error is raised on checksum failures.

Returns:

New instance of class with loaded data.

classmethod fromihexfile(filename, ignore_checksum_errors=False)[source]

Generates IntelHex instance from Intel-Hex file.

Opens filename for reading and calls fromihexfh() with the file handle.

Parameters:

  • filename (str) – input filename

  • ignore_checksum_errors (bool) – If True no error is raised on checksum failures

Returns:

New instance of class with loaded data.

loadihexfh(fh, ignore_checksum_errors=False)[source]

Loads Intel-Hex lines from file handle.

Parameters:

  • fh (file handle or compatible) – Source of Intel-Hex lines.

  • ignore_checksum_errors (bool) – If True no error is raised on checksum failures.

Returns:

self

Raises:

  • DecodeError – on checksum mismatch if ignore_checksum_errors is False.

  • DecodeError – on unsupported record type.

loadihexfile(filename, ignore_checksum_errors=False)[source]

Loads Intel-Hex lines from named file.

Creates new instance and calls loadihexfh() on it.

Parameters:

  • filename (str) – Name of Intel-Hex file.

  • ignore_checksum_errors (bool) – If True no error is raised on checksum failures.

Returns:

self

toihexfh(fh, **settings)[source]

Writes content as Intel-Hex file to given file handle.

Parameters:

  • fh (file handle or compatible) – Destination of S-Record lines.

  • bytesperline (int) – Number of bytes per line.

  • variant ('I08HEX', 'I8HEX', 'I16HEX', 'I32HEX', 8, 16, 32) – Variant of Intel-Hex format.

  • cs_ip (int, 32-bit) – Value of CS:IP starting address used for I16HEX variant.

  • eip (int, 32-bit) – Value of EIP starting address used for I32HEX variant.

Returns:

self

Raises:

EncodeError – if selected address length is not wide enough to fit all addresses.

toihexfile(filename, **settings)[source]

Writes content as Intel-Hex file to given file name.

Opens filename for writing and calls toihexfh() with the file handle and all arguments. See toihexfh() for description of the arguments.

Parameters:

  • filename (str) – Input file name.

  • bytesperline (int) – Number of bytes per line.

  • variant ('I08HEX', 'I8HEX', 'I16HEX', 'I32HEX', 8, 16, 32) – Variant of Intel-Hex format.

  • cs_ip (int, 32-bit) – Value of CS:IP starting address used for I16HEX variant.

  • eip (int, 32-bit) – Value of EIP starting address used for I32HEX variant.

Returns:

self

property variant
class hexformat.RandomContent(length=1)[source]

Bases: FillPattern

Specific FillPattern subclass to produce random content.

Return random content instead any given pattern. Every call produces a different random content. For this the Python random.randint() method is used.

Parameters:

length (int) – Official length. Only used if used with len() etc.

Raises:

AttributeError – May be raised by len(pattern) if input is not as requested above.

class hexformat.SRecord(**settings)[source]

Bases: HexFormat

Motorola S-Record hex file representation class.

The SRecord class is able to parse and generate binary data in the S-Record representation.

_SRECORD_ADDRESSLENGTH

Address length in bytes for each record type.

Type:

tuple

_STANDARD_FORMAT

The standard format used by fromfh() and fromfile() if no format was given.

Type:

str

_startaddress

Starting execution location. This tells the programmer which address contains the start routine. Default: 0.

Type:

int

_header

Header data written using record type 0 if not None. The content is application specific.

Type:

data buffer or None

property addresslength
property bytesperline
classmethod fromsrecfh(fh, raise_error_on_miscount=True)[source]

Generates SRecord instance from file handle which must point to S-Record lines.

Creates new instance and calls loadsrecfh() on it.

Parameters:

  • fh (file handle or compatible) – Source of S-Record lines.

  • raise_error_on_miscount (bool) – If True a DecodeError is raised if the number of records read differs from stored number of records.

Returns:

New instance of class with loaded data.

classmethod fromsrecfile(filename, raise_error_on_miscount=True)[source]

Generates SRecord instance from S-Record file.

Opens filename for reading and calls fromsrecfh() with the file handle.

Parameters:

  • filename (str) – Name of S-Record file.

  • raise_error_on_miscount (bool) – If True a DecodeError is raised if the number of records read differs from stored number of records.

Returns:

New instance of class with loaded data.

property header
loadsrecfh(fh, overwrite_metadata=False, overwrite_data=True, raise_error_on_miscount=True)[source]

Loads data from S-Record file over file handle.

Parses every source line using _parsesrecline() and processes the decoded elements according to the record type.

Parameters:

  • fh (file handle or compatible) – Source of S-Record lines.

  • overwrite_metadata (bool) – If True existing metadata will be overwritten.

  • overwrite_data (bool) – If True existing data will be overwritten.

  • raise_error_on_miscount (bool) – If True a DecodeError is raised if the number of records read differs from stored number of records.

Returns:

self

Raises:

  • DecodeError – If decoded record type is outside of range 0..9.

  • DecodeError – If raise_error_on_miscount is True and number of records read differ from stored number of records.

loadsrecfile(filename, overwrite_metadata=False, overwrite_data=True, raise_error_on_miscount=True)[source]

Loads S-Record lines from named file.

Creates new instance and calls loadsrecfh() on it.

Parameters:

  • filename (str) – Name of S-Record file.

  • overwrite_metadata (bool) – If True existing metadata will be overwritten.

  • overwrite_data (bool) – If True existing data will be overwritten.

  • raise_error_on_miscount (bool) – If True a DecodeError is raised if the number of records read differs from stored number of records.

Returns:

self

property startaddress
tosrecfh(fh, **settings)[source]

Writes content as S-Record file to given file handle.

Parameters:

  • fh (file handle or compatible) – Destination of S-Record lines.

  • bytesperline (int) – Number of data bytes per line.

  • addresslength (None or int in range 2..4) – Address length in bytes. This determines the used file format variant. If None then the shortest possible address length large enough to encode the highest address present is used.

  • write_number_of_records (bool) – If True then the number of data records is written as a record type 5 or 6. This adds an additional verification method if the S-Record file is consistent.

Returns:

self

tosrecfile(filename, **settings)[source]

Writes content as S-Record file to given file name.

Opens filename for writing and calls tosrecfh() with the file handle and all arguments. See tosecfh() for description of the arguments.

Returns:

self

property write_number_of_records