jk_prettyprintobj 0.2024.2.18__tar.gz → 0.2024.10.20__tar.gz

{jk_prettyprintobj-0.2024.2.18 → jk_prettyprintobj-0.2024.10.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: jk_prettyprintobj
-Version: 0.2024.2.18
+Version: 0.2024.10.20
 Summary: This python module provides a mixin for creating pretty debugging output for objects. This is especially useful for semi-complex data structures.
 Keywords: pretty-print,debugging,debug
 Author-email: Jürgen Knauth <pubsrc@binary-overflow.de>

jk_prettyprintobj-0.2024.10.20/jk_prettyprintobj/DumperSettings.py

@@ -0,0 +1,51 @@
+
+
+
+
+#
+# Holds settings about how to dump data.
+#
+class DumperSettings(object):
+
+	################################################################################################################################
+	## Constants
+	################################################################################################################################
+
+	################################################################################################################################
+	## Constructor
+	################################################################################################################################
+
+	#
+	# Constructor method.
+	#
+	def __init__(self) -> None:
+		self.showPrimitivesWithType = False
+		self.showDictKeysWithType = False
+		self.showComplexStructsWithType = False
+		self.compactSequenceLengthLimit = 8
+		self.compactSequenceItemLengthLimit = 50
+		self.bytesLineSize = 32
+		self.compactBytesLinesLengthLimit = 32
+	#
+
+	################################################################################################################################
+	## Public Properties
+	################################################################################################################################
+
+	################################################################################################################################
+	## Helper Methods
+	################################################################################################################################
+
+	################################################################################################################################
+	## Public Methods
+	################################################################################################################################
+
+	################################################################################################################################
+	## Public Static Methods
+	################################################################################################################################
+
+#
+
+
+
+

jk_prettyprintobj-0.2024.10.20/jk_prettyprintobj/RawValue.py

@@ -0,0 +1,47 @@
+
+
+
+#
+# Represents a value that should be written directly without any automatic formatting.
+#
+class RawValue(object):
+
+	################################################################################################################################
+	## Constants
+	################################################################################################################################
+
+	################################################################################################################################
+	## Constructor
+	################################################################################################################################
+
+	#
+	# Constructor method.
+	#
+	def __init__(self, text:str) -> None:
+		assert isinstance(text, str)
+		assert text
+
+		self.text = text
+	#
+
+	################################################################################################################################
+	## Public Properties
+	################################################################################################################################
+
+	################################################################################################################################
+	## Helper Methods
+	################################################################################################################################
+
+	################################################################################################################################
+	## Public Methods
+	################################################################################################################################
+
+	################################################################################################################################
+	## Public Static Methods
+	################################################################################################################################
+
+#
+
+
+
+

jk_prettyprintobj-0.2024.10.20/jk_prettyprintobj/_ByteChunker.py

@@ -0,0 +1,152 @@
+
+
+import codecs
+import math
+import typing
+
+from .DumperSettings import DumperSettings
+
+
+
+
+
+class _ByteChunker(object):
+
+	################################################################################################################################
+	## Constants
+	################################################################################################################################
+
+	################################################################################################################################
+	## Constructor
+	################################################################################################################################
+
+	################################################################################################################################
+	## Public Properties
+	################################################################################################################################
+
+	################################################################################################################################
+	## Helper Methods
+	################################################################################################################################
+
+	@staticmethod
+	def _x_byteChunkToHex(data:bytes) -> str:
+		hexSpanLength = 16		# == 8 bytes for a span
+
+		s = codecs.encode(data, "hex").decode("ascii")
+		chunks = [ s[i:i+hexSpanLength] for i in range(0, len(s), hexSpanLength) ]
+		return " ".join(chunks)
+	#
+
+	@staticmethod
+	def _x_byteChunkToASCII(data:bytes) -> str:
+		spanLength = 8		# == 8 bytes for a span
+
+		ret = []
+		for i, b in enumerate(data):
+			if (i % spanLength) == 0:
+				ret.append(" ")
+			if 32 <= b <= 127:
+				ret.append(chr(b))
+			else:
+				ret.append(".")
+
+		return "".join(ret)
+	#
+
+	################################################################################################################################
+	## Public Methods
+	################################################################################################################################
+
+	################################################################################################################################
+	## Public Static Methods
+	################################################################################################################################
+
+	#
+	# Creates data for output.
+	#
+	# @param		DumperSettings settings		The settings object that contains <c>settings.compactBytesLinesLengthLimit</c>
+	# @param		bytes data					The full data block to process
+	# @param		str? processorName			Understands "shorten" to provide shortened output,
+	#											respecting <c>settings.compactBytesLinesLengthLimit</c> in that cae
+	# @return		tuple<str,str,str>[]		Returns a generator that provides tuples of the following values:
+	#											* str offset part
+	#											* str hex data part
+	#											* str ascii data part
+	#
+	@staticmethod
+	def chunkWithOfs(settings:DumperSettings, data:bytes, processorName:str = None) -> typing.Generator[typing.Tuple[str,str,str],typing.Tuple[str,str,str],typing.Tuple[str,str,str]]:
+		assert isinstance(settings, DumperSettings)
+		assert isinstance(data, bytes)
+		chunkSize = settings.bytesLineSize
+		assert isinstance(chunkSize, int)
+		assert chunkSize > 0
+		hexStrPadded = chunkSize*2 + math.ceil(chunkSize / 8) - 1
+		if processorName is not None:
+			assert isinstance(processorName, str)
+
+		# ----
+
+		nTotalLength = len(data)
+		nTotalLines = math.ceil(nTotalLength / chunkSize)
+		formatStrFragment = None
+		formatStrFragmentEllipsis = None
+		if nTotalLength <= 256*256:
+			formatStrFragment = "{:04x}"
+			formatStrFragmentEllipsis = "... "
+		elif nTotalLength <= 256*256*256:
+			formatStrFragment = "{:06x}"
+			formatStrFragmentEllipsis = "...   "
+		else:
+			formatStrFragment = "{:08x}"
+			formatStrFragmentEllipsis = "...     "
+
+		# ----
+
+		skipFrom = -1
+		skipTo = -1
+		if processorName:
+			if processorName == "shorten":
+				skipFrom = settings.compactBytesLinesLengthLimit
+				skipTo = nTotalLines - 4
+				if skipFrom >= skipTo:
+					skipFrom = -1
+					skipTo = -1
+			else:
+				raise Exception("No such postprocessor: " + repr(processorName))
+
+		# ----
+
+		if skipFrom < 0:
+			# direct loop, no addtional if statements
+			iFrom = 0
+			iTo = chunkSize
+			while iFrom < len(data):
+				chunk = data[iFrom:iTo]
+				yield formatStrFragment.format(iFrom), _ByteChunker._x_byteChunkToHex(chunk).ljust(hexStrPadded), _ByteChunker._x_byteChunkToASCII(chunk)
+				iFrom = iTo
+				iTo += chunkSize
+		else:
+			# loop with if statements
+			lineNo = 0
+			iFrom = 0
+			iTo = chunkSize
+			while iFrom < len(data):
+				chunk = data[iFrom:iTo]
+				if skipFrom <= lineNo <= skipTo:
+					if skipFrom == lineNo:
+						yield formatStrFragmentEllipsis, "...".ljust(hexStrPadded), "..."
+				else:
+					yield formatStrFragment.format(iFrom), _ByteChunker._x_byteChunkToHex(chunk).ljust(hexStrPadded), _ByteChunker._x_byteChunkToASCII(chunk)
+				iFrom = iTo
+				iTo += chunkSize
+				lineNo += 1
+	#
+
+#
+
+
+
+
+
+
+

jk_prettyprintobj-0.2024.10.20/jk_prettyprintobj/_ConverterFunctions.py

@@ -0,0 +1,116 @@
+
+
+import typing
+
+from ._Hex import _Hex
+from ._Bits import _Bits
+
+
+
+
+
+class _ConverterFunctions(object):
+
+	################################################################################################################################
+	## Constants
+	################################################################################################################################
+
+	################################################################################################################################
+	## Constructor
+	################################################################################################################################
+
+	################################################################################################################################
+	## Public Properties
+	################################################################################################################################
+
+	################################################################################################################################
+	## Helper Methods
+	################################################################################################################################
+
+	################################################################################################################################
+	## Public Methods
+	################################################################################################################################
+
+	################################################################################################################################
+	## Public Static Methods
+	################################################################################################################################
+
+	@staticmethod
+	def str_shortenText(text:str) -> str:
+		if len(text) > 40:
+			return text[:40] + "..."
+		else:
+			return text
+	#
+
+	@staticmethod
+	def float_roundTo7FractionDigits(data:typing.Union[int,float]) -> float:
+		return round(data, 7)
+	#
+
+	@staticmethod
+	def float_roundTo6FractionDigits(data:typing.Union[int,float]) -> float:
+		return round(data, 6)
+	#
+
+	@staticmethod
+	def float_roundTo5FractionDigits(data:typing.Union[int,float]) -> float:
+		return round(data, 5)
+	#
+
+	@staticmethod
+	def float_roundTo4FractionDigits(data:typing.Union[int,float]) -> float:
+		return round(data, 4)
+	#
+
+	@staticmethod
+	def float_roundTo3FractionDigits(data:typing.Union[int,float]) -> float:
+		return round(data, 3)
+	#
+
+	@staticmethod
+	def float_roundTo2FractionDigits(data:typing.Union[int,float]) -> float:
+		return round(data, 2)
+	#
+
+	@staticmethod
+	def float_roundTo1FractionDigits(data:typing.Union[int,float]) -> float:
+		return round(data, 1)
+	#
+
+	@staticmethod
+	def int_toHex(data:int) -> typing.Union[int,str]:
+		if data < 0:
+			return data
+		return _Hex(data)
+	#
+
+	@staticmethod
+	def int_toBits(data:int) -> typing.Union[int,str]:
+		if data < 0:
+			return data
+		return _Bits(data)
+	#
+
+	@staticmethod
+	def byteChunker(data:bytes, chunkSize:int) -> typing.Generator[bytes,bytes,bytes]:
+		assert isinstance(data, bytes)
+		assert isinstance(chunkSize, int)
+		assert chunkSize > 0
+
+		iFrom = 0
+		iTo = chunkSize
+		while iFrom < len(data):
+			yield data[iFrom:iTo]
+			iFrom = iTo
+			iTo += chunkSize
+	#
+
+#
+
+
+
+
+
+
+

jk_prettyprintobj-0.2024.10.20/jk_prettyprintobj/__init__.py

@@ -0,0 +1,46 @@
+
+
+
+__author__ = "Jürgen Knauth"
+__version__ = "0.2024.10.20"
+__all__ = (
+	"DumperSettings",
+	"RawValue",
+	"DumpMixin",
+	"Dumper",
+	"DumpCtx",
+	"DEFAULT_DUMPER_SETTINGS",
+	"pprint",
+)
+
+
+
+
+
+from .DumperSettings import DumperSettings
+from .RawValue import RawValue
+from .dumper import DumpMixin, Dumper, DumpCtx, DEFAULT_DUMPER_SETTINGS
+
+from builtins import print as _print
+
+
+
+
+#
+# Print any value in a human readable way.
+#
+def pprint(something, printFunc = None):
+	if printFunc is None:
+		printFunc = _print
+	else:
+		assert callable(printFunc)
+
+	dumper = Dumper()
+	with dumper.createContext(None, "") as dumper2:
+		dumper2._dumpX("", something)
+	dumper.print(printFunc)
+#
+
+
+
+

{jk_prettyprintobj-0.2024.2.18 → jk_prettyprintobj-0.2024.10.20}/jk_prettyprintobj/dumper.py

@@ -7,247 +7,51 @@ import math
 import codecs
 #import datetime
 
+from .RawValue import RawValue
+from .DumperSettings import DumperSettings
 from ._Hex import _Hex
 from ._Bits import _Bits
+from ._ConverterFunctions import _ConverterFunctions as _CF
+from ._ByteChunker import _ByteChunker
 
 
 
-################################################################################################################################
-################################################################################################################################
-##
-## Dumpable objects should use the following import:
-##
-##		import jk_prettyprintobj
-##
-## Dumpable objects should then be defined like this:
-##
-##		class FooBar(SomeBaseClassA,SomeMixinB,jk_prettyprintobj.DumpMixin)
-##			....
-##		#
-##
-## Dumpable objects should then implement one of these two methods:
-##
-##		def _dump(self, ctx:jk_prettyprintobj.DumpCtx):
-##			ctx.dumpVar(...)
-##		#
-##
-## or:
-##
-##		def _dumpVarNames(self) -> typing.List[str]:
-##			return [
-##				"....",
-##			]
-##		#
-##
-################################################################################################################################
-################################################################################################################################
-
-
 
 
 
 
 
-
-class DumperSettings(object):
-
-	def __init__(self):
-		self.showPrimitivesWithType = False
-		self.showDictKeysWithType = False
-		self.showComplexStructsWithType = False
-		self.compactSequenceLengthLimit = 8
-		self.compactSequenceItemLengthLimit = 50
-		self.bytesLineSize = 32
-		self.compactBytesLinesLengthLimit = 32
-	#
-
-#
-
 DEFAULT_DUMPER_SETTINGS = DumperSettings()
 
 
 
 
-def _str_shortenText(text:str) -> str:
-	if len(text) > 40:
-		return text[:40] + "..."
-	else:
-		return text
-#
-
-def _float_roundTo7FractionDigits(data:typing.Union[int,float]) -> float:
-	return round(data, 7)
-#
-
-def _float_roundTo6FractionDigits(data:typing.Union[int,float]) -> float:
-	return round(data, 6)
-#
-
-def _float_roundTo5FractionDigits(data:typing.Union[int,float]) -> float:
-	return round(data, 5)
-#
-
-def _float_roundTo4FractionDigits(data:typing.Union[int,float]) -> float:
-	return round(data, 4)
-#
-
-def _float_roundTo3FractionDigits(data:typing.Union[int,float]) -> float:
-	return round(data, 3)
-#
-
-def _float_roundTo2FractionDigits(data:typing.Union[int,float]) -> float:
-	return round(data, 2)
-#
-
-def _float_roundTo1FractionDigits(data:typing.Union[int,float]) -> float:
-	return round(data, 1)
-#
-
-def _int_toHex(data:int) -> typing.Union[int,str]:
-	if data < 0:
-		return data
-	return _Hex(data)
-#
-
-def _int_toBits(data:int) -> typing.Union[int,str]:
-	if data < 0:
-		return data
-	return _Bits(data)
-#
-
-def _byteChunker(data:bytes, chunkSize:int) -> typing.Sequence[bytes]:
-	assert isinstance(data, bytes)
-	assert isinstance(chunkSize, int)
-	assert chunkSize > 0
-
-	iFrom = 0
-	iTo = chunkSize
-	while iFrom < len(data):
-		yield data[iFrom:iTo]
-		iFrom = iTo
-		iTo += chunkSize
-#
-
-def _x_byteChunkToHex(data:bytes) -> str:
-	hexSpanLength = 16		# == 8 bytes for a span
-
-	s = codecs.encode(data, "hex").decode("ascii")
-	chunks = [ s[i:i+hexSpanLength] for i in range(0, len(s), hexSpanLength) ]
-	return " ".join(chunks)
-#
-
-def _x_byteChunkToASCII(data:bytes) -> str:
-	spanLength = 8		# == 8 bytes for a span
-
-	ret = []
-	for i, b in enumerate(data):
-		if (i % spanLength) == 0:
-			ret.append(" ")
-		if 32 <= b <= 127:
-			ret.append(chr(b))
-		else:
-			ret.append(".")
-
-	return "".join(ret)
-#
-
-#
-# Returns chunks of the specified data.
-#
-def _byteChunkerWithOfs(settings:DumperSettings, data:bytes, processorName:str = None) -> typing.Sequence[typing.Tuple[str,str,str]]:
-	assert isinstance(settings, DumperSettings)
-	assert isinstance(data, bytes)
-	chunkSize = settings.bytesLineSize
-	assert isinstance(chunkSize, int)
-	assert chunkSize > 0
-	hexStrPadded = chunkSize*2 + math.ceil(chunkSize / 8) - 1
-	if processorName is not None:
-		assert isinstance(processorName, str)
-
-	# ----
-
-	nTotalLength = len(data)
-	nTotalLines = math.ceil(nTotalLength / chunkSize)
-	formatStrFragment = None
-	formatStrFragmentEllipsis = None
-	if nTotalLength <= 256*256:
-		formatStrFragment = "{:04x}"
-		formatStrFragmentEllipsis = "... "
-	elif nTotalLength <= 256*256*256:
-		formatStrFragment = "{:06x}"
-		formatStrFragmentEllipsis = "...   "
-	else:
-		formatStrFragment = "{:08x}"
-		formatStrFragmentEllipsis = "...     "
-
-	# ----
-
-	skipFrom = -1
-	skipTo = -1
-	if processorName:
-		if processorName == "shorten":
-			skipFrom = settings.compactBytesLinesLengthLimit
-			skipTo = nTotalLines - 4
-			if skipFrom >= skipTo:
-				skipFrom = -1
-				skipTo = -1
-		else:
-			raise Exception("No such postprocessor: " + repr(processorName))
-
-	# ----
-
-	if skipFrom < 0:
-		# direct loop, no addtional if statements
-		iFrom = 0
-		iTo = chunkSize
-		while iFrom < len(data):
-			chunk = data[iFrom:iTo]
-			yield formatStrFragment.format(iFrom), _x_byteChunkToHex(chunk).ljust(hexStrPadded), _x_byteChunkToASCII(chunk)
-			iFrom = iTo
-			iTo += chunkSize
-	else:
-		# loop with if statements
-		lineNo = 0
-		iFrom = 0
-		iTo = chunkSize
-		while iFrom < len(data):
-			chunk = data[iFrom:iTo]
-			if skipFrom <= lineNo <= skipTo:
-				if skipFrom == lineNo:
-					yield formatStrFragmentEllipsis, "...".ljust(hexStrPadded), "..."
-			else:
-				yield formatStrFragment.format(iFrom), _x_byteChunkToHex(chunk).ljust(hexStrPadded), _x_byteChunkToASCII(chunk)
-			iFrom = iTo
-			iTo += chunkSize
-			lineNo += 1
-#
-
-
 
 
+_PRIMITIVE_POST_PROCESSORS = {
+	# map associating processor name to tuple consisting of type (or type list) and callable
 
-POST_PROCESSORS = {
-	"shorten": (str, _str_shortenText),
-	"hex": (int, _int_toHex),
-	"bit": (int, _int_toBits),
-	"round1": ((float, int), _float_roundTo1FractionDigits),
-	"round2": ((float, int), _float_roundTo2FractionDigits),
-	"round3": ((float, int), _float_roundTo3FractionDigits),
-	"round4": ((float, int), _float_roundTo4FractionDigits),
-	"round5": ((float, int), _float_roundTo5FractionDigits),
-	"round6": ((float, int), _float_roundTo6FractionDigits),
-	"round7": ((float, int), _float_roundTo7FractionDigits),
+	"shorten": (str, _CF.str_shortenText),
+	"hex": (int, _CF.int_toHex),
+	"bit": (int, _CF.int_toBits),
+	"round1": ((float, int), _CF.float_roundTo1FractionDigits),
+	"round2": ((float, int), _CF.float_roundTo2FractionDigits),
+	"round3": ((float, int), _CF.float_roundTo3FractionDigits),
+	"round4": ((float, int), _CF.float_roundTo4FractionDigits),
+	"round5": ((float, int), _CF.float_roundTo5FractionDigits),
+	"round6": ((float, int), _CF.float_roundTo6FractionDigits),
+	"round7": ((float, int), _CF.float_roundTo7FractionDigits),
 
-	"str_shorten": (str, _str_shortenText),
-	"float_round7": ((float, int), _float_roundTo7FractionDigits),
-	"float_round6": ((float, int), _float_roundTo6FractionDigits),
-	"float_round5": ((float, int), _float_roundTo5FractionDigits),
-	"float_round4": ((float, int), _float_roundTo4FractionDigits),
-	"float_round3": ((float, int), _float_roundTo3FractionDigits),
-	"float_round2": ((float, int), _float_roundTo2FractionDigits),
-	"float_round1": ((float, int), _float_roundTo1FractionDigits),
-	"int_hex": (int, _int_toHex),
-	"int_bit": (int, _int_toBits),
+	"str_shorten": (str, _CF.str_shortenText),
+	"float_round7": ((float, int), _CF.float_roundTo7FractionDigits),
+	"float_round6": ((float, int), _CF.float_roundTo6FractionDigits),
+	"float_round5": ((float, int), _CF.float_roundTo5FractionDigits),
+	"float_round4": ((float, int), _CF.float_roundTo4FractionDigits),
+	"float_round3": ((float, int), _CF.float_roundTo3FractionDigits),
+	"float_round2": ((float, int), _CF.float_roundTo2FractionDigits),
+	"float_round1": ((float, int), _CF.float_roundTo1FractionDigits),
+	"int_hex": (int, _CF.int_toHex),
+	"int_bit": (int, _CF.int_toBits),
 }
 
 
@@ -257,23 +61,17 @@ class _Omitted:
 	pass
 #
 
-class RawValue:
-
-	def __init__(self, text:str) -> None:
-		self.text = text
-	#
-
-#
-
 _OMITTED = _Omitted()
 
 
 
 
 
+DumpCtx = typing.NewType("DumpCtx", object)
+
 class DumpCtx(object):
 
-	_TYPE_MAP = {}				# type -> function
+	_TYPE_MAP:typing.Dict[type,typing.Callable[[DumpCtx,str,typing.Any,typing.Union[str,None]],None]] = {}				# type -> function
 
 	def __init__(self, s:DumperSettings, outputLines:list, exitAppend:str, prefix:str):
 		self.__s = s
@@ -294,7 +92,7 @@ class DumpCtx(object):
 	#
 
 	def dumpVarRaw(self, varName:str, value:RawValue) -> None:
-		self._dumpX(varName + " = ", value.text)
+		self._dumpX(varName + " = ", value)
 	#
 
 	#
@@ -339,9 +137,13 @@ class DumpCtx(object):
 	################################################################################################################################
 
 	#
-	# This method outputs a value (recursively).
+	# This method outputs a value (recursively). It is the main dump method.
 	# To achieve this this method analyses the data type of the specified value and invokes individual type processing methods if available.
 	#
+	# @param		str extraPrefix			(required) A prefix to use
+	# @param		any value				(optional) The value to print
+	# @param		str? processorName		(optional) A value output processor
+	#
 	def _dumpX(self, extraPrefix:str, value, processorName:str = None):
 		if value is None:
 			self._dumpPrimitive(extraPrefix, None, processorName)
@@ -369,7 +171,7 @@ class DumpCtx(object):
 			self._dumpObj(extraPrefix, value, processorName)
 			return
 
-		# is it derived from on of our types?
+		# is it derived from one of our types?
 
 		for storedT, m in DumpCtx._TYPE_MAP.items():
 			if isinstance(value, storedT):
@@ -401,7 +203,10 @@ class DumpCtx(object):
 	#
 	def _dumpObj(self, extraPrefix:str, value:object, processorName:str = None):
 		if processorName == "shorten":
-			self.outputLines.append(self.prefix + extraPrefix + "<" + value.__class__.__name__ + "(...)>")
+			if hasattr(value, "_dumpShort"):
+				value._dumpShort(ctx2)
+			else:
+				self.outputLines.append(self.prefix + extraPrefix + "<" + value.__class__.__name__ + "(...)>")
 
 		else:
 			self.outputLines.append(self.prefix + extraPrefix + "<" + value.__class__.__name__ + "(")
@@ -421,6 +226,9 @@ class DumpCtx(object):
 	#
 	# Dump the specified dictionary.
 	#
+	# @param		str processorName			(optional) The processor name. This name is passed to recursive calls of _dumpX() so that it is applied
+	#											to every value. Additionally if "shorten" is specified the dictionary itself will be shortened.
+	#
 	def _dumpDict(self, extraPrefix:str, value:dict, processorName:str = None):
 		e = (type(value).__name__ + ":") if self.__s.showComplexStructsWithType else ""
 
@@ -428,11 +236,17 @@ class DumpCtx(object):
 
 		ctx = DumpCtx(self.__s, self.outputLines, None, self.prefix + "\t")
 		with ctx as ctx2:
+			i = 0
 			for k, v in value.items():
+				if processorName == "shorten":
+					if i >= 3:
+						ctx2._dumpRawValue("", RawValue("..."))
+						break
 				if processorName == "omitValues":
 					v = _OMITTED
 				ctx2._dumpX(self._dictKeyToStr(k) + " : ", v)
 				self.outputLines[-1] += ","
+				i += 1
 
 		self.outputLines.append(self.prefix + "}")
 	#
@@ -454,20 +268,30 @@ class DumpCtx(object):
 	#
 	# Dump the specified list.
 	#
+	# @param		str processorName			(optional) The processor name. This name is passed to recursive calls of _dumpX() so that it is applied
+	#											to every value. Additionally if "shorten" is specified the list itself will be shortened.
+	#
 	def _dumpList(self, extraPrefix:str, value:list, processorName:str = None):
 		e = (type(value).__name__ + ":") if self.__s.showComplexStructsWithType else ""
 
 		if self._canCompactSequence(value):
-			self.outputLines.append(self.prefix + extraPrefix + e + "[ " + self._compactSequence(value, processorName) + " ]")
+			rawText = self._compactSequence(value, processorName)
+			self.outputLines.append(self.prefix + extraPrefix + e + "[ " + rawText + " ]")
 
 		else:
 			self.outputLines.append(self.prefix + extraPrefix + e + "[")
 
 			ctx = DumpCtx(self.__s, self.outputLines, None, self.prefix + "\t")
 			with ctx as ctx2:
+				i = 0
 				for vItem in value:
+					if processorName == "shorten":
+						if i >= 3:
+							ctx2._dumpRawValue("", RawValue("..."))
+							break
 					ctx2._dumpX("", vItem, processorName)
 					self.outputLines[-1] += ","
+					i += 1
 
 			self.outputLines.append(self.prefix + "]")
 	#
@@ -484,7 +308,7 @@ class DumpCtx(object):
 		else:
 			self.outputLines.append(self.prefix + extraPrefix + e + "<")
 
-			for sOfs, chunk, sAscii in _byteChunkerWithOfs(self.__s, value, processorName):
+			for sOfs, chunk, sAscii in _ByteChunker.chunkWithOfs(self.__s, value, processorName):
 				self.outputLines.append(self.prefix + "\t" + sOfs + "  " + chunk + "  " + sAscii)
 
 			if len(value) == 1:
@@ -498,20 +322,30 @@ class DumpCtx(object):
 	#
 	# Dump the specified tuple.
 	#
+	# @param		str processorName			(optional) The processor name. This name is passed to recursive calls of _dumpX() so that it is applied
+	#											to every value. Additionally if "shorten" is specified the list itself will be shortened.
+	#
 	def _dumpTuple(self, extraPrefix:str, value:set, processorName:str = None):
 		e = (type(value).__name__ + ":") if self.__s.showComplexStructsWithType else ""
 
 		if self._canCompactSequence(value):
-			self.outputLines.append(self.prefix + extraPrefix + e + "( " + self._compactSequence(value, processorName) + " )")
+			rawText = self._compactSequence(value, processorName)
+			self.outputLines.append(self.prefix + extraPrefix + e + "( " + rawText + " )")
 
 		else:
 			self.outputLines.append(self.prefix + extraPrefix + e + "(")
 
 			ctx = DumpCtx(self.__s, self.outputLines, None, self.prefix + "\t")
 			with ctx as ctx2:
+				i = 0
 				for vItem in value:
+					if processorName == "shorten":
+						if i >= 3:
+							ctx2._dumpRawValue("", RawValue("..."))
+							break
 					ctx2._dumpX("", vItem, processorName)
 					self.outputLines[-1] += ","
+					i += 1
 
 			self.outputLines.append(self.prefix + ")")
 	#
@@ -591,6 +425,7 @@ class DumpCtx(object):
 		return True
 	#
 
+	# TODO: support "shorten" to shorten the list
 	def _compactSequence(self, someSequence, processorName:str = None) -> str:
 		ret = []
 		for v in someSequence:
@@ -627,9 +462,9 @@ class DumpCtx(object):
 		else:
 			# process value before converting it to str
 			if processorName:
-				if processorName not in POST_PROCESSORS:
+				if processorName not in _PRIMITIVE_POST_PROCESSORS:
 					raise Exception("No such postprocessor: " + repr(processorName))
-				postProcessorTypeCompatibility, postProcessor = POST_PROCESSORS[processorName]
+				postProcessorTypeCompatibility, postProcessor = _PRIMITIVE_POST_PROCESSORS[processorName]
 				if isinstance(value, postProcessorTypeCompatibility):
 					value = postProcessor(value)
 
@@ -730,28 +565,73 @@ class Dumper(object):
 
 
 
+################################################################################################################################
+################################################################################################################################
+"""
+
+Dumpable objects should be defined like this:
+
+	class FooBar(SomeBaseClassA,SomeMixinB,jk_prettyprintobj.DumpMixin)
+		....
+	#
+
+Dumpable objects should then implement one of these two methods:
+
+	def _dump(self, ctx:jk_prettyprintobj.DumpCtx):
+		ctx.dumpVar(...)
+	#
+
+or:
+
+	def _dumpVarNames(self) -> typing.List[str]:
+		return [
+			"....",
+		]
+	#
+
+and maybe additionally:
+
+	def _dumpShort(self, ctx:jk_prettyprintobj.DumpCtx):
+		ctx.dumpVar(...)
+	#
+
+"""
+################################################################################################################################
+################################################################################################################################
+
+
+
+
 class DumpMixin:
 
 	__slots__ = tuple()
 
-	def dump(self, prefix:str = None, printFunc = None) -> None:
+	def __dump(self, prefix:str = None) -> Dumper:
 		dumper = Dumper()
 		with dumper.createContext(self, prefix) as dumper2:
 			if not dumper2._isDumpableObj(self):
 				raise Exception("Improper object encountered for prettyprinting: " + self.__class__.__name__ + " - Either implement _dump(ctx:DumpCtx) or _dumpVarNames()!")
 			dumper2._dumpObj("", self)
+		return dumper
+	#
+
+	def dump(self, prefix:str = None, printFunc = None) -> None:
+		dumper = self.__dump(prefix)
 		dumper.print(printFunc)
 	#
 
 	def dumpToStr(self, prefix:str = None) -> str:
-		dumper = Dumper()
-		with dumper.createContext(self, prefix) as dumper2:
-			if not dumper2._isDumpableObj(self):
-				raise Exception("Improper object encountered for prettyprinting: " + self.__class__.__name__ + " - Either implement _dump(ctx:DumpCtx) or _dumpVarNames()!")
-			dumper2._dumpObj("", self)
+		dumper = self.__dump(prefix)
 		return dumper.toStr()
 	#
 
+	def dumpToFile(self, filePath:str) -> None:
+		dumper = self.__dump()
+		assert isinstance(filePath, str)
+		with open(filePath, "w", newline="\n", encoding="UTF-8") as fout:
+			fout.write(dumper.toStr())
+	#
+
 #
 
 

jk_prettyprintobj-0.2024.2.18/jk_prettyprintobj/__init__.py

@@ -1,16 +0,0 @@
-
-
-
-__author__ = "Jürgen Knauth"
-__version__ = "0.2024.2.18"
-
-
-
-from .dumper import DumpMixin, Dumper, DumpCtx, DEFAULT_DUMPER_SETTINGS, RawValue
-
-
-
-
-
-
-