Skip to main content

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:

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:

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() 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:

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.