memory-graph 0.3.6__tar.gz → 0.3.7__tar.gz

{memory_graph-0.3.6/memory_graph.egg-info → memory_graph-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: memory_graph
-Version: 0.3.6
+Version: 0.3.7
 Summary: Draws a graph of your data to analyze its structure.
 Home-page: https://github.com/bterwijn/memory_graph
 Author: Bas Terwijn
@@ -80,11 +80,11 @@ class MyClass:
         self.y = y
 
 data = [ range(1, 2), (3, 4), {5, 6}, {7:'seven', 8:'eight'},  MyClass(9, 10) ]
-mg.show(data, block=True)
+mg.show(data)
 ```
 ![many_types.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/many_types.png)
 
-By using `block=True` the program blocks until the <Enter> key is pressed so you can view the graph before continuing program execution (and possibly viewing later graphs). Instead of showing the graph you can also render it to an output file of your choosing (see [Graphviz Output Formats](https://graphviz.org/docs/outputs/)) using for example:
+Instead of showing the graph you can also render it to an output file of your choosing (see [Graphviz Output Formats](https://graphviz.org/docs/outputs/)) using for example:
 
 ```python
 mg.render(data, "my_graph.pdf")
@@ -190,7 +190,7 @@ mg.show(locals())
 
 
 ### Custom Copy Method ###
-We can write our own custom copy function or method in case the three "copy" options don't do what we want. For example the copy() method of My_Class in the code below copies the `digits` but shares the `letters` between the two objects.
+We can write our own custom copy function or method in case the three "copy" options don't do what we want. For example, in the code below the copy() method of My_Class copies the `digits` but shares the `letters` between two objects.
 
 ```python
 import memory_graph as mg
@@ -216,7 +216,7 @@ mg.show(locals())
 
 
 ## Call Stack ##
-The function `mg.get_call_stack()` returns the complete call stack, including all local variables for each function in the stack. This allows us to simultaneously visualize the local variables of all the called functions. By doing so, we can identify whether any local variables from different functions in the call stack share data with one another. Here for example we call function ```add_one()``` with arguments ```a, b, c``` that adds 1 to each of its arguments.
+The `mg.get_call_stack()` function retrieves the entire call stack, including the local variables for each function on the stack. This enables us to visualize the local variables across all active functions simultaneously. Then by examining the graph, we can determine whether any local variables from different functions on the call stack share data. For instance, consider the function `add_one()` which adds the value `1` to each of its parameters, `a`, `b`, and `c`.
 
 ```python
 import memory_graph as mg
@@ -243,9 +243,17 @@ a:[4, 3, 2, 1] b:(4, 3, 2) c:[4, 3, 2]
 
 This is because `b` is of immutable type 'tuple' so its value gets copied automatically when it is changed. And because the function is called with a copy of `c`, its original value is not changed by the function. The value of variable `a` is the only value of mutable type that is shared between the root stack frame **'0: \<module>'** and the **'1: add_one'** stack frame of the function so only that variable is affected as a result of the function call. The other changes remain confined to the local variables of the ```add_one()``` function.
 
+### Block ###
+It is often helpful to temporarily block program execution to inspect the graph. For this, you can use the `mg.block()` function:
+
+```python
+mg.block(fun, arg1, arg2, ..., loc=True) 
+```
+
+This function first executes `fun(arg1, arg2, ...)`, then prints the current source location in the program, and blocks execution until the &lt;Enter&gt; key is pressed. To skip printing the source location, set `loc=False`.
 
 ### Recursion ###
-The call stack can be used to visualize how recursion works. Here we show each step of how recursively ```factorial(3)``` is computed:
+The call stack is also helpful to visualize how recursion works. Here we use `mg.block()` to show each step of how recursively ```factorial(3)``` is computed:
 
 ```python
 import memory_graph as mg
@@ -253,28 +261,26 @@ import memory_graph as mg
 def factorial(n):
     if n==0:
         return 1
-    mg.show( mg.get_call_stack(), block=True )
+    mg.block(mg.show, mg.get_call_stack())
     result = n * factorial(n-1)
-    mg.show( mg.get_call_stack(), block=True )
+    mg.block(mg.show, mg.get_call_stack())
     return result
 
 print(factorial(3))
 ```
 
-Execution results in:
-
 ![factorial.gif](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/factorial.gif)
 
 and the result is: 1 x 2 x 3 = 6
 
 ### Power Set ###
-A more insteresting recursive example that shows sharing of data is power_set(). A power set is the set of all subsets of a collection of values.
+A more interesting recursive example that shows sharing of data is power_set(). A power set is the set of all subsets of a collection of values.
 
 ```python
 import memory_graph as mg
 
 def get_subsets(subsets, data, i, subset):
-    mg.show(mg.get_call_stack(), block=True)
+    mg.block(mg.show, mg.get_call_stack())
     if i == len(data):
         subsets.append(subset.copy())
         return
@@ -282,7 +288,7 @@ def get_subsets(subsets, data, i, subset):
     get_subsets(subsets, data, i+1, subset) #    do include data[i]
     subset.pop()
     get_subsets(subsets, data, i+1, subset) # don't include data[i]
-    mg.show(mg.get_call_stack(), block=True)
+    mg.block(mg.show, mg.get_call_stack())
 
 def power_set(data):
     subsets = []
@@ -292,8 +298,6 @@ def power_set(data):
 print( power_set(['a', 'b', 'c']) )
 ```
 
-Execution results in:
-
 ![power_set.gif](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/power_set.gif)
 ```
 [['a', 'b', 'c'], ['a', 'b'], ['a', 'c'], ['a'], ['b', 'c'], ['b'], ['c'], []]
@@ -329,49 +333,28 @@ mg.get_call_stack_after_up_to(after_function, up_to_function="<module>")
 
 ### Debugging without Debugger Tool ###
 
-To make debugging without a debugger tool easier we provide these alias functions that you can add to your code where you want to view a graph:
-
-| alias | function|
-|:---|:---|
-| `d()` | `mg.show(locals(), block=True)` |
-| `ds()` | `mg.show(mg.get_call_stack(), block=True)` |
+To simplify debugging without a debugger tool, we offer these blocking alias functions that you can insert into your code at a specific point to visualize a graph:
 
-These functions have the following default arguments:
-```python
-def d(data=None, graph=True, log=False, block=True):
-```
-- data: defaults to locals() and mg.get_call_stack() respectively
-- graph: if True the data is visualized as a graph
-- log: if True the data is printed
-- block: if True the function blocks until the &lt;Enter&gt; key is pressed
-
-To print to a log file instead of standard output use:
-```python
-mg.log_file = open("my_log_file.txt", "w")
-```
+| alias | purpose | function call |
+|:---|:---|:---|
+| `mg.l()` | graph **l**ocal variables | `mg.block(mg.show, locals())` |
+| `mg.s()` | graph the call **s**tack | `mg.block(mg.show, mg.get_call_stack())` |
 
 For example, executing this program:
 
 ```python
-import memory_graph as mg
-from memory_graph import d, ds
+from memory_graph as mg
 
 squares = []
 squares_collector = []
 for i in range(1, 6):
     squares.append(i**2)
     squares_collector.append(squares.copy())
-    d(log=True)
+    mg.l() # graph local variables
 ```
-and pressing &lt;Enter&gt; a number of times, produces:
+and pressing &lt;Enter&gt; a number of times, results in:
 
 ![debugging.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/debugging.gif)
-```
-squares: [1, 4, 9, 16, 25]
-squares_collector: [[1], [1, 4], [1, 4, 9], [1, 4, 9, 16], [1, 4, 9, 16, 25]]
-i: 5
-```
-
 
 ## Datastructure Examples ##
 Module memory_graph can be very useful in a course about datastructures, some examples:
@@ -404,7 +387,7 @@ class LinkedList:
             new_node.next = self.head
             self.head.prev = new_node
             self.head = new_node
-        mg.show(locals(), block=True) # <--- draw graph
+        mg.block(mg.show, locals()) # <--- draw graph
 
 linked_list = LinkedList()
 n = 100
@@ -443,7 +426,7 @@ class BinTree:
                 node.larger = Node(new_value)
             else:
                 self.add_recursive(new_value, node.larger)
-        mg.show(locals(), block=True) # <--- draw graph
+        mg.block(mg.show, locals()) # <--- draw graph
 
     def add(self, value):
         if self.root is None:
@@ -476,7 +459,7 @@ class HashSet:
             self.buckets[index] = []
         bucket = self.buckets[index]
         bucket.append(value)
-        mg.show(locals(), block=True) # <--- draw graph
+        mg.block(mg.show, locals()) # <--- draw graph
 
     def contains(self, value):
         index = hash(value) % len(self.buckets)
@@ -499,10 +482,10 @@ for i in range(n):
 
 
 ## Configuration ##
-Different aspects of memory_graph can be configured. The default configuration is reset by importing 'mg.config_default'.
+Different aspects of memory_graph can be configured. The default configuration is reset by importing 'memory_graph.config_default'.
 
-- ***mg.config.max_number_nodes*** : int
-  - The maxium number of Nodes shown in the graph. When the graph gets too big set this to a smaller number. A `★` symbol indictes where the graph is cut short.
+- ***mg.config.max_tree_depth*** : int
+  - The maxium depth of the graph. A `★` symbol indictes where the graph is cut short.
 
 - ***mg.config.max_string_length*** : int
   - The maximum length of strings shown in the graph. Longer strings will be truncated.
@@ -547,7 +530,7 @@ mg.show( locals(),
 Different extensions are available for types from other Python packages. 
 
 ### Numpy ###
-Numpy types `arrray` and `matrix` and `ndarray` can be graphed with the "memory_graph.extension_numpy" extension:
+Numpy types `arrray` and `matrix` and `ndarray` can be graphed with "memory_graph.extension_numpy":
 
 ```python
 import memory_graph as mg
@@ -558,12 +541,12 @@ np.random.seed(0) # use same random numbers each run
 array = np.array([1.1, 2, 3, 4, 5])
 matrix = np.matrix([[i*20+j for j in range(20)] for i in range(20)])
 ndarray = np.random.rand(20,20)
-mg.show(locals(), block=True)
+mg.show(locals())
 ```
 ![extension_numpy.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/extension_numpy.png)
 
 ### Pandas ###
-Pandas types `Series` and `DataFrame` can be graphed with the "memory_graph.extension_pandas" extension:
+Pandas types `Series` and `DataFrame` can be graphed with "memory_graph.extension_pandas":
 
 ```python
 import memory_graph as mg
@@ -577,7 +560,7 @@ dataframe2 = pd.DataFrame({  'Name'   : [ 'Tom', 'Anna', 'Steve', 'Lisa'],
                              'Age'    : [    28,     34,      29,     42],
                              'Length' : [  1.70,   1.66,    1.82,   1.73] },
                             index=['one', 'two', 'three', 'four']) # with row names
-mg.show(locals(), block=True)
+mg.show(locals())
 ```
 ![extension_pandas.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/extension_pandas.png)
 
@@ -591,6 +574,6 @@ See for example [jupyter_example.ipynb](https://raw.githubusercontent.com/bterwi
 
 ## Troubleshooting ##
 
-- Adobe Acrobat Reader [doesn't refresh a PDF file](https://superuser.com/questions/337011/windows-pdf-viewer-that-auto-refreshes-pdf-when-compiling-with-pdflatex) when it changes on disk and blocks updates which results in an `Could not open 'somefile.pdf' for writing : Permission denied` error. One solution is to install a PDF reader that does refresh ([Evince](https://www.fosshub.com/Evince.html) for example) and set it as the default PDF reader. Another solution is to `render()` the graph to a different output format and open it manually.
+- Adobe Acrobat Reader [doesn't refresh a PDF file](https://superuser.com/questions/337011/windows-pdf-viewer-that-auto-refreshes-pdf-when-compiling-with-pdflatex) when it changes on disk and blocks updates which results in an `Could not open 'somefile.pdf' for writing : Permission denied` error. One solution is to install a PDF reader that does refresh ([Evince](https://www.fosshub.com/Evince.html), [Okular](https://okular.kde.org/), [SumatraPDF](https://www.sumatrapdfreader.org/), ...) and set it as the default PDF reader. Another solution is to `render()` the graph to a different output format and to open it manually.
 
 - When graph edges overlap it can be hard to distinguish them. Using an interactive graphviz viewer, such as [xdot](https://github.com/jrfonseca/xdot.py), on a '*.gv' DOT output file will help.

{memory_graph-0.3.6 → memory_graph-0.3.7}/README.md

@@ -61,11 +61,11 @@ class MyClass:
         self.y = y
 
 data = [ range(1, 2), (3, 4), {5, 6}, {7:'seven', 8:'eight'},  MyClass(9, 10) ]
-mg.show(data, block=True)
+mg.show(data)
 ```
 ![many_types.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/many_types.png)
 
-By using `block=True` the program blocks until the <Enter> key is pressed so you can view the graph before continuing program execution (and possibly viewing later graphs). Instead of showing the graph you can also render it to an output file of your choosing (see [Graphviz Output Formats](https://graphviz.org/docs/outputs/)) using for example:
+Instead of showing the graph you can also render it to an output file of your choosing (see [Graphviz Output Formats](https://graphviz.org/docs/outputs/)) using for example:
 
 ```python
 mg.render(data, "my_graph.pdf")
@@ -171,7 +171,7 @@ mg.show(locals())
 
 
 ### Custom Copy Method ###
-We can write our own custom copy function or method in case the three "copy" options don't do what we want. For example the copy() method of My_Class in the code below copies the `digits` but shares the `letters` between the two objects.
+We can write our own custom copy function or method in case the three "copy" options don't do what we want. For example, in the code below the copy() method of My_Class copies the `digits` but shares the `letters` between two objects.
 
 ```python
 import memory_graph as mg
@@ -197,7 +197,7 @@ mg.show(locals())
 
 
 ## Call Stack ##
-The function `mg.get_call_stack()` returns the complete call stack, including all local variables for each function in the stack. This allows us to simultaneously visualize the local variables of all the called functions. By doing so, we can identify whether any local variables from different functions in the call stack share data with one another. Here for example we call function ```add_one()``` with arguments ```a, b, c``` that adds 1 to each of its arguments.
+The `mg.get_call_stack()` function retrieves the entire call stack, including the local variables for each function on the stack. This enables us to visualize the local variables across all active functions simultaneously. Then by examining the graph, we can determine whether any local variables from different functions on the call stack share data. For instance, consider the function `add_one()` which adds the value `1` to each of its parameters, `a`, `b`, and `c`.
 
 ```python
 import memory_graph as mg
@@ -224,9 +224,17 @@ a:[4, 3, 2, 1] b:(4, 3, 2) c:[4, 3, 2]
 
 This is because `b` is of immutable type 'tuple' so its value gets copied automatically when it is changed. And because the function is called with a copy of `c`, its original value is not changed by the function. The value of variable `a` is the only value of mutable type that is shared between the root stack frame **'0: \<module>'** and the **'1: add_one'** stack frame of the function so only that variable is affected as a result of the function call. The other changes remain confined to the local variables of the ```add_one()``` function.
 
+### Block ###
+It is often helpful to temporarily block program execution to inspect the graph. For this, you can use the `mg.block()` function:
+
+```python
+mg.block(fun, arg1, arg2, ..., loc=True) 
+```
+
+This function first executes `fun(arg1, arg2, ...)`, then prints the current source location in the program, and blocks execution until the &lt;Enter&gt; key is pressed. To skip printing the source location, set `loc=False`.
 
 ### Recursion ###
-The call stack can be used to visualize how recursion works. Here we show each step of how recursively ```factorial(3)``` is computed:
+The call stack is also helpful to visualize how recursion works. Here we use `mg.block()` to show each step of how recursively ```factorial(3)``` is computed:
 
 ```python
 import memory_graph as mg
@@ -234,28 +242,26 @@ import memory_graph as mg
 def factorial(n):
     if n==0:
         return 1
-    mg.show( mg.get_call_stack(), block=True )
+    mg.block(mg.show, mg.get_call_stack())
     result = n * factorial(n-1)
-    mg.show( mg.get_call_stack(), block=True )
+    mg.block(mg.show, mg.get_call_stack())
     return result
 
 print(factorial(3))
 ```
 
-Execution results in:
-
 ![factorial.gif](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/factorial.gif)
 
 and the result is: 1 x 2 x 3 = 6
 
 ### Power Set ###
-A more insteresting recursive example that shows sharing of data is power_set(). A power set is the set of all subsets of a collection of values.
+A more interesting recursive example that shows sharing of data is power_set(). A power set is the set of all subsets of a collection of values.
 
 ```python
 import memory_graph as mg
 
 def get_subsets(subsets, data, i, subset):
-    mg.show(mg.get_call_stack(), block=True)
+    mg.block(mg.show, mg.get_call_stack())
     if i == len(data):
         subsets.append(subset.copy())
         return
@@ -263,7 +269,7 @@ def get_subsets(subsets, data, i, subset):
     get_subsets(subsets, data, i+1, subset) #    do include data[i]
     subset.pop()
     get_subsets(subsets, data, i+1, subset) # don't include data[i]
-    mg.show(mg.get_call_stack(), block=True)
+    mg.block(mg.show, mg.get_call_stack())
 
 def power_set(data):
     subsets = []
@@ -273,8 +279,6 @@ def power_set(data):
 print( power_set(['a', 'b', 'c']) )
 ```
 
-Execution results in:
-
 ![power_set.gif](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/power_set.gif)
 ```
 [['a', 'b', 'c'], ['a', 'b'], ['a', 'c'], ['a'], ['b', 'c'], ['b'], ['c'], []]
@@ -310,49 +314,28 @@ mg.get_call_stack_after_up_to(after_function, up_to_function="<module>")
 
 ### Debugging without Debugger Tool ###
 
-To make debugging without a debugger tool easier we provide these alias functions that you can add to your code where you want to view a graph:
-
-| alias | function|
-|:---|:---|
-| `d()` | `mg.show(locals(), block=True)` |
-| `ds()` | `mg.show(mg.get_call_stack(), block=True)` |
+To simplify debugging without a debugger tool, we offer these blocking alias functions that you can insert into your code at a specific point to visualize a graph:
 
-These functions have the following default arguments:
-```python
-def d(data=None, graph=True, log=False, block=True):
-```
-- data: defaults to locals() and mg.get_call_stack() respectively
-- graph: if True the data is visualized as a graph
-- log: if True the data is printed
-- block: if True the function blocks until the &lt;Enter&gt; key is pressed
-
-To print to a log file instead of standard output use:
-```python
-mg.log_file = open("my_log_file.txt", "w")
-```
+| alias | purpose | function call |
+|:---|:---|:---|
+| `mg.l()` | graph **l**ocal variables | `mg.block(mg.show, locals())` |
+| `mg.s()` | graph the call **s**tack | `mg.block(mg.show, mg.get_call_stack())` |
 
 For example, executing this program:
 
 ```python
-import memory_graph as mg
-from memory_graph import d, ds
+from memory_graph as mg
 
 squares = []
 squares_collector = []
 for i in range(1, 6):
     squares.append(i**2)
     squares_collector.append(squares.copy())
-    d(log=True)
+    mg.l() # graph local variables
 ```
-and pressing &lt;Enter&gt; a number of times, produces:
+and pressing &lt;Enter&gt; a number of times, results in:
 
 ![debugging.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/debugging.gif)
-```
-squares: [1, 4, 9, 16, 25]
-squares_collector: [[1], [1, 4], [1, 4, 9], [1, 4, 9, 16], [1, 4, 9, 16, 25]]
-i: 5
-```
-
 
 ## Datastructure Examples ##
 Module memory_graph can be very useful in a course about datastructures, some examples:
@@ -385,7 +368,7 @@ class LinkedList:
             new_node.next = self.head
             self.head.prev = new_node
             self.head = new_node
-        mg.show(locals(), block=True) # <--- draw graph
+        mg.block(mg.show, locals()) # <--- draw graph
 
 linked_list = LinkedList()
 n = 100
@@ -424,7 +407,7 @@ class BinTree:
                 node.larger = Node(new_value)
             else:
                 self.add_recursive(new_value, node.larger)
-        mg.show(locals(), block=True) # <--- draw graph
+        mg.block(mg.show, locals()) # <--- draw graph
 
     def add(self, value):
         if self.root is None:
@@ -457,7 +440,7 @@ class HashSet:
             self.buckets[index] = []
         bucket = self.buckets[index]
         bucket.append(value)
-        mg.show(locals(), block=True) # <--- draw graph
+        mg.block(mg.show, locals()) # <--- draw graph
 
     def contains(self, value):
         index = hash(value) % len(self.buckets)
@@ -480,10 +463,10 @@ for i in range(n):
 
 
 ## Configuration ##
-Different aspects of memory_graph can be configured. The default configuration is reset by importing 'mg.config_default'.
+Different aspects of memory_graph can be configured. The default configuration is reset by importing 'memory_graph.config_default'.
 
-- ***mg.config.max_number_nodes*** : int
-  - The maxium number of Nodes shown in the graph. When the graph gets too big set this to a smaller number. A `★` symbol indictes where the graph is cut short.
+- ***mg.config.max_tree_depth*** : int
+  - The maxium depth of the graph. A `★` symbol indictes where the graph is cut short.
 
 - ***mg.config.max_string_length*** : int
   - The maximum length of strings shown in the graph. Longer strings will be truncated.
@@ -528,7 +511,7 @@ mg.show( locals(),
 Different extensions are available for types from other Python packages. 
 
 ### Numpy ###
-Numpy types `arrray` and `matrix` and `ndarray` can be graphed with the "memory_graph.extension_numpy" extension:
+Numpy types `arrray` and `matrix` and `ndarray` can be graphed with "memory_graph.extension_numpy":
 
 ```python
 import memory_graph as mg
@@ -539,12 +522,12 @@ np.random.seed(0) # use same random numbers each run
 array = np.array([1.1, 2, 3, 4, 5])
 matrix = np.matrix([[i*20+j for j in range(20)] for i in range(20)])
 ndarray = np.random.rand(20,20)
-mg.show(locals(), block=True)
+mg.show(locals())
 ```
 ![extension_numpy.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/extension_numpy.png)
 
 ### Pandas ###
-Pandas types `Series` and `DataFrame` can be graphed with the "memory_graph.extension_pandas" extension:
+Pandas types `Series` and `DataFrame` can be graphed with "memory_graph.extension_pandas":
 
 ```python
 import memory_graph as mg
@@ -558,7 +541,7 @@ dataframe2 = pd.DataFrame({  'Name'   : [ 'Tom', 'Anna', 'Steve', 'Lisa'],
                              'Age'    : [    28,     34,      29,     42],
                              'Length' : [  1.70,   1.66,    1.82,   1.73] },
                             index=['one', 'two', 'three', 'four']) # with row names
-mg.show(locals(), block=True)
+mg.show(locals())
 ```
 ![extension_pandas.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/extension_pandas.png)
 
@@ -572,6 +555,6 @@ See for example [jupyter_example.ipynb](https://raw.githubusercontent.com/bterwi
 
 ## Troubleshooting ##
 
-- Adobe Acrobat Reader [doesn't refresh a PDF file](https://superuser.com/questions/337011/windows-pdf-viewer-that-auto-refreshes-pdf-when-compiling-with-pdflatex) when it changes on disk and blocks updates which results in an `Could not open 'somefile.pdf' for writing : Permission denied` error. One solution is to install a PDF reader that does refresh ([Evince](https://www.fosshub.com/Evince.html) for example) and set it as the default PDF reader. Another solution is to `render()` the graph to a different output format and open it manually.
+- Adobe Acrobat Reader [doesn't refresh a PDF file](https://superuser.com/questions/337011/windows-pdf-viewer-that-auto-refreshes-pdf-when-compiling-with-pdflatex) when it changes on disk and blocks updates which results in an `Could not open 'somefile.pdf' for writing : Permission denied` error. One solution is to install a PDF reader that does refresh ([Evince](https://www.fosshub.com/Evince.html), [Okular](https://okular.kde.org/), [SumatraPDF](https://www.sumatrapdfreader.org/), ...) and set it as the default PDF reader. Another solution is to `render()` the graph to a different output format and to open it manually.
 
 - When graph edges overlap it can be hard to distinguish them. Using an interactive graphviz viewer, such as [xdot](https://github.com/jrfonseca/xdot.py), on a '*.gv' DOT output file will help.

{memory_graph-0.3.6 → memory_graph-0.3.7}/memory_graph/__init__.py

@@ -9,24 +9,41 @@ import sys
 
 import graphviz
 
-__version__ = "0.3.06"
+__version__ = "0.3.07"
 __author__ = 'Bas Terwijn'
 
-log_file=sys.stdout
-press_enter_text="press <ENTER> to continue..."
-
 def get_source_location(stack_index):
     """ Helper function to get the source location of the stack with 'stack_index' of the call stack. """
     frameInfo = inspect.stack()[stack_index] # get frameInfo of calling frame
     filename= frameInfo.filename
     line_nr= frameInfo.lineno
     function = frameInfo.function
-    return f'in {filename}:{line_nr} function:"{function}"'
+    return f'blocked at {filename}:{line_nr} function:"{function}"'
 
-def get_locals_from_calling_frame(stack_index):
-    """ Helper function to get locals of the stack with 'stack_inex' of the call stack. """
-    frameInfo = inspect.stack()[stack_index] # get frameInfo of calling frame
-    return frameInfo.frame.f_locals
+def block(fun=None, *args, **kwargs):
+    """
+    Calls the given function `fun` with specified arguments and keyword arguments,
+    waits for the user to press Enter, and returns the result of `fun`.
+    """
+    loc=True
+    stack_index=2
+    if 'loc' in kwargs:
+        loc = kwargs['loc']
+        del kwargs['loc']
+    if 'stack_index' in kwargs:
+        stack_index = kwargs['stack_index']
+        del kwargs['stack_index']
+    result = None
+    if callable(fun):
+        result = fun(*args, **kwargs)
+    if loc:
+        print(get_source_location(stack_index),end=', ')
+    input("Press <Enter> to continue...")
+    return result
+
+def block_deprecated_message():
+    print("Warning: 'block=True' deprecated, use mg.block(fun) instead.")
+    input(f"{get_source_location(3)}, Press <Enter> to continue...")
 
 def create_graph(data,
                  colors = None,
@@ -37,88 +54,49 @@ def create_graph(data,
     graphviz_graph = memory_to_nodes.memory_to_nodes(data)
     return graphviz_graph
 
-def show(data=None ,block=False, stack_index=2,
+def show(data ,block=False,
                  colors = None,
                  vertical_orientations = None,
                  slicers = None):
     """ Shows the graph of 'data' and optionally blocks. """
-    if data is None:
-        data=get_locals_from_calling_frame(stack_index)
     graph = create_graph(data, colors, vertical_orientations, slicers)
     graph.view()
     if block:
-        input(f"showing '{graph.filename}', {get_source_location(2)}, {press_enter_text}")
+        block_deprecated_message()
 
-def render(data=None, outfile=None, block=False, stack_index=2,
+def render(data, outfile=None, block=False,
                  colors = None,
                  vertical_orientations = None,
                  slicers = None):
     """ Renders the graph of 'data' to 'output_filename' and optionally blocks. """
-    if data is None:
-        data=get_locals_from_calling_frame(stack_index)
     graph = create_graph(data, colors, vertical_orientations, slicers)
     filename = outfile if outfile else graph.filename+".pdf"
     graph.render(outfile=filename)
     if block:
-        input(f"rendering '{filename}', {get_source_location(2)}, {press_enter_text}")
+        block_deprecated_message()
 
-def to_str(data):
-    try:
-        return str(data)
-    except Exception as e:
-        return f"problem printing: {type(data)}"
-
-def d(data=None,graph=True,log=False,block=True,stack_index=2,
-                 colors = None,
-                 vertical_orientations = None,
-                 slicers = None):
+def l(loc=True, stack_index=2, colors = None, vertical_orientations = None, slicers = None):
     """ 
-    Shows the graph of and optionally prints 'data', and optionally blocks.
-    When no 'data' is given, the locals of the calling frame are used as 'data'.
+    Shows the graph of 'data' or the locals of the calling frame, and blocks. 
     """
-    if data is None:
-        data=get_locals_from_calling_frame(stack_index)
-    if graph:
-        grph=create_graph(data, colors, vertical_orientations, slicers)
-        grph.view()
-    if log:
-        if isinstance(data,dict):
-            for key,value in utils.filter_dict_attributes(data.items()):
-                print(f"{to_str(key)}: {to_str(value)}", file=log_file, flush=True)
-        else:
-            print(to_str(data), file=log_file, flush=True)
-        if not block and not log_file == sys.stdout:
-            print(f"debugging, {get_source_location(stack_index)}",file=log_file)
-    if block:
-        input(f"debugging, {get_source_location(stack_index)}, {press_enter_text}")
-
-def ds(data=None,graph=True,log=False,block=True,stack_index=2,
-                 colors = None,
-                 vertical_orientations = None,
-                 slicers = None):
+    data = get_locals_from_calling_frame(stack_index=stack_index)
+    memory_graph.block(memory_graph.show, data, loc=loc, stack_index=stack_index+1, block=False, 
+                       colors=colors, vertical_orientations=vertical_orientations, slicers=slicers)
+    
+def s(loc=True, stack_index=2, colors = None, vertical_orientations = None, slicers = None):
     """ 
     Shows the graph of and optionally prints the call stack, and optionally blocks.
     """
-    if data is None:
-        data=get_call_stack(stack_index=stack_index)
-    if graph:
-        grph=create_graph(data, colors, vertical_orientations, slicers)
-        grph.view()
-    if log:
-        if isinstance(data,dict):
-            for frame, vars in data.items():
-                print("===== stack frame",frame)
-                if isinstance(vars,dict):
-                    for key,value in utils.filter_dict_attributes(vars.items()):
-                        print(f"{to_str(key)}: {to_str(value)}", file=log_file, flush=True)
-                else:
-                    print(to_str(frame), file=log_file, flush=True)
-        else:
-            print(to_str(data), file=log_file, flush=True)
-        if not block and not log_file == sys.stdout:
-            print(f"debugging, {get_source_location(stack_index)}",file=log_file)
-    if block:
-        input(f"debugging, {get_source_location(stack_index)}, {press_enter_text}")
+    data = get_call_stack(stack_index=stack_index)
+    memory_graph.block(memory_graph.show, data, loc=loc, stack_index=stack_index+1, block=False, 
+                       colors=colors, vertical_orientations=vertical_orientations, slicers=slicers)
+
+# ------------ locals
+
+def get_locals_from_calling_frame(stack_index=1):
+    """ Helper function to get locals of the stack with 'stack_inex' of the call stack. """
+    frameInfo = inspect.stack()[stack_index] # get frameInfo of calling frame
+    return frameInfo.frame.f_locals
 
 # ------------ call stack
 

{memory_graph-0.3.6 → memory_graph-0.3.7/memory_graph.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: memory_graph
-Version: 0.3.6
+Version: 0.3.7
 Summary: Draws a graph of your data to analyze its structure.
 Home-page: https://github.com/bterwijn/memory_graph
 Author: Bas Terwijn
@@ -80,11 +80,11 @@ class MyClass:
         self.y = y
 
 data = [ range(1, 2), (3, 4), {5, 6}, {7:'seven', 8:'eight'},  MyClass(9, 10) ]
-mg.show(data, block=True)
+mg.show(data)
 ```
 ![many_types.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/many_types.png)
 
-By using `block=True` the program blocks until the <Enter> key is pressed so you can view the graph before continuing program execution (and possibly viewing later graphs). Instead of showing the graph you can also render it to an output file of your choosing (see [Graphviz Output Formats](https://graphviz.org/docs/outputs/)) using for example:
+Instead of showing the graph you can also render it to an output file of your choosing (see [Graphviz Output Formats](https://graphviz.org/docs/outputs/)) using for example:
 
 ```python
 mg.render(data, "my_graph.pdf")
@@ -190,7 +190,7 @@ mg.show(locals())
 
 
 ### Custom Copy Method ###
-We can write our own custom copy function or method in case the three "copy" options don't do what we want. For example the copy() method of My_Class in the code below copies the `digits` but shares the `letters` between the two objects.
+We can write our own custom copy function or method in case the three "copy" options don't do what we want. For example, in the code below the copy() method of My_Class copies the `digits` but shares the `letters` between two objects.
 
 ```python
 import memory_graph as mg
@@ -216,7 +216,7 @@ mg.show(locals())
 
 
 ## Call Stack ##
-The function `mg.get_call_stack()` returns the complete call stack, including all local variables for each function in the stack. This allows us to simultaneously visualize the local variables of all the called functions. By doing so, we can identify whether any local variables from different functions in the call stack share data with one another. Here for example we call function ```add_one()``` with arguments ```a, b, c``` that adds 1 to each of its arguments.
+The `mg.get_call_stack()` function retrieves the entire call stack, including the local variables for each function on the stack. This enables us to visualize the local variables across all active functions simultaneously. Then by examining the graph, we can determine whether any local variables from different functions on the call stack share data. For instance, consider the function `add_one()` which adds the value `1` to each of its parameters, `a`, `b`, and `c`.
 
 ```python
 import memory_graph as mg
@@ -243,9 +243,17 @@ a:[4, 3, 2, 1] b:(4, 3, 2) c:[4, 3, 2]
 
 This is because `b` is of immutable type 'tuple' so its value gets copied automatically when it is changed. And because the function is called with a copy of `c`, its original value is not changed by the function. The value of variable `a` is the only value of mutable type that is shared between the root stack frame **'0: \<module>'** and the **'1: add_one'** stack frame of the function so only that variable is affected as a result of the function call. The other changes remain confined to the local variables of the ```add_one()``` function.
 
+### Block ###
+It is often helpful to temporarily block program execution to inspect the graph. For this, you can use the `mg.block()` function:
+
+```python
+mg.block(fun, arg1, arg2, ..., loc=True) 
+```
+
+This function first executes `fun(arg1, arg2, ...)`, then prints the current source location in the program, and blocks execution until the &lt;Enter&gt; key is pressed. To skip printing the source location, set `loc=False`.
 
 ### Recursion ###
-The call stack can be used to visualize how recursion works. Here we show each step of how recursively ```factorial(3)``` is computed:
+The call stack is also helpful to visualize how recursion works. Here we use `mg.block()` to show each step of how recursively ```factorial(3)``` is computed:
 
 ```python
 import memory_graph as mg
@@ -253,28 +261,26 @@ import memory_graph as mg
 def factorial(n):
     if n==0:
         return 1
-    mg.show( mg.get_call_stack(), block=True )
+    mg.block(mg.show, mg.get_call_stack())
     result = n * factorial(n-1)
-    mg.show( mg.get_call_stack(), block=True )
+    mg.block(mg.show, mg.get_call_stack())
     return result
 
 print(factorial(3))
 ```
 
-Execution results in:
-
 ![factorial.gif](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/factorial.gif)
 
 and the result is: 1 x 2 x 3 = 6
 
 ### Power Set ###
-A more insteresting recursive example that shows sharing of data is power_set(). A power set is the set of all subsets of a collection of values.
+A more interesting recursive example that shows sharing of data is power_set(). A power set is the set of all subsets of a collection of values.
 
 ```python
 import memory_graph as mg
 
 def get_subsets(subsets, data, i, subset):
-    mg.show(mg.get_call_stack(), block=True)
+    mg.block(mg.show, mg.get_call_stack())
     if i == len(data):
         subsets.append(subset.copy())
         return
@@ -282,7 +288,7 @@ def get_subsets(subsets, data, i, subset):
     get_subsets(subsets, data, i+1, subset) #    do include data[i]
     subset.pop()
     get_subsets(subsets, data, i+1, subset) # don't include data[i]
-    mg.show(mg.get_call_stack(), block=True)
+    mg.block(mg.show, mg.get_call_stack())
 
 def power_set(data):
     subsets = []
@@ -292,8 +298,6 @@ def power_set(data):
 print( power_set(['a', 'b', 'c']) )
 ```
 
-Execution results in:
-
 ![power_set.gif](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/power_set.gif)
 ```
 [['a', 'b', 'c'], ['a', 'b'], ['a', 'c'], ['a'], ['b', 'c'], ['b'], ['c'], []]
@@ -329,49 +333,28 @@ mg.get_call_stack_after_up_to(after_function, up_to_function="<module>")
 
 ### Debugging without Debugger Tool ###
 
-To make debugging without a debugger tool easier we provide these alias functions that you can add to your code where you want to view a graph:
-
-| alias | function|
-|:---|:---|
-| `d()` | `mg.show(locals(), block=True)` |
-| `ds()` | `mg.show(mg.get_call_stack(), block=True)` |
+To simplify debugging without a debugger tool, we offer these blocking alias functions that you can insert into your code at a specific point to visualize a graph:
 
-These functions have the following default arguments:
-```python
-def d(data=None, graph=True, log=False, block=True):
-```
-- data: defaults to locals() and mg.get_call_stack() respectively
-- graph: if True the data is visualized as a graph
-- log: if True the data is printed
-- block: if True the function blocks until the &lt;Enter&gt; key is pressed
-
-To print to a log file instead of standard output use:
-```python
-mg.log_file = open("my_log_file.txt", "w")
-```
+| alias | purpose | function call |
+|:---|:---|:---|
+| `mg.l()` | graph **l**ocal variables | `mg.block(mg.show, locals())` |
+| `mg.s()` | graph the call **s**tack | `mg.block(mg.show, mg.get_call_stack())` |
 
 For example, executing this program:
 
 ```python
-import memory_graph as mg
-from memory_graph import d, ds
+from memory_graph as mg
 
 squares = []
 squares_collector = []
 for i in range(1, 6):
     squares.append(i**2)
     squares_collector.append(squares.copy())
-    d(log=True)
+    mg.l() # graph local variables
 ```
-and pressing &lt;Enter&gt; a number of times, produces:
+and pressing &lt;Enter&gt; a number of times, results in:
 
 ![debugging.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/debugging.gif)
-```
-squares: [1, 4, 9, 16, 25]
-squares_collector: [[1], [1, 4], [1, 4, 9], [1, 4, 9, 16], [1, 4, 9, 16, 25]]
-i: 5
-```
-
 
 ## Datastructure Examples ##
 Module memory_graph can be very useful in a course about datastructures, some examples:
@@ -404,7 +387,7 @@ class LinkedList:
             new_node.next = self.head
             self.head.prev = new_node
             self.head = new_node
-        mg.show(locals(), block=True) # <--- draw graph
+        mg.block(mg.show, locals()) # <--- draw graph
 
 linked_list = LinkedList()
 n = 100
@@ -443,7 +426,7 @@ class BinTree:
                 node.larger = Node(new_value)
             else:
                 self.add_recursive(new_value, node.larger)
-        mg.show(locals(), block=True) # <--- draw graph
+        mg.block(mg.show, locals()) # <--- draw graph
 
     def add(self, value):
         if self.root is None:
@@ -476,7 +459,7 @@ class HashSet:
             self.buckets[index] = []
         bucket = self.buckets[index]
         bucket.append(value)
-        mg.show(locals(), block=True) # <--- draw graph
+        mg.block(mg.show, locals()) # <--- draw graph
 
     def contains(self, value):
         index = hash(value) % len(self.buckets)
@@ -499,10 +482,10 @@ for i in range(n):
 
 
 ## Configuration ##
-Different aspects of memory_graph can be configured. The default configuration is reset by importing 'mg.config_default'.
+Different aspects of memory_graph can be configured. The default configuration is reset by importing 'memory_graph.config_default'.
 
-- ***mg.config.max_number_nodes*** : int
-  - The maxium number of Nodes shown in the graph. When the graph gets too big set this to a smaller number. A `★` symbol indictes where the graph is cut short.
+- ***mg.config.max_tree_depth*** : int
+  - The maxium depth of the graph. A `★` symbol indictes where the graph is cut short.
 
 - ***mg.config.max_string_length*** : int
   - The maximum length of strings shown in the graph. Longer strings will be truncated.
@@ -547,7 +530,7 @@ mg.show( locals(),
 Different extensions are available for types from other Python packages. 
 
 ### Numpy ###
-Numpy types `arrray` and `matrix` and `ndarray` can be graphed with the "memory_graph.extension_numpy" extension:
+Numpy types `arrray` and `matrix` and `ndarray` can be graphed with "memory_graph.extension_numpy":
 
 ```python
 import memory_graph as mg
@@ -558,12 +541,12 @@ np.random.seed(0) # use same random numbers each run
 array = np.array([1.1, 2, 3, 4, 5])
 matrix = np.matrix([[i*20+j for j in range(20)] for i in range(20)])
 ndarray = np.random.rand(20,20)
-mg.show(locals(), block=True)
+mg.show(locals())
 ```
 ![extension_numpy.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/extension_numpy.png)
 
 ### Pandas ###
-Pandas types `Series` and `DataFrame` can be graphed with the "memory_graph.extension_pandas" extension:
+Pandas types `Series` and `DataFrame` can be graphed with "memory_graph.extension_pandas":
 
 ```python
 import memory_graph as mg
@@ -577,7 +560,7 @@ dataframe2 = pd.DataFrame({  'Name'   : [ 'Tom', 'Anna', 'Steve', 'Lisa'],
                              'Age'    : [    28,     34,      29,     42],
                              'Length' : [  1.70,   1.66,    1.82,   1.73] },
                             index=['one', 'two', 'three', 'four']) # with row names
-mg.show(locals(), block=True)
+mg.show(locals())
 ```
 ![extension_pandas.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/extension_pandas.png)
 
@@ -591,6 +574,6 @@ See for example [jupyter_example.ipynb](https://raw.githubusercontent.com/bterwi
 
 ## Troubleshooting ##
 
-- Adobe Acrobat Reader [doesn't refresh a PDF file](https://superuser.com/questions/337011/windows-pdf-viewer-that-auto-refreshes-pdf-when-compiling-with-pdflatex) when it changes on disk and blocks updates which results in an `Could not open 'somefile.pdf' for writing : Permission denied` error. One solution is to install a PDF reader that does refresh ([Evince](https://www.fosshub.com/Evince.html) for example) and set it as the default PDF reader. Another solution is to `render()` the graph to a different output format and open it manually.
+- Adobe Acrobat Reader [doesn't refresh a PDF file](https://superuser.com/questions/337011/windows-pdf-viewer-that-auto-refreshes-pdf-when-compiling-with-pdflatex) when it changes on disk and blocks updates which results in an `Could not open 'somefile.pdf' for writing : Permission denied` error. One solution is to install a PDF reader that does refresh ([Evince](https://www.fosshub.com/Evince.html), [Okular](https://okular.kde.org/), [SumatraPDF](https://www.sumatrapdfreader.org/), ...) and set it as the default PDF reader. Another solution is to `render()` the graph to a different output format and to open it manually.
 
 - When graph edges overlap it can be hard to distinguish them. Using an interactive graphviz viewer, such as [xdot](https://github.com/jrfonseca/xdot.py), on a '*.gv' DOT output file will help.

{memory_graph-0.3.6 → memory_graph-0.3.7}/setup.py

@@ -7,7 +7,7 @@ long_description_from_readme = (this_directory / "README.md").read_text()
 
 setup(
     name = 'memory_graph',
-    version = '0.3.06',
+    version = '0.3.07',
     description = 'Draws a graph of your data to analyze its structure.',
     long_description = long_description_from_readme,
     long_description_content_type = 'text/markdown',