# 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()](../reference/call_tree_dir.md#callgrove.call_tree_dir) reads `.py` files on disk, and [call_tree_app()](../reference/call_tree_app.md#callgrove.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()](../reference/call_tree_dir.md#callgrove.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")
```


    █─app_server
    ├─log_msg
    └─█─counter_server
      ├─log_msg
      └─█─counter_server.count
        └─counter_server._clicks


`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")
```


    █─app_server
    └─█─counter_server
      └─█─counter_server.count
        └─counter_server._clicks


When two files define a function with the same name, [call_tree_dir()](../reference/call_tree_dir.md#callgrove.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()](../reference/call_tree_dir.md#callgrove.call_tree_dir) works it out from the file's imports and assignments, the same way Python would:


*\[Rich HTML output -- view on the documentation site\]*


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")
```


    █─counter_ui
    ├─log_msg
    └─█─Labeler.label
      └─clean


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")
```


    █─counter_ui
    ├─log_msg
    └─█─_labeler.label
      └─clean


`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()](../reference/call_tree_dir.md#callgrove.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")
```


    █─run_app
    └─█─counter.app:app
      ├─█─app_ui
      │ └─█─counter_ui
      │   └─█─Labeler.label
      │     └─clean
      └─█─app_server
        └─█─counter_server
          └─█─counter_server.count
            └─counter_server._clicks


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


    █─app_ui
    └─counter_ui


# Inspecting an App object

[call_tree_app()](../reference/call_tree_app.md#callgrove.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")
```


    /tmp/ipykernel_2567/3889257383.py:7: UserWarning: The app's UI was rendered when App() was created, so its function can't be found; pass `ui_fun=` to include the UI branch
      call_tree_app(app, exclude="log_msg")


    █─app
    └─█─app_server
      └─█─counter_server
        └─█─counter_server.count
          └─counter_server._clicks


`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()](../reference/call_tree_app.md#callgrove.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")
```


    █─app
    ├─█─app_ui
    │ └─█─counter_ui
    │   └─█─Labeler.label
    │     └─clean
    └─█─app_server
      └─█─counter_server
        └─█─counter_server.count
          └─counter_server._clicks


Module functions are found even though Shiny wraps them, because [call_tree_app()](../reference/call_tree_app.md#callgrove.call_tree_app) peels the decorator off before reading the source. The UI branch matches what [call_tree_dir()](../reference/call_tree_dir.md#callgrove.call_tree_dir) drew from the files: the same definition names, `Labeler.label` included.


# Recap

[call_tree_dir()](../reference/call_tree_dir.md#callgrove.call_tree_dir) works on source you haven't installed, and it resolves imports, aliases, and methods without running anything. [call_tree_app()](../reference/call_tree_app.md#callgrove.call_tree_app) works on an app you can import. Both return a [CallTree](../reference/CallTree.md#callgrove.CallTree) labeled by definition names, and both take `modules_only`, `exclude`, `max_depth`, and `labels`.
