Add detailed trace mode showing saved object size and visual depth le…

…vel (#471)

* Add detailed trace mode showing dumped object size and visual depeth level

* Tests: logging code coverage

* logger: just show size after writing object

* Box drawing formatting

* fallback for non-UTF-8 terminals

* review: corrections and improvements

* review: adjustments

* split module imports into separated lines

* deal with non-standardized UTF-8 encoding name

* update sample trace in module docs

* use trace() as a context manager

* pypy special cases

* accept file handle in trace context manager

* fix dict (PyPy) and mappingproxy (CPython) trace

Co-authored-by: anivegesana <anirudh.vegesana@gmail.com>

README.md

@@ -170,26 +170,30 @@ To aid in debugging pickling issues, use *dill.detect* which provides
 tools like pickle tracing::
 
     >>> import dill.detect
-    >>> dill.detect.trace(True)
-    >>> f = dumps(squared)
-    F1: <function <lambda> at 0x108899e18>
-    F2: <function _create_function at 0x108db7488>
-    # F2
-    Co: <code object <lambda> at 0x10866a270, file "<stdin>", line 1>
-    F2: <function _create_code at 0x108db7510>
-    # F2
-    # Co
-    D1: <dict object at 0x10862b3f0>
-    # D1
-    D2: <dict object at 0x108e42ee8>
-    # D2
-    # F1
-    >>> dill.detect.trace(False)
+    >>> with dill.detect.trace():
+    >>>     dumps(squared)
+    ┬ F1: <function <lambda> at 0x7fe074f8c280>
+    ├┬ F2: <function _create_function at 0x7fe074c49c10>
+    │└ # F2 [34 B]
+    ├┬ Co: <code object <lambda> at 0x7fe07501eb30, file "<stdin>", line 1>
+    │├┬ F2: <function _create_code at 0x7fe074c49ca0>
+    ││└ # F2 [19 B]
+    │└ # Co [87 B]
+    ├┬ D1: <dict object at 0x7fe0750d4680>
+    │└ # D1 [22 B]
+    ├┬ D2: <dict object at 0x7fe074c5a1c0>
+    │└ # D2 [2 B]
+    ├┬ D2: <dict object at 0x7fe074f903c0>
+    │├┬ D2: <dict object at 0x7fe074f8ebc0>
+    ││└ # D2 [2 B]
+    │└ # D2 [23 B]
+    └ # F1 [180 B]
 
 With trace, we see how ``dill`` stored the lambda (``F1``) by first storing
 ``_create_function``, the underlying code object (``Co``) and ``_create_code``
 (which is used to handle code objects), then we handle the reference to
-the global dict (``D2``).  A ``#`` marks when the object is actually stored.
+the global dict (``D2``) plus other dictionaries (``D1`` and ``D2``) that
+save the lambda object's state. A ``#`` marks when the object is actually stored.
 
 
 More Information

dill/__init__.py

@@ -185,26 +185,30 @@
 tools like pickle tracing::
 
     >>> import dill.detect
-    >>> dill.detect.trace(True)
-    >>> f = dumps(squared)
-    F1: <function <lambda> at 0x108899e18>
-    F2: <function _create_function at 0x108db7488>
-    # F2
-    Co: <code object <lambda> at 0x10866a270, file "<stdin>", line 1>
-    F2: <function _create_code at 0x108db7510>
-    # F2
-    # Co
-    D1: <dict object at 0x10862b3f0>
-    # D1
-    D2: <dict object at 0x108e42ee8>
-    # D2
-    # F1
-    >>> dill.detect.trace(False)
+    >>> with dill.detect.trace():
+    >>>     dumps(squared)
+    ┬ F1: <function <lambda> at 0x7fe074f8c280>
+    ├┬ F2: <function _create_function at 0x7fe074c49c10>
+    │└ # F2 [34 B]
+    ├┬ Co: <code object <lambda> at 0x7fe07501eb30, file "<stdin>", line 1>
+    │├┬ F2: <function _create_code at 0x7fe074c49ca0>
+    ││└ # F2 [19 B]
+    │└ # Co [87 B]
+    ├┬ D1: <dict object at 0x7fe0750d4680>
+    │└ # D1 [22 B]
+    ├┬ D2: <dict object at 0x7fe074c5a1c0>
+    │└ # D2 [2 B]
+    ├┬ D2: <dict object at 0x7fe074f903c0>
+    │├┬ D2: <dict object at 0x7fe074f8ebc0>
+    ││└ # D2 [2 B]
+    │└ # D2 [23 B]
+    └ # F1 [180 B]
 
 With trace, we see how ``dill`` stored the lambda (``F1``) by first storing
 ``_create_function``, the underlying code object (``Co``) and ``_create_code``
 (which is used to handle code objects), then we handle the reference to
-the global dict (``D2``).  A ``#`` marks when the object is actually stored.
+the global dict (``D2``) plus other dictionaries (``D1`` and ``D2``) that
+save the lambda object's state. A ``#`` marks when the object is actually stored.
 
 
 More Information