invocation-tree 0.0.35__tar.gz → 0.0.37__tar.gz

{invocation_tree-0.0.35 → invocation_tree-0.0.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: invocation_tree
-Version: 0.0.35
+Version: 0.0.37
 Summary: Generates an invocation tree of functions calls.
 Author-email: Bas Terwijn <bterwijn@gmail.com>
 License-Expression: BSD-2-Clause
@@ -32,12 +32,14 @@ Run a live demo in the 👉 [**Invocation Tree Web Debugger**](https://invocatio
 - shows the invocation tree (call tree) of a program **in real time**
 - helps to **understand recursion** and its depth-first nature
 
-The new `@ivt.show` [decorator interface](#decorator) now allows to scale to application in **production code**.
+The new `@ivt.show` [decorator interface](#decorator) now allows for **scaling** to larger code bases.
 
 # Topics #
 
 [Iteration and Recursion](#iteration-and-recursion)
 
+[Divide and Conquer](#divide-and-conquer)
+
 [Permutations](#permutations)
 
 [Recursion Benefits](#recursion-benefits)
@@ -48,6 +50,8 @@ The new `@ivt.show` [decorator interface](#decorator) now allows to scale to app
 
 [Quick Sort](#quick-sort)
 
+[Mutability](#mutability)
+
 [Jugs Puzzle](#jugs-puzzle)
 
 [Configuration](#Configuration)
@@ -149,17 +153,27 @@ Each node in the invocation tree represents a function call, and the node's colo
 
 For every function call, the package displays its **local variables** and **return value**. Changes to the values of these variables over time are highlighted using bold text and gray shading to make them easier to track.
 
+We can also visualize the execution of this program in the [Memory Graph Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/factorial.py&timestep=1.0&play):
+
+[![factorial_mgwd](https://raw.githubusercontent.com/bterwijn/invocation_tree/main/images/factorial_mgwd.svg)](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/factorial.py&timestep=1.0&play)
+
+where the **call stack** is explicit. Each function call adds a stack frame to the call stack with a reference to its local variables and when a function returns it's stack frame is removed from the call stack. But when later a function calls itself multiple times the [invocation_tree](https://github.com/bterwijn/invocation_tree?tab=readme-ov-file#installation) will give us a better visualization than [memory_graph](https://github.com/bterwijn/memory_graph?tab=readme-ov-file#installation), so we will use that here mostly.
+
+# Divide and Conquer #
+
 With recursion we often use a divide and conquer strategy, splitting the problem in subproblems that are easier to solve. With factorial we split `factorial(4)` in a `4` and `factorial(3)` subproblem.
 
-**exercise1:** Use recursions to compute the sum of all the values in a list (hint: split for example the list `[1, 2, 3, ...]` in head `1` and tail `[2, 3, ...]`).
+### exercise1
+Use recursions to compute the sum of all the values in a list (hint: split for example the list `[1, 2, 3, ...]` in head `1` and tail `[2, 3, ...]`).
 ```python
-def sum(values):
+def sum_list(values):
     # <your recursive implementation>
 
-print(sum([3, 7, 4, 9, 2]))  # 25
+print(sum_list([3, 7, 4, 9, 2]))  # 25
 ```
 
-**exercise2:** Rewrite this iterative implementation of decimal to binary conversion to a recursive implementation.
+### exercise2
+Rewrite this iterative implementation of decimal to binary conversion to a recursive implementation.
 
 ```python
 def binary(decimal):
@@ -189,7 +203,7 @@ We can use recursion to compute all permutation of a number of elements with rep
 
 ![perms_LR3](https://raw.githubusercontent.com/bterwijn/invocation_tree/main/images/perms_LR3.png)
 
-This can be implemented recursively, using a divide and conquer strategy, like:
+This can be implemented recursively, using a divide and conquer strategy, with a function calling itself multiple times, like:
 
 ```python
 import invocation_tree as ivt
@@ -217,7 +231,7 @@ RRR
 ![permutations](https://raw.githubusercontent.com/bterwijn/invocation_tree/main/images/permutations.gif)
 Or see it in the [Invocation Tree Web Debugger](https://invocation-tree.com/#timestep=1.0&play)
 
-The visualization shows the depth-first nature of recursion. In each step the first elements is chosen first, and quickly the bottom of the tree is reached. Then the permutation is printed, the function returns, one step back is made, and the next element is chosen. When each element had it's turn the function returns and another step back is made. This pattern repeats until all permutations are printed.
+The visualization shows the depth-first nature of recursion. In each step the first element is chosen first, and quickly the bottom of the tree is reached. Then the permutation is printed, the function returns, one step back is made, and the next element is chosen. When each element had it's turn the function returns and another step back is made. This pattern repeats until all permutations are printed.
 
 We can also iterate over all permutations with replacement using the `product()` function of `iterools` to get the same result:
 
@@ -266,7 +280,19 @@ Or see it in the [Invocation Tree Web Debugger](https://www.invocation-tree.com/
 
 With recursion we can stop neighbors from being equal early, in contrast to iteration, where we would have had to filter out a permutation with equal neighbors after it was fully generated, which could be much slower and would require a more complex program.
 
-**exercise3:** Print all permutations with replacements of elements 'A', 'B', and 'C' of length 5 that are palindrome ('ABABA' is palindrome because if you read it backwards it's the same).
+### exercise3
+Write function `palindromes(elems, perm, n)` that print all permutations with replacements of elements in `elems` of length `n` that are palindrome ('ABABA' is palindrome because if you read it backwards it's the same). The function call `palindromes('ABC', '', 3)` should result in these lines in any order:
+```
+AAA
+ABA
+ACA
+BAB
+BBB
+BCB
+CAC
+CBC
+CCC
+```
 
 # Path Planning #
 
@@ -332,7 +358,8 @@ See it in the [Invocation Tree Web Debugger](https://www.invocation-tree.com/#co
 
 Add temporary debug prints wherever behavior isn’t clear. Experiment with what and how you print to maximize clarity.
 
-**exercise4:** In this larger bidirectional graph, print all the paths of length 7 that connect node `a` to node `b` where going over the same node multiple times is allowed (`avjxbxb` is one such path, there are 114 such paths in total).
+### exercise4
+In this larger bidirectional graph, print all the paths of length 7 that connect node `a` to node `b` where going over the same node multiple times is allowed (`avjxbxb` is one such path, there are 114 such paths in total).
 
 ```python
 edges =  [('a', 's'), ('i', 'z'), ('c', 'p'), ('d', 'p'), ('d', 'u'), ('b', 'e'), ('b', 'g'),
@@ -393,7 +420,8 @@ print(results)
 <!-- ![permutations_collect](https://raw.githubusercontent.com/bterwijn/invocation_tree/main/images/permutations_collect.gif) -->
 See it in the [Invocation Tree Web Debugger](https://www.invocation-tree.com/#codeurl=https://raw.githubusercontent.com/bterwijn/invocation_tree/refs/heads/main/src/permutations_collect.py&timestep=0.5&play)
 
-**exercise5:** Create a list with all paths of length 10 in the larger bidirectional graph that go from `a` to `b`, and that do go via `d` but do **not** go via `x` (`amajdjaskb` is one such path, there are 145 such paths in total).
+### exercise5
+Create a list with all paths of length 10 in the larger bidirectional graph that go from `a` to `b`, and that do go via `d` but do **not** go via `x` (`amajdjaskb` is one such path, there are 145 such paths in total).
 
 Where is the best place in the code to test for `x` to make the program run fast?
 
@@ -407,9 +435,75 @@ edges =  [('a', 's'), ('i', 'z'), ('c', 'p'), ('d', 'p'), ('d', 'u'), ('b', 'e')
 ```
 ![graph_big_d_x.png)](https://raw.githubusercontent.com/bterwijn/invocation_tree/main/images/graph_big_d_x.png)
 
+
+# Mutability #
+
+In the permutation problem we could choose to use mutable type `list` to represent a permutation instead of the immutable type `str` we used before. This can be done in two ways. One way is to use the `+` list concatenation operator to add elements to the permutation, but this is slow because this creates a whole new list each time:
+
+```python
+def permutations(elements, perm, n):
+    if n == 0:
+        print(perm)
+    else:
+        for element in elements:
+            permutations(elements, perm + [element], n-1)  # creates new list, SLOW!
+
+permutations('LR', [], 3)
+```
+
+The [Memory Graph Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/invocation_tree/refs/heads/main/src/perm_mutable_copy.py&timestep=1&play) shows that each recursive function call has it's own list copy.
+
+The [Invocation Tree Web Debugger](https://invocation-tree.com/#codeurl=https://raw.githubusercontent.com/bterwijn/invocation_tree/refs/heads/main/src/perm_mutable_copy.py&timestep=1&play) shows that all permutation are generated in the same way as when we used immutable type `str` to represent each permutation.
+
+A second way is to mutate the `list` value with the `+=` operator or `append()` function and then after the recursive call to undo this action to restore its original value. This way we avoid creating new lists so this is much faster. We now use the same list in each recursive function call. We couldn't do this before with immutable type `str` because a value of immutable type is always automatically copied when we change it. However, now we have to take care to correctly undo each action we take so the code can get it a bit more complex, but this generally is worth it for faster execution. This style of recursion is often called **backtracking with in-place mutation**.
+
+```python
+def permutations(elements, perm, n):
+    if n == 0:
+        print(perm)
+    else:
+        for element in elements:
+            perm.append(element)  # do action that mutates, FAST!
+            permutations(elements, perm, n-1)
+            perm.pop()            # undo action
+            
+permutations('LR', [], 3)
+```
+
+The [Memory Graph Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/invocation_tree/refs/heads/main/src/perm_mutable_undo.py&timestep=1&play) now shows that all function calls use the same list.
+
+The [Invocation Tree Web Debugger](https://invocation-tree.com/#codeurl=https://raw.githubusercontent.com/bterwijn/invocation_tree/refs/heads/main/src/perm_mutable_undo.py&timestep=1&play) shows that all permutation are generated but with each action being undone so that in the end the list is empty again.
+
+### exercise6
+Rewrite your code of **exercise5** so that it uses a list to represent each path and uses backtracking with in-place mutation so that a single list is used in each recursive function call for faster execution. For example the path `'amajdjaskb'` should now be represented as `['a', 'm', 'a', 'j', 'd', 'j', 'a', 's', 'k', 'b']`.
+
+# Lazy Evaluation #
+
+We can combine recursion and lazy evaluation using the `yield` and `yield from` keywords. We use `yield` to produce a value, and we use `yield from` when calling each function that (indirectly) produces a value using `yield`. Here we see an example with the `permutations()` function:
+
+```python
+def permutations(elements, perm, n):
+    if n == 0:
+        yield perm
+    else:
+        for element in elements:
+            yield from permutations(elements, perm + element, n-1)
+
+generator_function = permutations('LR', '', 3)
+for perm in generator_function:
+    print(perm)
+```
+
+The first call to the `permutations()` function now results in a generator_function where we can iterate over to get all permutations that are yielded.
+
+The [Invocation Tree Web Debugger](https://invocation-tree.com/#codeurl=https://raw.githubusercontent.com/bterwijn/invocation_tree/refs/heads/main/src/perm_lazy.py&timestep=1&play) gives an idea about how lazy evaluation is implemented. When we read a value from the generator_function the `permutations()` functions get called recursively until a permutation is yielded and then all `permutations()` calls return. When we read the next value the previous state of the recursion is restored and execution continues until the next permutation is yielded. This patterns repeats until all the recursive calls are completed and the generator is used up. Unfortunately this process makes the tree difficult to read, something we might improve in the future. At least it now gives an idea about the overhead of the lazy evaluation of recursive functions, the price we pay for not having to use memory for the `results` list.
+
+### exercise7
+Rewrite your code of **exercise6** so that `get_all_paths()` recursion is evaluated lazily.
+
 # Quick Sort #
 
-Another nice example of divide-and-conquer is the recursive quicksort algorithm. It works by choosing a pivot element and dividing the list into elements smaller than the pivot and elements larger than the pivot. Each of these sublists is then quicksorted in the same way. When we get to the point a sublist has zero or one element, it is already sorted. When returning, these sorted sublists are then combined with the pivot to produce a larger sorted lists. Here we use the return value to get the sorted result.
+Another nice example of divide-and-conquer is the recursive quicksort algorithm. It works by choosing a pivot element and splitting the list into elements smaller than the pivot, equal to the pivot, and larger than the pivot. The smaller and larger sublists are then quicksorted recursively. When we get to the point a sublist has zero or one element, then it is sorted. When returning, these sorted sublists are then combined with the elements equal to the pivot to produce a larger sorted lists.
 
 ```python
 import invocation_tree as ivt
@@ -417,7 +511,7 @@ import invocation_tree as ivt
 def quick_sort(values):
     if len(values) <= 1:
         return values
-    pivot = values[0]  # choose arbitrarity the first as pivot
+    pivot = values[0]  # choose arbitrarily the first as pivot
     smaller = [x for x in values if x  < pivot]
     equal   = [x for x in values if x == pivot]
     larger  = [x for x in values if x  > pivot]
@@ -433,10 +527,16 @@ print('  sorted values:',values)
 unsorted values: [7, 4, 10, 11, 2, 6, 9, 1, 5, 3, 8, 12]
   sorted values: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
 ```
-<!-- ![quick_sort](https://raw.githubusercontent.com/bterwijn/invocation_tree/main/images/quick_sort.gif) -->
+
 See it in the [Invocation Tree Web Debugger](https://www.invocation-tree.com/#codeurl=https://raw.githubusercontent.com/bterwijn/invocation_tree/refs/heads/main/src/quick_sort.py&timestep=0.5&play)
 
-**exercise6:** Rewrite this quick sort program so that we can pass in a list to collect the sorted result and we don't need to use a return value. This would make the program faster as it avoids having to use the `+` list concatenation operator that creates a new list each time we use it, whereas `+=` or `append()` only add to an existing list.
+### exercise8
+Add a `key` argument so that we can use the `quick_sort(values, key=None)` function to sort each value `x` in `values` as if it was value `key(x)`, in exactly the same way as how the `sorted(iterable, key=None)` function works. For example:
+
+- The call `quick_sort([1, 3, 4, 2], key = lambda x : -x)` should return `[4, 3, 2, 1]` because then each value is sorted by its negative value [-4, -3, -2, -1]. 
+- The call `quick_sort(['aaa', 'bb', 'c'], key = lambda x : len(x))` should return `['c', 'bb', 'aaa']` because then each value is sorted by its length [1, 2, 3].
+
+Sort the values as normal when `key` is `None`.
 
 # Jugs Puzzle #
 
@@ -494,14 +594,15 @@ Where:
 
 The breadth-first algorithm works and gives us the shortest path to a goal state, but to do that it uses a lot of memory to store each generation and all jugs states it has seen. Now we also want an algorithm that uses much less memory.
 
-**exercise7:** Write a recursive solver for the Jugs Puzzle that uses less memory by searching for the solution in a depth-first manner.
+### exercise9
+Write a recursive solver for the Jugs Puzzle that uses less memory by searching for the solution in a depth-first manner.
 
 - A solution may not have the same jugs state multiple times (this also avoids infinite loops).
 - It is not necessary to find the shortest path to a goal state (like breadth-first does).
 
-If you want to use the Invocation Tree Web Debugger, you can look at these [configuration examples](https://invocation-tree.com/#codeurl=https://raw.githubusercontent.com/bterwijn/invocation_tree/refs/heads/main/src/config.py) to keep the tree small and readable.
+Use the [decorator interface](#decorator) to visualize the execution on your system (not the Invocation Tree Web Debugger) because that allows you to easily choose which functions show up in the tree.
 
-**solution exercise7:** First try it yourself, we give the [solution](https://www.invocation-tree.com/#codeurl=https://raw.githubusercontent.com/bterwijn/invocation_tree/refs/heads/main/src/jugs_depth_first.py&breakpoints=136&continues=1) here for comparison.
+**solution exercise8:** First try it yourself, we give the [solution](https://www.invocation-tree.com/#codeurl=https://raw.githubusercontent.com/bterwijn/invocation_tree/refs/heads/main/src/jugs_depth_first.py&breakpoints=136&continues=1) here for comparison.
 
 A harder more fun instance of this puzzle is with jugs with capacity 3, 5, 34 and 107 liter and the goal of getting to a jug with 51 liters.
 
@@ -514,7 +615,7 @@ The Invocation Tree Web Debugger gives examples of the [most important configura
 
 
 ## Hidding ##
-It can be useful to hide certian variables or functions to avoid unnecessary complexity. This can be done with:
+It can be useful to hide certian variables to avoid unnecessary complexity. This can be done with:
 
 ```python
 tree = ivt.blocking()
@@ -544,28 +645,29 @@ tree = ivt.blocking()
 tree.ignore_calls.add(r're:namespace\..*')
 ```
 
-ignores all function of `namespace`.
+ignores all functions starting with `namespace.`.
 
 ## Decorator ##
 
-A better way to hide functions is to use the `@ivt.show` decorator on only the functions you want to graph. The decorator uses the global `ivt.decorator_tree` tree.
+A better way to hide functions is to use the `@ivt.show` decorator on only the functions you want to graph but this can only be used when running the code locally and not in the Invocation Tree Web Debugger. The decorator uses the global `ivt.decorator_tree` tree.
 
 ```python
 import invocation_tree as ivt
 ivt.decorator_tree = ivt.blocking()               # set tree used by decorator
-#ivt.decorator_tree = ivt.blocking_each_change()  # block at each change, but much slower
+#ivt.decorator_tree = ivt.blocking_each_change()  # block at each change, much slower
+#ivt.decorator_tree = ivt.debugger()              # for VS Code or PyCharm debugger
 
-@ivt.show  # use decorator to select which functions to graph
+@ivt.show  # use this decorator to select which functions to graph
 def permutations(elements, perm, n):
     if n == 0:
         print(perm)
     else:
         for element in elements:
-            perm.append(element)
+            perm.append(element)  # do action that mutates
             permutations(elements, perm, n-1)
-            perm.pop()
+            perm.pop()            # undo action
             
-permutations( 'LR', [], 3)  # all permutations of L and R of length 3
+permutations('LR', [], 3)  # all permutations of L and R of length 3
 ```
 
 ## Blocking ##
@@ -612,12 +714,6 @@ tree = ivt.Invocation_Tree()
   - if `>=0` the out filename is numbered for animated gif making
 - **tree.indent** : string
   - the string used for identing the local variables
-- **tree.color_active** : string
-  - HTML color for active function
-- **tree.color_paused*** : string
-  - HTML color for paused functions
-- **tree.color_returned***: string
-  - HTML color for returned functions
 - **tree.to_string** : dict[str, fun]
   - mapping from type/name/id to a to_string() function for custom printing of values
 - **tree.hide_vars** : set()
@@ -631,6 +727,32 @@ tree = ivt.Invocation_Tree()
 - **tree.fontsize** : str
   - the font size used in the graph, default '14'
 
+## Functions ##
+
+- **tree.dark_mode(b: bool = None)**
+  - set dark mode to 'True' or 'False', or 'None' to toggle.
+- **tree.transparent_background(b: bool = None)**
+  - set transparent background to 'True' or 'False', or 'None' to toggle.
+
+## Colors ##
+
+For light mode the colors are:
+
+- ivt.foreground_color_light
+- ivt.background_color_light
+- ivt.color_paused_light
+- ivt.color_active_light
+- ivt.color_returned_light
+
+For dark mode the colors are:
+
+- ivt.foreground_color_dark
+- ivt.background_color_dark
+- ivt.color_paused_dark
+- ivt.color_active_dark 
+- ivt.color_returned_dark 
+
+
 # Troubleshooting #
 - Adobe Acrobat Reader [doesn't refresh a PDF file](https://community.adobe.com/t5/acrobat-reader-discussions/reload-refresh-pdfs/td-p/9632292) when it changes on disk and blocks updates which results in an `Could not open 'tree.pdf' for writing : Permission denied` error. One solution is to install a PDF reader that does refresh ([SumatraPDF](https://www.sumatrapdfreader.org/), [Okular](https://okular.kde.org/),  ...) and set it as the default PDF reader. Another solution is to `render()` the graph to a different output format.