rcviz
- Python module to visualize a recursion as a tree with arguments and return values at each node.
- Provides a decorator to instrument target functions (as opposed to trace or debugger based approaches)
- Uses pygraphviz to render the graph.
Updates
-
Jun-2023: Jupyter notebook integration. Invoke callgraph.render() with no params from inside a notebook and it renders the visualization as a png in your notebook. See fibonacci.ipynb in the examples folder.
-
Oct-2021: Run this in your browser! You can run rcviz-annotated python code in your browser, with this incredible pyiodide based web app by @pamelafox, and generate the same recursion visualizations that you would with the command line.
Usage
- Use the @viz decorator to instrument the recursive function.
@viz
def factorial(n):
- Call the function
factorial(8)
- Render the recursion with
callgraph.render("outfile.png")
The output file type is derived from the file name. Supported types include .dot (graphviz dot file), .png (png image), .svg (vector graphic). No params writes to out.svg
Example
Output for recursive Fibonacci function and for a Recursive Descent parse can be found in the ./examples folder and on this blog post and
from rcviz import callgraph, viz
@viz
def quicksort(items):
if len(items) <= 1:
return items
else:
pivot = items[0]
lesser = quicksort([x for x in items[1:] if x < pivot])
greater = quicksort([x for x in items[1:] if x >= pivot])
return lesser + [pivot] + greater
print quicksort( list("helloworld") )
callgraph.render("sort.png")
Output
Note:
- The edges are numbered by the order in which they were traversed by the execution.
- The edges are colored from black to grey to indicate order of traversal : black edges first, grey edges last.
Auxiliary node data
Show intermediate values of local variables in the output render by invoking decoratedfunction.track(param1=val1, param2=val2,...). In the quicksort example above you can track the pivot with:
pivot = items[0]
quicksort.track(the_pivot=pivot) # shows a new row labelled the_pivot in each node
Installation
rviz depends on pygraphviz which is a python api into graphviz. See install instructions for your platform here. Basically you need to install graphviz using your OS package manager, or download it from here and also the graphviz-dev (ubuntu) or graphviz-devel (fedora) package
Linux - Fedora
sudo dnf install graphviz graphviz-devel
You can test the graphviz install with:
$echo 'digraph { a -> b }' | dot -Tsvg > output.svg
$pip install pygraphviz --user
Linux - install troubleshooting
Note: if the install fails, pygraphviz is trying to build a library, first install
$sudo dnf install python-devel python-wheel $sudo groupinstall "Development Tools"
And now pip install pygraphviz runs cleanly, and therefore also pip install rcviz
$pip install pygraphviz --user