---------------------------------------------------------------------- This is the API documentation for the callgrove library. ---------------------------------------------------------------------- ## Call trees Build the call tree of a function, a folder of source files, or a Shiny app. call_stack(fn: 'str | Callable[..., Any]', max_depth: 'int | None' = None, exclude: 'str | Iterable[str] | None' = None, package_only: 'bool' = False, labels: 'str' = 'def') -> 'CallTree' Build the call tree of a function from its source, without running it. ``call_stack()`` reads the function's source, finds every function it calls, and follows each of those the same way. Calls to ``functools.singledispatch`` functions are followed into every registered implementation, which play the part R's ``UseMethod()`` methods do. Resolution is static. The function is never called. A class call is followed into the class's ``__init__``, ``self.method()`` and ``cls.method()`` into the class the caller is defined in, and ``Class().method()`` into that method. Calls that can only be known at run time (``getattr()``, functions passed in as arguments, methods on a parameter) show as leaves or are skipped. Builtins and C extension functions have no Python source, so they are leaves too. Parameters ---------- fn A dotted path such as ``"json.dumps"`` or ``"pkg.module.Class.method"``, a bare builtin name such as ``"len"``, or the function itself. max_depth How many levels to expand. ``None`` (the default) follows every call down to a leaf or a function already visited. exclude Function names to drop from the tree, such as a logging helper that appears under every node. A dropped function's children move up into its place. The root is never dropped. package_only When True, only functions from the root's own top level package are expanded. Calls into other packages and the standard library stay in the tree as leaves. Default False, which follows every call. labels ``"def"`` (the default) labels a function from the root's own package by its definition name (``Model.fit``), and everything else by the text at the call site (``re.sub``). ``"call"`` uses the call site text everywhere (``model.fit``). Nested functions are always labeled ``outer.inner``. Returns ------- CallTree The root node. Print it to draw the tree. Examples -------- >>> call_stack("callgrove.CallTree.__str__") █─CallTree.__str__ ├─_label └─█─_draw ├─enumerate ├─len ├─_label └─_draw >>> call_stack("callgrove.call_tree_dir", max_depth=1, package_only=True) █─call_tree_dir ... call_tree_dir(path: 'str | Path' = 'src', root: 'str' = '', modules_only: 'bool' = False, exclude: 'str | Iterable[str] | None' = None, max_depth: 'int | None' = None, labels: 'str' = 'def') -> 'CallTree' Build the call tree of the functions defined in a folder of ``.py`` files. ``call_tree_dir()`` parses every ``.py`` file under ``path`` (subfolders included) without importing or running any of it. It collects each top level function (``def name(...)`` or ``name = lambda ...``) and each class method (as ``Class.method``), then links a function to every other collected function its body calls or names. The result is the tree reachable from ``root``. Names are resolved through each file's imports, so ``mdl.fit()`` after ``import pkg.model as mdl``, ``plots.draw()`` after ``from . import plots``, and ``g()`` after ``from .m import f as g`` all link to the function they name. A module level instance (``model = Model()``) links ``model.fit()`` to ``Model.fit``. A class call links to ``Class.__init__`` when the class defines one, ``Class().fit()`` links to ``Class.fit``, and ``self.m()`` or ``cls.m()`` inside a method links to ``m`` on the same class (base classes are not searched). Nodes are labeled with the name of the definition, not the alias used at the call site. Folders named ``great-docs`` or ``_freeze`` (docs build output) and hidden folders are skipped. Because nothing is imported, it works on a package's ``src/`` folder or a Shiny for Python app before it is installed. A launch function often names the app as a string, as in ``shiny.run_app("myapp.app:app")``. Such a ``"module:attr"`` string is followed when ``module`` is one of the scanned files. When ``attr`` is a module level assignment (``app = create_app()``), the string becomes a node whose children are the functions that assignment calls or names. When ``attr`` is a function (an app factory), it links straight to it. Parameters ---------- path Folder to scan. Default ``"src"``. root Name of the function to root the tree at: a top level function found under ``path``, or a method written as ``"Class.method"``. modules_only When True, keep only ``root`` and functions decorated with Shiny's ``@module.ui`` or ``@module.server``. Every other function is spliced out and its children move up, so modules reached through a plain wrapper stay visible. exclude Function names to drop from the tree; their children move up into their place. The root is never dropped. max_depth How many levels to expand. ``None`` (the default) expands everything. labels ``"def"`` (the default) labels each node by its definition name (``Model.fit``). ``"call"`` uses the text at the call site (``model.fit``) for the edge into each node. Nested functions are always labeled ``outer.inner``. Returns ------- CallTree The root node. Print it to draw the tree. Warns ----- UserWarning When two files define a top level function with the same name. The file parsed last (in sorted path order) wins. Examples -------- >>> import tempfile >>> from pathlib import Path >>> app_dir = Path(tempfile.mkdtemp()) >>> _ = (app_dir / "app.py").write_text(''' ... from shiny import App, module, ui ... ... @module.ui ... def counter_ui(): ... return ui.input_action_button("go", "Go") ... ... @module.server ... def counter_server(input, output, session): ... pass ... ... def app_ui(): ... return ui.page_fluid(counter_ui("a")) ... ... def app_server(input, output, session): ... counter_server("a") ... ... def launch(): ... return App(app_ui(), app_server) ... ''') >>> call_tree_dir(app_dir, root="launch") █─launch ├─█─app_ui │ └─counter_ui └─█─app_server └─counter_server >>> call_tree_dir(app_dir, root="launch", modules_only=True) █─launch ├─counter_ui └─counter_server call_tree_app(app: 'Any', app_fun: 'str' = 'app', ui_fun: 'str | None' = None, server_fun: 'str | None' = None, modules_only: 'bool' = False, exclude: 'str | Iterable[str] | None' = None, max_depth: 'int | None' = None, labels: 'str' = 'def') -> 'CallTree' Build the call tree of a Shiny for Python ``App`` object. ``call_tree_app()`` takes the server function out of a ``shiny.App`` and reads its source. Each name it references is looked up the way the server would see it. When the name is a function defined in the app's own package (the top level package of the server's module), it joins the tree and its source is read the same way. Functions from other packages, such as ``shiny.ui``, are left out. A class in the app's package counts through its ``__init__``, and ``self.m()`` and ``Class().m()`` are looked up on the class, as in `call_stack()`. The app is never run, and shiny itself is never imported, so callgrove does not depend on it. Parameters ---------- app A ``shiny.App``. app_fun Label for the root node. The app does not record the name of the function that built it, so this is display text only. Default ``"app"``. ui_fun Name of the UI function. ``App`` renders a static UI when it is created, so the function behind it is lost. Pass its name here to include the UI branch. When the UI was passed as a function (``App(app_ui, server)``), it is found without this. When neither applies, the tree has no UI branch and a warning says so. server_fun Label for the server node. Default: the server function's own name. modules_only Keep only the root and Shiny module functions; see `call_tree_dir()`. exclude Function names to drop; see `call_tree_dir()`. max_depth How many levels to expand. ``None`` (the default) expands everything. labels ``"def"`` (the default) labels each function by its definition name (``Model.fit``), so one function reached under two names is one node. ``"call"`` uses the text at the call site (``model.fit``). Nested functions are always labeled ``outer.inner``. Returns ------- CallTree The root node. Print it to draw the tree. Warns ----- UserWarning When the UI is static and ``ui_fun`` is not given. Examples -------- ```python from myapp.app import app call_tree_app(app, ui_fun="app_ui") call_tree_app(app, ui_fun="app_ui", modules_only=True) ``` ## Tree object The node every builder returns, and how it prints. CallTree(name: 'str', calls: 'list[CallTree]' = , key: 'str | None' = None) -> None One node of a call tree: a function name and the calls it makes. Every tree builder in callgrove returns a ``CallTree``. Printing it (or showing it in a REPL) draws the tree in the style of R's ``lobstr::ast()``. A node with children is prefixed with ``█─``; a leaf is plain text. Children hang off ``├─`` and ``└─`` branches, one indent per level. Parameters ---------- name The function name, as written at the call site. calls Child nodes, in the order the calls appear in the source. Examples -------- >>> CallTree("main", [CallTree("load", [CallTree("open")]), CallTree("run")]) █─main ├─█─load │ └─open └─run ---------------------------------------------------------------------- This is the User Guide documentation for the package. ---------------------------------------------------------------------- ## Get started ### 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()`, 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()` 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) ``` 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()` 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()` lists each registered implementation as a child named `function[type]`, then the calls in the default body: ```{python} #| echo: false import functools import sys import tempfile import textwrap from pathlib import Path demo = Path(tempfile.mkdtemp()) (demo / "shapes.py").write_text(textwrap.dedent(''' import functools import math @functools.singledispatch def area(shape): raise TypeError(type(shape)) @area.register def _(shape: float): return math.pi * shape ** 2 @area.register def _(shape: tuple): return shape[0] * shape[1] ''')) sys.path.insert(0, str(demo)) ``` ```{python} call_stack("shapes.area") ``` ## 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"]) ``` ## Staying inside one package 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: ```{python} call_stack("callgrove.call_tree_dir", package_only=True, max_depth=2) ``` ## Recap `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](01-shiny-modules.qmd). ## Shiny ### Shiny module trees A Shiny for Python app spreads its work across modules, reactive functions, and helpers in several files. On this page I'll draw that structure with two functions. `call_tree_dir()` reads `.py` files on disk, and `call_tree_app()` inspects a `shiny.App` object. ## A small app The code below writes a small app to a temporary folder. It has one module pair, a helper module imported under an alias, and a class with one shared instance: ```{python} import tempfile from pathlib import Path app_dir = Path(tempfile.mkdtemp()) / "counter" app_dir.mkdir() (app_dir / "__init__.py").write_text("") (app_dir / "labels.py").write_text(''' def clean(text): return text.strip() class Labeler: def label(self, text): return clean(text).title() ''') (app_dir / "modules.py").write_text(''' from shiny import module, render, ui from . import labels as lb _labeler = lb.Labeler() def log_msg(msg): return msg @module.ui def counter_ui(label="Count"): log_msg("counter_ui") return ui.input_action_button("go", _labeler.label(label)) @module.server def counter_server(input, output, session): log_msg("counter_server") def _clicks(n): return f"{n} clicks" @render.text def count(): return _clicks(input.go()) ''') _ = (app_dir / "app.py").write_text(''' import shiny from shiny import App, ui from .modules import counter_server, counter_ui, log_msg def app_ui(): return ui.page_fluid(counter_ui("a")) def app_server(input, output, session): log_msg("server") counter_server("a") app = App(app_ui(), app_server) def run_app(): shiny.run_app("counter.app:app") ''') ``` ## Reading the files `call_tree_dir()` parses every `.py` file under `path` without importing it. Each top level function is linked to the functions its body calls or names: ```{python} from callgrove import call_tree_dir call_tree_dir(app_dir, root="app_server") ``` `counter_server.count` is the `@render.text` function defined inside `counter_server`. Every decorated function nested in another one gets its own node, labeled `outer.inner`. That covers Shiny's `@reactive.effect`, `@reactive.calc`, and `@render.*` functions. A repeated name such as `_` gets `#2`, `#3`, and so on. Undecorated helpers work differently. `counter_server._clicks` sits under `count`, because that's where it is called, not where it is defined. A helper also shows up where it is passed by name, such as a callback. A helper that nothing calls is left out. `log_msg` shows up under every node. `exclude` drops it and moves its children up: ```{python} call_tree_dir(app_dir, root="app_server", exclude="log_msg") ``` When two files define a function with the same name, `call_tree_dir()` warns and keeps the one parsed last. ## Following imports and aliases `counter_ui()` calls `_labeler.label()`, and nothing in that name says where `label` is defined. `call_tree_dir()` works it out from the file's imports and assignments, the same way Python would: ```{mermaid} %%| eval: true %%| fig-align: 'center' %%| fig-caption: 'How _labeler.label() is resolved' %%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'monospace', "fontSize":"18px", "darkMode":false}}}%% flowchart TD ref(["_labeler.label()
in modules.py"]) assign("_labeler = lb.Labeler()
a module level instance") imp("from . import
labels as lb") cls[["class Labeler
in labels.py"]] node[/"node Labeler.label"/] ref -->|"i. look up _labeler"| assign assign -->|"ii. look up lb"| imp imp -->|"iii. find Labeler"| cls cls -->|"iv. find the label method"| node style ref fill:#FFFFFF,stroke:#3E2A1E style assign fill:#2A6F77,color:#FFFFFF,rx:5,ry:5 style imp fill:#2A6F77,color:#FFFFFF,rx:5,ry:5 style cls fill:#fff,stroke:#3E2A1E style node fill:#E8A33D,color:#1B2A41 ``` The tree below shows the result. Nodes use the name of the definition (`Labeler.label`), not the text at the call site: ```{python} call_tree_dir(app_dir, root="counter_ui") ``` The same lookup handles the other common forms: * Aliased module: `mdl.fit()` after `import pkg.model as mdl`. * Relative module: `plots.draw()` after `from . import plots`. * Renamed function: `g()` after `from .m import f as g`. Class methods can also be roots. `call_tree_dir(app_dir, root="Labeler.label")` starts the tree at that method. ## Choosing labels By default every builder labels a node with its definition name, so one function reached under two names is drawn once. `labels="call"` shows the text written at each call site instead: ```{python} call_tree_dir(app_dir, root="counter_ui", labels="call") ``` `exclude` and `modules_only` match definition names in both modes, so `exclude="Labeler.label"` works either way. Nested functions keep their `outer.inner` labels in both modes. ## Launch strings A launch function usually names the app as a string, which `shiny.run_app()` imports later. `call_tree_dir()` follows a `"module:attr"` string when the module is one of the scanned files. The string becomes a node. Its children are the functions that the `app = ...` assignment calls or names: ```{python} call_tree_dir(app_dir, root="run_app", exclude="log_msg") ``` Sometimes the string names a function instead, such as an app factory in `"counter.app:create_app"`. The tree then links straight to that function. A string that points outside the scanned folder is ignored. ## Modules only `modules_only=True` keeps the root and the functions decorated with `@module.ui` or `@module.server`. Every other function is spliced out, nested reactive functions included, and its children move up: ```{python} call_tree_dir(app_dir, root="app_ui", modules_only=True) ``` ## Inspecting an App object `call_tree_app()` takes the server out of a `shiny.App` and follows the names it references. Only functions defined in the app's own package join the tree, so `shiny.ui` calls are left out. The app is never run: ```{python} import sys sys.path.insert(0, str(app_dir.parent)) from counter.app import app from callgrove import call_tree_app call_tree_app(app, exclude="log_msg") ``` `App()` renders a static UI when it is created, so the function behind it is gone. That's why the tree above has no UI branch, and why `call_tree_app()` warned about it. Pass the function's name with `ui_fun` to add the UI branch: ```{python} call_tree_app(app, ui_fun="app_ui", exclude="log_msg") ``` Module functions are found even though Shiny wraps them, because `call_tree_app()` peels the decorator off before reading the source. The UI branch matches what `call_tree_dir()` drew from the files: the same definition names, `Labeler.label` included. ## Recap `call_tree_dir()` works on source you haven't installed, and it resolves imports, aliases, and methods without running anything. `call_tree_app()` works on an app you can import. Both return a `CallTree` labeled by definition names, and both take `modules_only`, `exclude`, `max_depth`, and `labels`.