from callgrove import call_stack
call_stack("textwrap.dedent", max_depth=2)█─dedent
├─_whitespace_only_re.sub
├─_leading_whitespace_re.findall
├─enumerate
├─zip
└─█─re.sub
├─_compile
└─_compile().sub
callgrove draws the call tree of a Python function without running it. It reads the function’s source, finds every function it calls, and follows each of those the same way. It is the Python counterpart to the R package stackcallr.
On this page I’ll draw the tree of a single function with call_stack(), then cover the arguments that keep a tree short enough to read.
callgrove isn’t on PyPI. Add the development version from GitHub to a uv project:
#| eval: false
#| code-fold: false
#| echo: true
uv add git+https://github.com/mjfrigaard/callgrove
call_stack() takes a dotted name, the same path you would import. max_depth stops the tree a few levels down:
█─dedent
├─_whitespace_only_re.sub
├─_leading_whitespace_re.findall
├─enumerate
├─zip
└─█─re.sub
├─_compile
└─_compile().sub
A node with children starts with █─. A leaf is plain text. Leaves are builtins (no Python source), functions already drawn higher in the tree, or calls the source alone can’t resolve.
For each call in the body, call_stack() looks the name up the way the function would at call time:
A dotted call such as re.sub() resolves re that way, then follows the attribute. Names bound inside the function (parameters, local variables, local imports) are skipped. A call on self or cls is looked up on the class the function is defined in. A class call, such as Model(), follows the class’s __init__, and Model().fit() follows Model.fit.
A decorated function defined inside the body, such as a @functools.wraps wrapper or a Shiny @reactive.effect, gets its own node named outer.inner. Its calls are listed under it rather than under the function that defines it. An undecorated helper defined inside the body is a node too, but only where it is called or passed by name.
A function from the root’s own package is labeled by its definition name, such as Model.fit. Everything else keeps the text at the call site, such as re.sub, so you can still see which library it came from. One function reached under two names is drawn once. labels="call" uses the call site text everywhere, so model.fit() shows as model.fit.
A functools.singledispatch function is Python’s closest match to an S3 generic in R. call_stack() lists each registered implementation as a child named function[type], then the calls in the default body:
exclude removes functions by name. A dropped function’s children move up into its place, so nothing below it is lost:
A function that calls into a large library can produce a very long tree, because call_stack() follows those calls too. package_only=True expands only the functions from the root’s own top level package. Everything else stays a leaf:
█─call_tree_dir
├─█─check_args
│ ├─isinstance
│ ├─TypeError
│ ├─list
│ └─all
├─isinstance
├─TypeError
├─Path
├─NotADirectoryError
├─str
├─█─_parse_dir
│ ├─_Scan.__init__
│ ├─sorted
│ ├─any
│ ├─ast.parse
│ ├─str
│ ├─_module_parts
│ ├─_top_level_assigns
│ ├─_top_level_imports
│ ├─set
│ ├─_top_level_defs
│ ├─warnings.warn
│ └─isinstance
├─ValueError
├─█─check_labels
│ ├─ValueError
│ └─str
├─█─_add_def
│ ├─nested_helpers
│ ├─referenced_names
│ ├─_resolve
│ ├─_add_def
│ └─nested_defs
├─█─launch_targets
│ ├─_body
│ ├─ast.walk
│ ├─isinstance
│ ├─_TARGET.match
│ ├─list
│ └─dict.fromkeys
├─█─_follow_target
│ ├─_find_module
│ └─_resolve_refs
├─█─build_tree
│ ├─CallTree.__init__
│ └─build_tree
├─█─is_module_def
│ ├─isinstance
│ └─dotted_name
├─█─prune_children
│ ├─prune_children
│ ├─_ids
│ └─CallTree.__init__
└─█─splice_out
├─set
├─splice_out
├─_ids
└─CallTree.__init__
call_stack() reads source, never runs it, and returns a CallTree that prints as an outline. Use max_depth or package_only to keep the tree short, and exclude to hide helpers that appear everywhere. For a Shiny for Python app, see Shiny module trees.