blob: c55ae5db2376ea48ce9967c7b255a56b59c3ae95 [file] [edit]
# This is a codec to create and decode hexdumps with spaces between characters.
#
# This file is part of pySerial. https://github.com/pyserial/pyserial
# (C) 2015-2016 Chris Liechti <cliechti@gmx.net>
#
# SPDX-License-Identifier: BSD-3-Clause
"""\
Python 'hexlify' Codec - 2-digit hex with spaces content transfer encoding.
The built-in 'hex_codec' is similar, but encodes and decodes to bytes
and doesn't return spaces between pairs of hexadecimal digits.
Encode and decode may be a bit misleading at first sight...
The str representation is a hex dump: e.g. "40 41"
The "encoded" bytes representation of this is the binary form, e.g. b"@A"
Thus, decoding is binary to text and thus converting binary data to hex dump.
"""
import codecs
HEXDIGITS = "0123456789ABCDEF"
# Codec APIs
def hex_encode(data: str, errors: str = "strict") -> tuple[bytes, int]:
"""'40 41 42' -> b'@AB'"""
return bytes.fromhex(data), len(data)
def hex_decode(data: bytes | memoryview, errors: str = "strict") -> tuple[str, int]:
"""b'@AB' -> '40 41 42'"""
return data.hex(sep=" ").upper() + " ", len(data)
class Codec(codecs.Codec):
def encode(self, data: str, errors: str = "strict") -> tuple[bytes, int]:
"""'40 41 42' -> b'@AB'"""
return bytes.fromhex(data), len(data)
def decode(self, data: bytes, errors: str = "strict") -> tuple[str, int]:
"""b'@AB' -> '40 41 42'"""
return data.hex(sep=" ").upper() + " ", len(data)
class IncrementalEncoder(codecs.IncrementalEncoder):
"""Incremental hex encoder"""
def __init__(self, errors: str = "strict") -> None:
self.errors = errors
self.state = 0
def reset(self) -> None:
self.state = 0
def getstate(self) -> int:
return self.state
def setstate(self, state: int) -> None:
self.state = state
def encode(self, data: str, final: bool = False) -> bytes:
"""\
Incremental encode, keep track of digits and emit a byte when a pair
of hex digits is found. The space is optional unless the error
handling is defined to be 'strict'.
"""
state = self.getstate()
encoded = []
for c in data.upper():
if c in HEXDIGITS:
z = HEXDIGITS.index(c)
if state:
encoded.append(z + (state & 0xF0))
state = 0
else:
state = 0x100 + (z << 4)
elif c == " ": # allow spaces to separate values
if state and self.errors == "strict":
raise UnicodeError("odd number of hex digits")
state = 0
else:
if self.errors == "strict":
raise UnicodeError(f"non-hex digit found: {c!r}")
self.setstate(state)
return bytes(encoded)
class IncrementalDecoder(codecs.IncrementalDecoder):
"""Incremental decoder"""
def decode(self, data: bytes, final: bool = False):
return data.hex(sep=" ").upper() + " "
class StreamWriter(Codec, codecs.StreamWriter):
"""Combination of hexlify codec and StreamWriter"""
class StreamReader(Codec, codecs.StreamReader):
"""Combination of hexlify codec and StreamReader"""
def getregentry() -> codecs.CodecInfo:
"""encodings module API"""
return codecs.CodecInfo(
name="hexlify",
encode=hex_encode,
decode=hex_decode,
incrementalencoder=IncrementalEncoder,
incrementaldecoder=IncrementalDecoder,
streamwriter=StreamWriter,
streamreader=StreamReader,
)