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")
''')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:
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:
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:
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() 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:
%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'monospace', "fontSize":"18px", "darkMode":false}}}%%
flowchart TD
ref(["<code>_labeler.label()</code><br>in <code>modules.py</code>"])
assign("<code>_labeler = lb.Labeler()</code><br>a module level instance")
imp("<code>from . import</code><br><code>labels as lb</code>")
cls[["<code>class Labeler</code><br>in <code>labels.py</code>"]]
node[/"node <code>Labeler.label</code>"/]
ref -->|"i. look up <code>_labeler</code>"| assign
assign -->|"ii. look up <code>lb</code>"| imp
imp -->|"iii. find <code>Labeler</code>"| cls
cls -->|"iv. find the <code>label</code> 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:
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()afterimport pkg.model as mdl. - Relative module:
plots.draw()afterfrom . import plots. - Renamed function:
g()afterfrom .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:
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() 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:
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:
call_tree_dir(app_dir, root="app_ui", modules_only=True)█─app_ui
└─counter_ui
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:
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() warned about it. Pass the function’s name with ui_fun to add the UI branch:
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() 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.