# Get started

`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](https://mjfrigaard.github.io/stackcallr/).

On this page I'll draw the tree of a single function with [call_stack()](../reference/call_stack.md#callgrove.call_stack), then cover the arguments that keep a tree short enough to read.


# Installation

`callgrove` isn't on PyPI. Add the development version from GitHub to a uv project:

``` {bash}
#| eval: false
#| code-fold: false
#| echo: true
uv add git+https://github.com/mjfrigaard/callgrove
```


# Drawing one function

[call_stack()](../reference/call_stack.md#callgrove.call_stack) takes a dotted name, the same path you would import. `max_depth` stops the tree a few levels down:


``` python
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


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.


# How is a call resolved?

For each call in the body, [call_stack()](../reference/call_stack.md#callgrove.call_stack) looks the name up the way the function would at call time:

1.  The function's closure.
2.  The globals of the module that defined it.
3.  Python's builtins.

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.


# How are nodes labeled?

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`.


# Following singledispatch functions

A `functools.singledispatch` function is Python's closest match to an S3 generic in R. [call_stack()](../reference/call_stack.md#callgrove.call_stack) lists each registered implementation as a child named `function[type]`, then the calls in the default body:


``` python
call_stack("shapes.area")
```


    █─area
    ├─area[float]
    ├─area[tuple]
    ├─TypeError
    └─type


# Dropping noise

`exclude` removes functions by name. A dropped function's children move up into its place, so nothing below it is lost:


``` python
call_stack("textwrap.dedent", max_depth=2, exclude=["enumerate", "zip"])
```


    █─dedent
    ├─_whitespace_only_re.sub
    ├─_leading_whitespace_re.findall
    └─█─re.sub
      ├─_compile
      └─_compile().sub


# Staying inside one package

A function that calls into a large library can produce a very long tree, because [call_stack()](../reference/call_stack.md#callgrove.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:


``` python
call_stack("callgrove.call_tree_dir", package_only=True, max_depth=2)
```


    █─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__


# Recap

[call_stack()](../reference/call_stack.md#callgrove.call_stack) reads source, never runs it, and returns a [CallTree](../reference/CallTree.md#callgrove.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](shiny-modules.md).
