invocation-tree 0.0.15__py3-none-any.whl

invocation_tree/__init__.py

@@ -0,0 +1,283 @@
+# This file is part of invocation_tree.
+# Copyright (c) 2023, Bas Terwijn.
+# SPDX-License-Identifier: BSD-2-Clause
+
+from graphviz import Digraph
+import html
+import sys
+import difflib 
+
+__version__ = "0.0.15"
+__author__ = 'Bas Terwijn'
+
+def highlight_diff(str1, str2):
+    matcher = difflib.SequenceMatcher(None, str1, str2)
+    result = []
+    is_highlighted = False
+    for tag, i1, i2, j1, j2 in matcher.get_opcodes():
+        if tag == 'replace':
+            result.append(f'<B>{str2[j1:j2]}&#8203;</B>&#8203;')
+            is_highlighted = True
+        elif tag == 'delete':
+            result.append(f'<FONT COLOR="#aaaaaa"><I>{str1[i1:i2]}&#8203;</I></FONT>&#8203;')
+            is_highlighted = True
+        elif tag == 'insert':
+            result.append(f'<B>{str2[j1:j2]}&#8203;</B>&#8203;')
+            is_highlighted = True
+        elif tag == 'equal':
+            result.append(str2[j1:j2])
+    diff = ''.join(result)
+    return diff, is_highlighted
+
+def get_class_function_name(frame):
+    class_name = ''
+    if 'self' in frame.f_locals:
+        class_name = frame.f_locals['self'].__class__.__name__ + '.'
+    function_name = class_name+frame.f_code.co_name
+    return function_name
+
+def filter_variables(var, val):
+    if callable(val):
+        return False
+    if isinstance(val, (type, type(object), type(__import__('os')))):
+        return False
+    if var.startswith('__'):
+        return False
+    return True
+
+class Tree_Node:
+
+    def __init__(self, node_id, frame, return_value):
+        self.node_id = node_id
+        self.frame = frame
+        self.return_value = return_value
+        self.is_returned = False
+        self.strings = {}
+
+    def __repr__(self):
+        return f'node_id:{self.node_id} frame:{self.frame} return_value:{self.return_value}'
+
+class Invocation_Tree:
+
+    def __init__(self, 
+                 filename='tree.pdf', 
+                 show=True, 
+                 block=True, 
+                 src_loc=True, 
+                 each_line=False, 
+                 gifcount=-1,
+                 max_string_len=150, 
+                 indent='   ', 
+                 color_paused = '#ccffcc', 
+                 color_active = '#ffffff', 
+                 color_returned = '#ffcccc', 
+                 to_string=None, 
+                 hide=None,
+                 cleanup=True,
+                 quiet=True):
+        # --- config
+        self.filename = filename
+        self.prev_filename = None
+        self.show = show
+        self.block = block
+        self.src_loc = src_loc
+        self.max_string_len = max_string_len
+        self.gifcount = gifcount
+        self.indent = indent
+        self.color_paused = color_paused
+        self.color_active = color_active
+        self.color_returned = color_returned
+        self.each_line = each_line
+        self.to_string = {}
+        if not to_string is None:
+            self.to_string = to_string
+        self.hide = set()
+        if not hide is None:
+            self.hide = hide
+        self.cleanup = cleanup
+        self.quiet = quiet
+        # --- core
+        self.stack = []
+        self.returned = []
+        self.prev_returned = []
+        self.node_id = 0
+        self.node_id_to_table = {}
+        self.edges = []
+        self.is_highlighted = False
+        self.ignore_calls = {'Invocation_Tree.__exit__', 'Invocation_Tree.stop_trace'}
+
+    def __repr__(self):
+        return f'Invocation_Tree(filename={repr(self.filename)}, show={self.show}, block={self.block}, each_line={self.each_line}, gifcount={self.gifcount})'
+
+    def __call__(self, fun, *args, **kwargs):
+        try:
+            sys.settrace(self.trace_calls)
+            result = fun(*args, **kwargs)
+        finally:
+            sys.settrace(None)
+        return result
+
+    def value_to_string(self, key, value, use_repr=False):
+        try:
+            if id(value) in self.to_string:
+                val_str = self.to_string[id(value)](value)
+            elif key in self.to_string:
+                val_str = self.to_string[key](value)
+            elif type(value) in self.to_string:
+                val_str = self.to_string[type(value)](value)
+            else:
+                val_str = repr(value) if use_repr else str(value)
+        except Exception as e:
+            val_str = '<not-string-convertable>'
+        if len(val_str) > self.max_string_len:
+            val_str = '...'+val_str[-self.max_string_len:]
+        return html.escape(val_str)
+
+    def get_hightlighted_content(self, tree_node, key, value, use_old_content=False, use_repr=False):
+        if use_old_content:
+            return tree_node.strings[key]
+        is_highlighted = False
+        content = self.value_to_string(key, value, use_repr=use_repr)
+        if key in tree_node.strings:
+            use_old_content = tree_node.strings[key]
+            hightlighted_content, is_highlighted = highlight_diff(use_old_content, content)
+        else:
+            if len(content.strip())>0: # fixes graphviz error on empty <B></B> tag
+                hightlighted_content = '<B>'+content+'</B>' 
+                is_highlighted = True
+            else:
+                hightlighted_content = content
+        tree_node.strings[key] = content
+        self.is_highlighted |= is_highlighted
+        return hightlighted_content
+    
+    def build_html_table(self, tree_node, active=False, is_returned=None, use_old_content=False):
+        if is_returned is None:
+            is_returned = tree_node.is_returned
+        else:
+            tree_node.is_returned = is_returned
+        return_value = tree_node.return_value
+        border = 1
+        color = self.color_paused
+        if active:
+            color = self.color_active
+            border = 3
+        if is_returned:
+            color = self.color_returned
+        table = f'<\n<TABLE BORDER="{str(border)}" CELLBORDER="0" CELLSPACING="0" BGCOLOR="{color}">\n  <TR>'
+        class_fun_name = get_class_function_name(tree_node.frame)
+        local_vars = tree_node.frame.f_locals
+        hightlighted_content = self.get_hightlighted_content(tree_node, class_fun_name, class_fun_name, use_old_content)
+        table += '<TD ALIGN="left">'+ '➤'+ hightlighted_content +'</TD>'
+        for var,val in local_vars.items():
+            var_name = class_fun_name+'..'+var
+            val_name = class_fun_name+'.'+var
+            if filter_variables(var,val) and not val_name in self.hide:
+                table += '</TR>\n  <TR>'
+                hightlighted_var = self.get_hightlighted_content(tree_node, var_name, var, use_old_content)
+                hightlighted_val = self.get_hightlighted_content(tree_node, val_name, val, use_old_content, use_repr=True)
+                hightlighted_content = self.indent + hightlighted_var + ': ' + hightlighted_val
+                table += '<TD ALIGN="left">'+ hightlighted_content  +'</TD>'
+        if is_returned:
+            return_name = class_fun_name+'.return'
+            if not return_name in self.hide:
+                table += '</TR>\n  <TR>'
+                hightlighted_content = self.get_hightlighted_content(tree_node, return_name, return_value, use_old_content, use_repr=True)
+                table += '<TD ALIGN="left">'+ 'return ' + hightlighted_content +'</TD>'
+        table += '</TR>\n</TABLE>>'
+        return table
+
+    def update_node(self, tree_node, active=False, returned=None, use_old_content=False):
+        table = self.build_html_table(tree_node, active, returned, use_old_content=use_old_content)
+        self.node_id_to_table[str(tree_node.node_id)] = table
+        
+    def add_edge(self, tree_node1, tree_node2):
+        self.edges.append((str(tree_node1.node_id), str(tree_node2.node_id)))
+
+    def get_output_filename(self):
+        if self.gifcount >= 0:
+            splits = self.filename.split('.')
+            if len(splits)>1:
+                splits[-2]+=str(self.gifcount)
+                self.gifcount += 1
+                return '.'.join(splits)
+        return self.filename
+        
+    def create_graph(self):
+        graphviz_graph_attr = {}
+        graphviz_node_attr = {'shape':'plaintext'}
+        graphviz_edge_attr = {}
+        graph = Digraph('invocation_tree',
+                graph_attr=graphviz_graph_attr,
+                node_attr=graphviz_node_attr,
+                edge_attr=graphviz_edge_attr)
+        for node in self.prev_returned:
+            self.update_node(node, use_old_content=True)
+        self.prev_returned = []
+        for node in self.returned:
+            self.update_node(node, returned=True)
+            self.prev_returned.append(node)
+        self.returned = []
+        for node in self.stack:
+            self.update_node(node, active=(node is self.stack[-1]))
+        for nid, table in self.node_id_to_table.items():
+            graph.node(nid, label=table)
+        for nid1, nid2 in self.edges:
+            graph.edge(nid1, nid2)
+        return graph
+        
+    def render_graph(self, graph):
+        view = (self.filename!=self.prev_filename) and self.show
+        graph.render(outfile=self.get_output_filename(), view=view, cleanup=self.cleanup, quiet=self.quiet)
+        self.prev_filename = self.filename
+
+    def output_graph(self, frame, event):
+        if self.block or self.gifcount >= 0:
+            self.is_highlighted = False
+            graph = self.create_graph()
+            if self.is_highlighted:
+                self.render_graph(graph)
+                if self.block:
+                    if self.src_loc:
+                        filename = frame.f_code.co_filename
+                        line_nr = frame.f_lineno
+                        print(f'{event.capitalize()} at {filename}:{line_nr}', end='. ')
+                    input('Press <Enter> to continue...')
+        else:
+            graph = self.create_graph()
+            self.render_graph(graph)
+
+    def trace_calls(self, frame, event, arg):
+        class_fun_name = get_class_function_name(frame)
+        if not class_fun_name in self.ignore_calls:
+            if event == 'call':
+                self.stack.append(Tree_Node(self.node_id, frame, None))
+                self.node_id += 1
+                if len(self.stack)>1:
+                    self.add_edge(self.stack[-2], self.stack[-1])
+                self.output_graph(frame, event)
+            elif event == 'return':
+                self.stack[-1].return_value = arg
+                self.returned.append(self.stack.pop())
+                self.output_graph(frame, event)
+            elif event == 'line' and self.each_line:
+                self.output_graph(frame, event)
+        return self.trace_calls
+
+def blocking(filename='tree.pdf'):
+    return Invocation_Tree(filename=filename)
+
+def blocking_each_change(filename='tree.pdf'):
+    return Invocation_Tree(filename=filename, each_line=True)
+
+def debugger(filename='tree.pdf'):
+    return Invocation_Tree(filename=filename, show=False, block=False, each_line=True)
+
+def gif(filename='tree.png'):
+    return Invocation_Tree(filename=filename, show=False, block=False, gifcount=0)
+
+def gif_each_change(filename='tree.png'):
+    return Invocation_Tree(filename=filename, show=False, block=False, gifcount=0, each_line=True)
+
+def non_blocking(filename='tree.pdf'):
+    return Invocation_Tree(filename=filename, block=False)

invocation_tree-0.0.15.dist-info/METADATA

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: invocation_tree
+Version: 0.0.15
+Summary: Generates an invocation tree of functions calls.
+Author-email: Bas Terwijn <bterwijn@gmail.com>
+License-Expression: BSD-2-Clause
+Project-URL: Homepage, https://github.com/bterwijn/invocation-tree
+Project-URL: Repository, https://github.com/bterwijn/invocation-tree.git
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: graphviz
+Dynamic: license-file
+
+# Installation #
+Install (or upgrade) `invocation_tree` using pip:
+```
+pip install --upgrade invocation_tree
+```
+Additionally [Graphviz](https://graphviz.org/download/) needs to be installed.
+
+# Invocation Tree #
+The [invocation_tree](https://pypi.org/project/invocation-tree/) package is designed to help with **program understanding and debugging** by visualizing the **tree of function invocations** that occur during program execution. Here’s a simple example of how it works, we start with `a = 1` and compute:
+
+```
+    (a - 3 + 9) * 6
+```
+
+```python
+import invocation_tree as ivt
+
+def main():
+    a = 1
+    a = expression(a)
+    return multiply(a, 6)
+    
+def expression(a):
+    a = subtract(a, 3)
+    return add(a, 9)
+    
+def subtract(a, b):
+    return a - b
+
+def add(a, b):
+    return a + b
+
+def multiply(a, b):
+    return a * b
+
+tree = ivt.blocking()
+print( tree(main) ) # show invocation tree starting at main
+```
+Running the program and pressing &lt;Enter&gt; a number of times results in:
+![compute](https://raw.githubusercontent.com/bterwijn/invocation_tree/main/images/compute.gif)
+```
+42
+```
+Each node in the tree represents a function call, and the node's color indicates its state:
+
+ - White: The function is currently being executed (it is at the top of the call stack).
+ - Green: The function is paused and will resume execution later (it is lower down on the call stack).
+ - Red: The function has completed execution and returned (it has been removed from the call stack).
+
+For every function, the package displays its **local variables** and **return value**. Changes to these values over time are highlighted using bold text and gray shading to make them easy to track.
+
+# Chapters #
+
+[Comprehensions](#Comprehensions)
+
+[Debugger](#Debugger)
+
+[Recursion](#Recursion)
+
+[Configuration](#Configuration)
+
+[Troubleshooting](#Troubleshooting)
+
+# Author #
+Bas Terwijn
+
+# Inspiration #
+Inspired by [rcviz](https://github.com/carlsborg/rcviz).
+
+# Supported by #
+<img src="https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/uva.png" alt="University of Amsterdam" width="600">
+
+___
+___
+
+# Comprehensions #
+In this more interesting example we compute which students pass a course by using list and dictionary comprehensions.
+
+```python
+import invocation_tree as ivt
+from decimal import Decimal, ROUND_HALF_UP
+
+def main():
+    students = {'Ann':[7.5, 8.0], 
+                'Bob':[4.5, 6.0], 
+                'Coy':[7.5, 6.0]}
+    averages = {student:compute_average(grades)
+                for student, grades in students.items()}
+    passing = passing_students(averages)
+    print(passing)
+
+def compute_average(grades):
+    average = sum(grades)/len(grades)
+    return half_up_round(average, 1)
+    
+def half_up_round(value, digits=0):
+    """ High-precision half-up rounding of 'value' to a specified number of 'digits'. """
+    return float(Decimal(str(value)).quantize(Decimal(f"1e-{digits}"),
+                                              rounding=ROUND_HALF_UP))
+
+def passing_students(averages):
+    return [student 
+        for student, average in averages.items() 
+        if average >= 5.5]
+
+if __name__ == '__main__':
+    tree = ivt.blocking()
+    tree(main)
+```
+![students](https://raw.githubusercontent.com/bterwijn/invocation_tree/main/images/students.gif)
+```
+['Ann', 'Coy']
+```
+
+## Blocking ##
+The program blocks execution at every function call and return statement, printing the current location in the source code. Press the &lt;Enter&gt; key to continue execution. To block at every line of the program (like in a debugger tool) and only where a change of value occured, use instead:
+
+```python
+    tree = ivt.blocking_each_change()
+```
+
+# Debugger #
+To visualize the invocation tree in a debugger tool, such as the integrated debugger in Visual Studio Code, use instead:
+
+```python
+    tree = ivt.debugger()
+```
+
+and open the 'tree.pdf' file manually.
+![Visual Studio Code debugger](https://raw.githubusercontent.com/bterwijn/invocation_tree/main/images/vscode.png)
+
+# Recursion #
+An invocation tree is particularly helpful to better understand recursion. A simple `factorial()` example:
+
+```python
+import invocation_tree as ivt
+
+def factorial(n):
+    if n <= 1:
+        return 1
+    prev_result = factorial(n - 1)
+    return n * prev_result
+
+tree = ivt.blocking()
+print( tree(factorial, 4) ) # show invocation tree of calling factorial(4)
+```
+![factorial](https://raw.githubusercontent.com/bterwijn/invocation_tree/main/images/factorial.gif)
+```
+24
+```
+
+## Permutations ##
+This `permutations()` example shows the depth-first nature of recursive execution:
+
+```python
+import invocation_tree as ivt
+
+def permutations(elements, perm, n):
+    if n==0:
+        return [perm]
+    all_perms = []
+    for element in elements:
+        all_perms.extend(permutations(elements, perm + element, n-1))
+    return all_perms
+
+tree = ivt.blocking()
+result = tree(permutations, ['L','R'], '', 2)
+print(result) # all permutations of going Left or Right of length 2
+```
+![permutations](https://raw.githubusercontent.com/bterwijn/invocation_tree/main/images/permutations.gif)
+```
+['LL', 'LR', 'RL', 'RR']
+```
+
+## Hide Variables ##
+In an educational context it can be useful to hide certian variables to avoid unnecessary complexity. This can for example be done with:
+
+```python
+tree = ivt.blocking()
+tree.hide.add('permutations.elements')
+tree.hide.add('permutations.element')
+tree.hide.add('permutations.all_perms')
+```
+
+# Configuration #
+These invocation_tree configurations are available for an `Invocation_Tree` objects:
+
+```python
+tree = ivt.Invocation_Tree()
+```
+
+- **tree.filename** : str  
+  - filename to save the tree to, defaults to 'tree.pdf'
+- **tree.show** : bool
+  - if `True` the default application is open to view 'tree.filename'
+- **tree.block** :  bool
+  - if `True` program execution is blocked after the tree is saved
+- **tree.src_loc** : bool
+  - if `True` the source location is printed when blocking
+- **tree.each_line** : bool
+  - if `True` each line of the program is stepped through
+- **tree.max_string_len** : int
+  - the maximum string length, only the end is shown of longer strings 
+- **tree.gifcount** : int
+  - 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.hide** : set()
+  - set of all variables names that are not shown in the tree
+- **tree.to_string** : dict[str, fun]
+  - mapping from type/name to a to_string() function for custom printing of values
+
+For convenience we provide these functions to set common configurations:
+
+- **ivt.blocking(filename)**, blocks on function call and return
+- **ivt.blocking_each_change(filename)**, blocks on each change of value
+- **ivt.debugger(filename)**, non-blocking for use in debugger tool (open &lt;filename&gt; manually)
+- **ivt.gif(filename)**, generates many output files on function call and return for gif creation
+- **ivt.gif_each_change(filename)**, generates many output files on each change of value for gif creation
+- **ivt.non_blocking(filename)**, non-blocking on each function call and return
+
+# 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 'somefile.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 and to open it manually.
+
+## Memory_Graph Package ##
+The [invocation_tree](https://pypi.org/project/invocation-tree/) package visualizes function calls at different moments in time. If instead you want a detailed visualization of your data at the current time, check out the [memory_graph](https://pypi.org/project/memory-graph/) package.

invocation_tree-0.0.15.dist-info/RECORD

@@ -0,0 +1,6 @@
+invocation_tree/__init__.py,sha256=mOh8VMlN_2QtFXPO3Sf0teB-3gzG5TDzIHPhKZOrR6E,11222
+invocation_tree-0.0.15.dist-info/licenses/LICENSE.txt,sha256=lhBfhX4yJut_-ahPAsH87Xhk-01Df17Std-X1Xy6rhU,1314
+invocation_tree-0.0.15.dist-info/METADATA,sha256=or2WV3il5CDUPBmXGJzs8wusp1YQUv4Bphl8gBru6pw,8971
+invocation_tree-0.0.15.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+invocation_tree-0.0.15.dist-info/top_level.txt,sha256=-UiQipEd5_8mqbNW12sUtrMfxlTqV0HV0T4WFCeeD_I,16
+invocation_tree-0.0.15.dist-info/RECORD,,

invocation_tree-0.0.15.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

invocation_tree-0.0.15.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2017, pyexample
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

invocation_tree-0.0.15.dist-info/top_level.txt

@@ -0,0 +1 @@
+invocation_tree