jk_prettyprintobj 0.2024.2.18__tar.gz

jk_prettyprintobj-0.2024.2.18/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.1
+Name: jk_prettyprintobj
+Version: 0.2024.2.18
+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>
+Maintainer-email: Jürgen Knauth <pubsrc@binary-overflow.de>
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+
+jk_prettyprintobj
+========
+
+Introduction
+------------
+
+This python module provides a mixin for dumping objects. This is ment for debugging purposes: Sometimes it is very convenient to have a way of writing all data of an object to STDOUT in a human readable way. This module assists in such implementations.
+
+Information about this module can be found here:
+
+* [github.org](https://github.com/jkpubsrc/python-module-jk-prettyprintobj)
+* [pypi.python.org](https://pypi.python.org/pypi/jk_prettyprintobj)
+
+How to use this module
+----------------------
+
+### Import the module
+
+In order to use this module you need to import it first. So add this line to the head of your python source code file:
+
+```python
+import jk_prettyprintobj
+```
+
+### Use the provided mixin
+
+To make use of the features of this module you must add a mixin to your class. Example:
+
+```python
+class ExampleClass(jk_prettyprintobj.DumpMixin):
+
+	def __init__(self, ...):
+		...
+
+	...
+```
+
+If you derive your class from a base class just add the mixin to your list of base classes. The order does not matter in this case. Here is an example how to do this:
+
+```python
+class MyFancyException(Exception, jk_prettyprintobj.DumpMixin):
+
+	def __init__(self, msg:str):
+		super().__init__(msg)
+
+	...
+```
+
+In this example we use `Exception` as a base class to keep this example simple. It just demonstrates the technique. You can use any base class for inheritance, it is just necessary that you somewhere in the list of base classes add `jk_prettyprintobj.DumpMixin`. This does not yet make use of the features provided by `jk_prettyprintobj` but prepares its use.
+
+This mixin adds a regular method named `dump()` to the class. For all things to work it is important that you have no other method named `dump()` in your class that might conflict with the implementation provided by `DumpMixin`. This method can be called later, but some additional implementation steps need to be taken first. (See next section!)
+
+### Implement a helper method
+
+To actually enable the class to produce output we must implement one of the helper methods. These are:
+
+| **Method name**									| **Description**								|
+| ---												| ---											|
+| `_dump(ctx:jk_prettyprintobj.DumpCtx) -> None`	| Implement dumping data on your own			|
+| `_dumpVarNames() -> typing.List[str]`				| Provide the names of the variable to output	|
+
+More to these options in the next sections.
+
+### Helper method _dumpVarNames()
+
+If you implement the method `_dumpVarNames() -> typing.List[str]` your method needs to return a list of variable names that should be dumped to STDOUT.
+
+Here is an example of a simple but working implementation.
+
+```python
+class Matrix(jk_prettyprintobj.DumpMixin):
+
+	def __init__(self, m):
+		self.m = m
+		self.nRows = len(m)
+		self.nColumns = len(m[0])
+
+	def _dumpVarNames(self) -> list:
+		return [
+			"nRows",
+			"nColumns",
+			"m",
+		]
+```
+
+Now what `_dumpVarNames()` will do is simply returning a list of variables to access for output.
+
+As private variables can not be accessed by mixins all variables in this example have therefore been defined as public variables. This is a general limitation of python so there is no way around this: All variables to output this way need to be non-private.
+
+Now let's create an instance of `Matrix` and invoke `dump()`:
+
+```python
+m = Matrix([
+	[	1,	2,	3 	],
+	[	4,	5,	6 	],
+	[	7,	8,	9.1234567	],
+])
+
+m.dump()
+```
+
+If `dump()` is invoked on an initialized instance of `Matrix` from this example such an object will render to something like this:
+
+```
+<Matrix(
+	nRows = 3
+	nColumns = 3
+	m = [
+		[ 1, 2, 3 ],
+		[ 4, 5, 6 ],
+		[ 7, 8, 9.1234567 ],
+	]
+)>
+```
+
+### Helper method _dump(ctx)
+
+If you implement the method `_dump(ctx:jk_prettyprintobj.DumpCtx) -> None` your method needs to use the provided context object to implement dumping variables to STDOUT on your own. This variant is helpful if you - for some reason - require to output private variables that an implementation of `_dumpVarNames()` will not be able to access.
+
+By implementing this method you will also be able to modify the way how the contents of a variable will be written to STDOUT.
+
+Here is an example of a simple but working implementation:
+
+```python
+class Matrix(jk_prettyprintobj.DumpMixin):
+
+	def __init__(self, m):
+		self.__m = m
+		self.__nRows = len(m)
+		self.__nColumns = len(m[0])
+
+	def _dump(self, ctx:jk_prettyprintobj.DumpCtx):
+		ctx.dumpVar("nRows", self.__nRows)
+		ctx.dumpVar("nColumns", self.__nColumns)
+		ctx.dumpVar("m", self.__m, "float_round3")
+```
+
+This class is expected to represent a mathematical matrix and therefore should receive a two-dimensional field of `float` values during construction. During construction this data is stored in a private variable named `__m`. Additional private variables are created. For simplicity no other methods except `dump_()` are implemented in this example.
+
+Now what `_dump()` will do is to invoke `dumpVar()` for every single variable. `dumpVar()` has the following signature:
+
+* `dumpVar(varName:str, value, postProcessorName:str = None) -> None`
+
+This method requires to receive up to three arguments:
+* `str varName`: The name to use for output. In this example we use `nRows` as we might add a property of exactly this name. (Not implemented in this example!)
+* `* value`: A value of any kind. This is the value that should later on be written to STDOUT.
+* `str processorName`: This optional value can be one of several identifiers that indicate how to process the value *before* it is converted to a string. (See section below.)
+
+If `dump()` is invoked on an initialized instance of `Matrix` from this example such an object will render to something like this:
+
+```
+<Matrix(
+	nRows = 3
+	nColumns = 3
+	m = [
+		[ 1, 2, 3 ],
+		[ 4, 5, 6 ],
+		[ 7, 8, 9.123 ],
+	]
+)>
+```
+
+Please note that in this case the output of the very last `float` in the matrix might be rounded to three digits as defined by the processor `float_round3`. This is different to an implementation providing `_dumpVarNames()`.
+
+### Processors
+
+For producing output you can apply a processor that will preprocess the output before writing it to STDOUT. This is useful to achieve a more human readable representation of data in some cases.
+
+These are the processors you can use:
+
+| **Name**			| **Description**				|
+| ---				| ---							|
+| `float_round1`	| Round to 1 fractional digit	|
+| `float_round2`	| Round to 2 fractional digit	|
+| `float_round3`	| Round to 3 fractional digit	|
+| `float_round4`	| Round to 4 fractional digit	|
+| `float_round5`	| Round to 5 fractional digit	|
+| `float_round6`	| Round to 6 fractional digit	|
+| `float_round7`	| Round to 7 fractional digit	|
+| `int_hex`			| Convert to hexadecimal representation		|
+| `int_bit`			| Convert to binary representation		|
+| `str_shorten`		| Shorten a string to at most 40 characters. If you have objects with large amounts of text this feature can make your output more readable.	|
+
+Futher Development
+-------------------
+
+It is likely that future developments will add more alternatives for dumping an objects. If you have any ideas, requirements or recommendations please feel free to leave a comment.
+
+Contact Information
+-------------------
+
+This is Open Source code. That not only gives you the possibility of freely using this code it also
+allows you to contribute. Feel free to contact the author(s) of this software listed below, either
+for comments, collaboration requests, suggestions for improvement or reporting bugs:
+
+* Jürgen Knauth: pubsrc@binary-overflow.de
+
+License
+-------
+
+This software is provided under the following license:
+
+* Apache Software License 2.0
+
+
+
+

jk_prettyprintobj-0.2024.2.18/README.md

@@ -0,0 +1,206 @@
+jk_prettyprintobj
+========
+
+Introduction
+------------
+
+This python module provides a mixin for dumping objects. This is ment for debugging purposes: Sometimes it is very convenient to have a way of writing all data of an object to STDOUT in a human readable way. This module assists in such implementations.
+
+Information about this module can be found here:
+
+* [github.org](https://github.com/jkpubsrc/python-module-jk-prettyprintobj)
+* [pypi.python.org](https://pypi.python.org/pypi/jk_prettyprintobj)
+
+How to use this module
+----------------------
+
+### Import the module
+
+In order to use this module you need to import it first. So add this line to the head of your python source code file:
+
+```python
+import jk_prettyprintobj
+```
+
+### Use the provided mixin
+
+To make use of the features of this module you must add a mixin to your class. Example:
+
+```python
+class ExampleClass(jk_prettyprintobj.DumpMixin):
+
+	def __init__(self, ...):
+		...
+
+	...
+```
+
+If you derive your class from a base class just add the mixin to your list of base classes. The order does not matter in this case. Here is an example how to do this:
+
+```python
+class MyFancyException(Exception, jk_prettyprintobj.DumpMixin):
+
+	def __init__(self, msg:str):
+		super().__init__(msg)
+
+	...
+```
+
+In this example we use `Exception` as a base class to keep this example simple. It just demonstrates the technique. You can use any base class for inheritance, it is just necessary that you somewhere in the list of base classes add `jk_prettyprintobj.DumpMixin`. This does not yet make use of the features provided by `jk_prettyprintobj` but prepares its use.
+
+This mixin adds a regular method named `dump()` to the class. For all things to work it is important that you have no other method named `dump()` in your class that might conflict with the implementation provided by `DumpMixin`. This method can be called later, but some additional implementation steps need to be taken first. (See next section!)
+
+### Implement a helper method
+
+To actually enable the class to produce output we must implement one of the helper methods. These are:
+
+| **Method name**									| **Description**								|
+| ---												| ---											|
+| `_dump(ctx:jk_prettyprintobj.DumpCtx) -> None`	| Implement dumping data on your own			|
+| `_dumpVarNames() -> typing.List[str]`				| Provide the names of the variable to output	|
+
+More to these options in the next sections.
+
+### Helper method _dumpVarNames()
+
+If you implement the method `_dumpVarNames() -> typing.List[str]` your method needs to return a list of variable names that should be dumped to STDOUT.
+
+Here is an example of a simple but working implementation.
+
+```python
+class Matrix(jk_prettyprintobj.DumpMixin):
+
+	def __init__(self, m):
+		self.m = m
+		self.nRows = len(m)
+		self.nColumns = len(m[0])
+
+	def _dumpVarNames(self) -> list:
+		return [
+			"nRows",
+			"nColumns",
+			"m",
+		]
+```
+
+Now what `_dumpVarNames()` will do is simply returning a list of variables to access for output.
+
+As private variables can not be accessed by mixins all variables in this example have therefore been defined as public variables. This is a general limitation of python so there is no way around this: All variables to output this way need to be non-private.
+
+Now let's create an instance of `Matrix` and invoke `dump()`:
+
+```python
+m = Matrix([
+	[	1,	2,	3 	],
+	[	4,	5,	6 	],
+	[	7,	8,	9.1234567	],
+])
+
+m.dump()
+```
+
+If `dump()` is invoked on an initialized instance of `Matrix` from this example such an object will render to something like this:
+
+```
+<Matrix(
+	nRows = 3
+	nColumns = 3
+	m = [
+		[ 1, 2, 3 ],
+		[ 4, 5, 6 ],
+		[ 7, 8, 9.1234567 ],
+	]
+)>
+```
+
+### Helper method _dump(ctx)
+
+If you implement the method `_dump(ctx:jk_prettyprintobj.DumpCtx) -> None` your method needs to use the provided context object to implement dumping variables to STDOUT on your own. This variant is helpful if you - for some reason - require to output private variables that an implementation of `_dumpVarNames()` will not be able to access.
+
+By implementing this method you will also be able to modify the way how the contents of a variable will be written to STDOUT.
+
+Here is an example of a simple but working implementation:
+
+```python
+class Matrix(jk_prettyprintobj.DumpMixin):
+
+	def __init__(self, m):
+		self.__m = m
+		self.__nRows = len(m)
+		self.__nColumns = len(m[0])
+
+	def _dump(self, ctx:jk_prettyprintobj.DumpCtx):
+		ctx.dumpVar("nRows", self.__nRows)
+		ctx.dumpVar("nColumns", self.__nColumns)
+		ctx.dumpVar("m", self.__m, "float_round3")
+```
+
+This class is expected to represent a mathematical matrix and therefore should receive a two-dimensional field of `float` values during construction. During construction this data is stored in a private variable named `__m`. Additional private variables are created. For simplicity no other methods except `dump_()` are implemented in this example.
+
+Now what `_dump()` will do is to invoke `dumpVar()` for every single variable. `dumpVar()` has the following signature:
+
+* `dumpVar(varName:str, value, postProcessorName:str = None) -> None`
+
+This method requires to receive up to three arguments:
+* `str varName`: The name to use for output. In this example we use `nRows` as we might add a property of exactly this name. (Not implemented in this example!)
+* `* value`: A value of any kind. This is the value that should later on be written to STDOUT.
+* `str processorName`: This optional value can be one of several identifiers that indicate how to process the value *before* it is converted to a string. (See section below.)
+
+If `dump()` is invoked on an initialized instance of `Matrix` from this example such an object will render to something like this:
+
+```
+<Matrix(
+	nRows = 3
+	nColumns = 3
+	m = [
+		[ 1, 2, 3 ],
+		[ 4, 5, 6 ],
+		[ 7, 8, 9.123 ],
+	]
+)>
+```
+
+Please note that in this case the output of the very last `float` in the matrix might be rounded to three digits as defined by the processor `float_round3`. This is different to an implementation providing `_dumpVarNames()`.
+
+### Processors
+
+For producing output you can apply a processor that will preprocess the output before writing it to STDOUT. This is useful to achieve a more human readable representation of data in some cases.
+
+These are the processors you can use:
+
+| **Name**			| **Description**				|
+| ---				| ---							|
+| `float_round1`	| Round to 1 fractional digit	|
+| `float_round2`	| Round to 2 fractional digit	|
+| `float_round3`	| Round to 3 fractional digit	|
+| `float_round4`	| Round to 4 fractional digit	|
+| `float_round5`	| Round to 5 fractional digit	|
+| `float_round6`	| Round to 6 fractional digit	|
+| `float_round7`	| Round to 7 fractional digit	|
+| `int_hex`			| Convert to hexadecimal representation		|
+| `int_bit`			| Convert to binary representation		|
+| `str_shorten`		| Shorten a string to at most 40 characters. If you have objects with large amounts of text this feature can make your output more readable.	|
+
+Futher Development
+-------------------
+
+It is likely that future developments will add more alternatives for dumping an objects. If you have any ideas, requirements or recommendations please feel free to leave a comment.
+
+Contact Information
+-------------------
+
+This is Open Source code. That not only gives you the possibility of freely using this code it also
+allows you to contribute. Feel free to contact the author(s) of this software listed below, either
+for comments, collaboration requests, suggestions for improvement or reporting bugs:
+
+* Jürgen Knauth: pubsrc@binary-overflow.de
+
+License
+-------
+
+This software is provided under the following license:
+
+* Apache Software License 2.0
+
+
+

jk_prettyprintobj-0.2024.2.18/jk_prettyprintobj/_Bits.py

@@ -0,0 +1,52 @@
+
+
+
+#
+# This class wraps around an integer value and represents a value in binary representation.
+# This is used to simlify output.
+#
+class _Bits(object):
+
+	__slots__ = (
+		"value",
+	)
+
+	def __init__(self, value:int):
+		assert isinstance(value, int)
+		assert value >= 0
+		self.value = value
+	#
+
+	def __repr__(self):
+		s = bin(self.value)[2:]
+		n = len(s)
+		if (n == 8) or (n == 16) or (n == 32) or (n == 64):
+			return "b" + s
+		elif n < 8:
+			r = n % 8
+			return "b" + ("0" * (8 - r)) + s
+		elif n < 16:
+			r = n % 16
+			return "b" + ("0" * (16 - r)) + s
+		elif n < 32:
+			r = n % 32
+			return "b" + ("0" * (32 - r)) + s
+		elif n < 64:
+			r = n % 64
+			return "b" + ("0" * (64 - r)) + s
+		else:
+			r = n % 8
+			return "b" + ("0" * (8 - r)) + s
+	#
+
+	def __str__(self):
+		return self.__repr__()
+	#
+
+#
+
+
+
+
+
+

jk_prettyprintobj-0.2024.2.18/jk_prettyprintobj/_Hex.py

@@ -0,0 +1,42 @@
+
+
+
+#
+# This class wraps around an integer value and represents a hex value.
+# This is used to simlify output.
+#
+class _Hex(object):
+
+	__slots__ = (
+		"value",
+	)
+
+	def __init__(self, value:int):
+		assert isinstance(value, int)
+		assert value >= 0
+		self.value = value
+	#
+
+	def __repr__(self):
+		s = hex(self.value)[2:]
+		n = len(s)
+		if n == 1:
+			return "x0" + s
+		elif n == 2:
+			return "x" + s
+		else:
+			r = n % 4
+			return "x" + ("0" * (4 - r)) + s
+	#
+
+	def __str__(self):
+		return self.__repr__()
+	#
+
+#
+
+
+
+
+
+

jk_prettyprintobj-0.2024.2.18/jk_prettyprintobj/__init__.py

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

jk_prettyprintobj-0.2024.2.18/jk_prettyprintobj/dumper.py

@@ -0,0 +1,767 @@
+
+
+import chunk
+import typing
+import collections
+import math
+import codecs
+#import datetime
+
+from ._Hex import _Hex
+from ._Bits import _Bits
+
+
+
+################################################################################################################################
+################################################################################################################################
+##
+## 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
+#
+
+
+
+
+
+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),
+
+	"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),
+}
+
+
+
+
+class _Omitted:
+	pass
+#
+
+class RawValue:
+
+	def __init__(self, text:str) -> None:
+		self.text = text
+	#
+
+#
+
+_OMITTED = _Omitted()
+
+
+
+
+
+class DumpCtx(object):
+
+	_TYPE_MAP = {}				# type -> function
+
+	def __init__(self, s:DumperSettings, outputLines:list, exitAppend:str, prefix:str):
+		self.__s = s
+		self.outputLines = outputLines
+		self.__exitAppend = exitAppend
+		self.prefix = prefix
+	#
+
+	################################################################################################################################
+	#### Methods that should be called by implementors
+	################################################################################################################################
+
+	#
+	# if you implement `void _dump(DumpCtx ctx)` invoke this method to dump a specific variable explicitely.
+	#
+	def dumpVar(self, varName:str, value, processorName:str = None) -> None:
+		self._dumpX(varName + " = ", value, processorName)
+	#
+
+	def dumpVarRaw(self, varName:str, value:RawValue) -> None:
+		self._dumpX(varName + " = ", value.text)
+	#
+
+	#
+	# This method is invoked if an object implements _dumpVarNames()
+	#
+	def dumpVars(self, caller, *args):
+		if len(args) == 0:
+			if hasattr(caller, "_dumpVarNames"):
+				varNames = caller._dumpVarNames()
+				assert isinstance(varNames, (list, tuple))
+			else:
+				raise Exception("Specify either variable names or a list of variables to dump!")
+
+		elif len(args) == 1:
+			if isinstance(args[0], str):
+				varNames = args
+			elif isinstance(args[0], (tuple, list)):
+				varNames = args[0]
+			else:
+				raise Exception("Unexpected data in args: " + repr(args))
+
+		else:
+			varNames = args
+
+		for varName in varNames:
+			assert isinstance(varName, str)
+
+			processorName = None
+			pos = varName.find(":")
+			if pos == 0:
+				raise Exception()
+			elif pos > 0:
+				processorName = varName[pos+1:]
+				varName = varName[:pos]
+
+			value = getattr(caller, varName)
+			self._dumpX(varName + " = ", value, processorName)
+	#
+
+	################################################################################################################################
+	#### Dispatcher method
+	################################################################################################################################
+
+	#
+	# This method outputs a value (recursively).
+	# To achieve this this method analyses the data type of the specified value and invokes individual type processing methods if available.
+	#
+	def _dumpX(self, extraPrefix:str, value, processorName:str = None):
+		if value is None:
+			self._dumpPrimitive(extraPrefix, None, processorName)
+			return
+
+		# is it a raw value?
+
+		if isinstance(value, RawValue):
+			if processorName is not None:
+				raise Exception("Raw values can not have processors.")
+			self._dumpRawValue(extraPrefix, value)
+			return
+
+		# is it one of our types?
+
+		t = type(value)
+		m = DumpCtx._TYPE_MAP.get(t)
+		if m:
+			m(self, extraPrefix, value, processorName)
+			return
+
+		# is it an object with a DumpMixin?
+
+		if isinstance(value, DumpMixin):
+			self._dumpObj(extraPrefix, value, processorName)
+			return
+
+		# is it derived from on of our types?
+
+		for storedT, m in DumpCtx._TYPE_MAP.items():
+			if isinstance(value, storedT):
+				m(self, extraPrefix, value, processorName)
+				return
+
+		# fallback
+
+		self.outputLines.append(self.prefix + extraPrefix + repr(value))
+	#
+
+	################################################################################################################################
+	#### Type specific dump methods
+	################################################################################################################################
+
+	def _isDumpableObj(self, obj):
+		if hasattr(obj, "_dump"):
+			return True
+		if hasattr(obj, "_dumpVarNames"):
+			return True
+		return False
+	#
+
+	#
+	# Dump the specified object.
+	#
+	# @param	str processorName		(optional) The name of an output processor.
+	#									Supports: "shorten"
+	#
+	def _dumpObj(self, extraPrefix:str, value:object, processorName:str = None):
+		if processorName == "shorten":
+			self.outputLines.append(self.prefix + extraPrefix + "<" + value.__class__.__name__ + "(...)>")
+
+		else:
+			self.outputLines.append(self.prefix + extraPrefix + "<" + value.__class__.__name__ + "(")
+
+			ctx = DumpCtx(self.__s, self.outputLines, None, self.prefix + "\t")
+			with ctx as ctx2:
+				if hasattr(value, "_dump"):
+					value._dump(ctx2)
+				elif hasattr(value, "_dumpVarNames"):
+					ctx2.dumpVars(value)
+				else:
+					raise Exception("Improper object encountered for prettyprinting: " + type(value).__name__)
+
+			self.outputLines.append(self.prefix + ")>")
+	#
+
+	#
+	# Dump the specified dictionary.
+	#
+	def _dumpDict(self, extraPrefix:str, value:dict, processorName:str = None):
+		e = (type(value).__name__ + ":") if self.__s.showComplexStructsWithType else ""
+
+		self.outputLines.append(self.prefix + extraPrefix + e + "{")
+
+		ctx = DumpCtx(self.__s, self.outputLines, None, self.prefix + "\t")
+		with ctx as ctx2:
+			for k, v in value.items():
+				if processorName == "omitValues":
+					v = _OMITTED
+				ctx2._dumpX(self._dictKeyToStr(k) + " : ", v)
+				self.outputLines[-1] += ","
+
+		self.outputLines.append(self.prefix + "}")
+	#
+
+	def _dumpOrderedDict(self, extraPrefix:str, value:dict, processorName:str = None):
+		e = (type(value).__name__ + ":") if self.__s.showComplexStructsWithType else ""
+
+		self.outputLines.append(self.prefix + extraPrefix + e + "{")
+
+		ctx = DumpCtx(self.__s, self.outputLines, None, self.prefix + "\t")
+		with ctx as ctx2:
+			for k, v in value.items():
+				ctx2._dumpX(self._dictKeyToStr(k) + " : ", v)
+				self.outputLines[-1] += ","
+
+		self.outputLines.append(self.prefix + "}")
+	#
+
+	#
+	# Dump the specified list.
+	#
+	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) + " ]")
+
+		else:
+			self.outputLines.append(self.prefix + extraPrefix + e + "[")
+
+			ctx = DumpCtx(self.__s, self.outputLines, None, self.prefix + "\t")
+			with ctx as ctx2:
+				for vItem in value:
+					ctx2._dumpX("", vItem, processorName)
+					self.outputLines[-1] += ","
+
+			self.outputLines.append(self.prefix + "]")
+	#
+
+	#
+	# Dump the specified byte array.
+	#
+	def _dumpBytes(self, extraPrefix:str, value:bytes, processorName:str = None):
+		e = (type(value).__name__ + ":") if self.__s.showComplexStructsWithType else ""
+
+		if len(value) <= self.__s.bytesLineSize:
+			self.outputLines.append(self.prefix + extraPrefix + e + repr(value))
+
+		else:
+			self.outputLines.append(self.prefix + extraPrefix + e + "<")
+
+			for sOfs, chunk, sAscii in _byteChunkerWithOfs(self.__s, value, processorName):
+				self.outputLines.append(self.prefix + "\t" + sOfs + "  " + chunk + "  " + sAscii)
+
+			if len(value) == 1:
+				self.outputLines.append(self.prefix + "\ttotal: 1 byte")
+			else:
+				self.outputLines.append(self.prefix + "\ttotal: " + str(len(value)) + " bytes")
+
+			self.outputLines.append(self.prefix + ">")
+	#
+
+	#
+	# Dump the specified tuple.
+	#
+	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) + " )")
+
+		else:
+			self.outputLines.append(self.prefix + extraPrefix + e + "(")
+
+			ctx = DumpCtx(self.__s, self.outputLines, None, self.prefix + "\t")
+			with ctx as ctx2:
+				for vItem in value:
+					ctx2._dumpX("", vItem, processorName)
+					self.outputLines[-1] += ","
+
+			self.outputLines.append(self.prefix + ")")
+	#
+
+	#
+	# Dump the specified set.
+	#
+	def _dumpSet(self, extraPrefix:str, value:set, processorName:str = None):
+		e = (type(value).__name__ + ":") if self.__s.showComplexStructsWithType else ""
+
+		sequence = sorted(value)
+
+		if self._canCompactSequence(sequence):
+			self.outputLines.append(self.prefix + extraPrefix + e + "{ " + self._compactSequence(sequence, processorName) + " }")
+
+		else:
+			self.outputLines.append(self.prefix + extraPrefix + e + "{")
+
+			ctx = DumpCtx(self.__s, self.outputLines, None, self.prefix + "\t")
+			with ctx as ctx2:
+				for vItem in sequence:
+					ctx2._dumpX("", vItem, processorName)
+					self.outputLines[-1] += ","
+
+			self.outputLines.append(self.prefix + "}")
+	#
+
+	#
+	# Dump the specified frozen set.
+	#
+	def _dumpFrozenSet(self, extraPrefix:str, value:frozenset, processorName:str = None):
+		e = (type(value).__name__ + ":") if self.__s.showComplexStructsWithType else ""
+
+		sequence = sorted(value)
+
+		if self._canCompactSequence(sequence):
+			self.outputLines.append(self.prefix + extraPrefix + e + "{ " + self._compactSequence(sequence, processorName) + " }")
+
+		else:
+			self.outputLines.append(self.prefix + extraPrefix + e + "{")
+
+			ctx = DumpCtx(self.__s, self.outputLines, None, self.prefix + "\t")
+			with ctx as ctx2:
+				for vItem in sequence:
+					ctx2._dumpX("", vItem, processorName)
+					self.outputLines[-1] += ","
+
+			self.outputLines.append(self.prefix + "}")
+	#
+
+	def _dumpPrimitive(self, extraPrefix:str, value, processorName:str = None):
+		self.outputLines.append(self.prefix + extraPrefix + self._primitiveValueToStr(value, processorName))
+	#
+
+	def _dumpRawValue(self, extraPrefix:str, value:RawValue):
+		self.outputLines.append(self.prefix + extraPrefix + value.text)
+	#
+
+	def _dumpOmitted(self, extraPrefix:str, value, processorName:str = None):
+		self.outputLines.append(self.prefix + extraPrefix + "...")
+	#
+
+	################################################################################################################################
+	#### Helper methods
+	################################################################################################################################
+
+	def _canCompactSequence(self, someSequence):
+		if len(someSequence) > self.__s.compactSequenceLengthLimit:
+			return False
+		for v in someSequence:
+			if v is not None:
+				if type(v) not in [ int, str, float, bool ]:
+					return False
+				if isinstance(v, str):
+					if len(v) > self.__s.compactSequenceItemLengthLimit:
+						return False
+		return True
+	#
+
+	def _compactSequence(self, someSequence, processorName:str = None) -> str:
+		ret = []
+		for v in someSequence:
+			ret.append(self._primitiveValueToStr(v, processorName))
+		return ", ".join(ret)
+	#
+
+	#
+	# Converts a single dictionary key to str
+	#
+	def _dictKeyToStr(self, value):
+		if value is None:
+			return "(null)"
+		else:
+			if self.__s.showDictKeysWithType:
+				if isinstance(value, float):
+					return "float:" + repr(value)
+				elif isinstance(value, bool):
+					return "bool:" + repr(value)
+				elif isinstance(value, int):
+					return "int:" + repr(value)
+				else:
+					return type(value).__name__ + ":" + repr(value)
+			else:
+				return repr(value)
+	#
+
+	#
+	# Converts a single primitive value to str
+	#
+	def _primitiveValueToStr(self, value, processorName:str = None):
+		if value is None:
+			return "(null)"
+		else:
+			# process value before converting it to str
+			if processorName:
+				if processorName not in POST_PROCESSORS:
+					raise Exception("No such postprocessor: " + repr(processorName))
+				postProcessorTypeCompatibility, postProcessor = POST_PROCESSORS[processorName]
+				if isinstance(value, postProcessorTypeCompatibility):
+					value = postProcessor(value)
+
+			# return value as str
+			if self.__s.showPrimitivesWithType:
+				if isinstance(value, float):
+					return "float:" + repr(value)
+				elif isinstance(value, bool):
+					return "bool:" + repr(value)
+				elif isinstance(value, int):
+					return "int:" + repr(value)
+				elif isinstance(value, str):
+					return "str:" + repr(value)
+				else:
+					return type(value).__name__ + ":" + repr(value)
+			else:
+				if isinstance(value, str):
+					return repr(value)
+				else:
+					return repr(value)
+	#
+
+	################################################################################################################################
+	#### Magic methods
+	################################################################################################################################
+
+	def __enter__(self):
+		return self
+	#
+
+	def __exit__(self, *args):
+		if self.__exitAppend:
+			self.outputLines.append(self.__exitAppend)
+		return False
+	#
+
+#
+
+
+
+
+#
+# Now let's register the types
+#
+if not DumpCtx._TYPE_MAP:
+	DumpCtx._TYPE_MAP[bytes] = DumpCtx._dumpBytes
+	DumpCtx._TYPE_MAP[set] = DumpCtx._dumpSet
+	DumpCtx._TYPE_MAP[frozenset] = DumpCtx._dumpFrozenSet
+	DumpCtx._TYPE_MAP[tuple] = DumpCtx._dumpTuple
+	DumpCtx._TYPE_MAP[list] = DumpCtx._dumpList
+	DumpCtx._TYPE_MAP[collections.OrderedDict] = DumpCtx._dumpOrderedDict
+	DumpCtx._TYPE_MAP[dict] = DumpCtx._dumpDict
+	DumpCtx._TYPE_MAP[int] = DumpCtx._dumpPrimitive
+	DumpCtx._TYPE_MAP[float] = DumpCtx._dumpPrimitive
+	DumpCtx._TYPE_MAP[bool] = DumpCtx._dumpPrimitive
+	DumpCtx._TYPE_MAP[str] = DumpCtx._dumpPrimitive
+	DumpCtx._TYPE_MAP[_Omitted] = DumpCtx._dumpOmitted
+
+
+
+
+
+
+class Dumper(object):
+
+	def __init__(self):
+		self.__outputLines = []
+		self.__contexts = []
+		self.__currentPrefix = ""
+	#
+
+	def createContext(self, obj, prefix:str = None):
+		if prefix is not None:
+			assert isinstance(prefix, str)
+		else:
+			prefix = ""
+
+		return DumpCtx(DEFAULT_DUMPER_SETTINGS, self.__outputLines, None, prefix)
+	#
+
+	def print(self, printFunc = None):
+		if printFunc is None:
+			printFunc = print
+		else:
+			assert callable(printFunc)
+
+		for line in self.__outputLines:
+			printFunc(line)
+	#
+
+	def toStr(self) -> str:
+		return "\n".join(self.__outputLines)
+	#
+
+#
+
+
+
+
+
+class DumpMixin:
+
+	__slots__ = tuple()
+
+	def dump(self, prefix:str = None, printFunc = None) -> None:
+		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.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)
+		return dumper.toStr()
+	#
+
+#
+
+
+
+
+
+
+
+
+
+
+
+

jk_prettyprintobj-0.2024.2.18/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "jk_prettyprintobj"
+dynamic = [ "version" ]
+authors = [
+	{ name = "Jürgen Knauth", email = "pubsrc@binary-overflow.de" },
+]
+maintainers = [
+	{ name = "Jürgen Knauth", email = "pubsrc@binary-overflow.de" },
+]
+description = "This python module provides a mixin for creating pretty debugging output for objects. This is especially useful for semi-complex data structures."
+readme = "README.md"
+requires-python = ">=3.8"
+keywords = [
+	"pretty-print",
+	"debugging",
+	"debug",
+]
+license = { text = "Apache2" }
+classifiers = [
+	"Development Status :: 5 - Production/Stable",
+	"License :: OSI Approved :: Apache Software License",
+	"Programming Language :: Python :: 3",
+	"Topic :: Software Development :: Testing",
+]
+dependencies = [
+]
+
+#[project.urls]
+#Homepage = "https://example.com"
+#Documentation = "https://readthedocs.org"
+#Repository = "https://github.com/me/spam.git"
+#Changelog = "https://github.com/me/spam/blob/master/CHANGELOG.md"
+
+[tool.flit.sdist]
+exclude = [
+	"bin/",
+	"build/",
+	"dist/",
+	"sdist/",
+	"*.egg-info",
+	"*.OLD",
+	"setup.cfg",
+]
+
+#[project.scripts]
+
+
+
+
+