Skip to main content

Package Layout

This page explains how shypermaid is split into files and why. It won’t tell you how to do something; the How-To guides cover that.

Three layers

The package has three layers, and each one only calls the layer below it. The diagram below shows the files in each layer and the calls between them:

%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'monospace', "fontSize":"18px", "darkMode":false}}}%%

flowchart TD
    subgraph App["<strong>app.py</strong>"]
        run(["<code>run_app()</code>"])
        create("<code>create_app()</code>")
        appui("<code>app_ui()</code>")
        srv("<code>server()</code>")
    end
    subgraph Modules["<strong>modules.py</strong>"]
        editor("<code>editor_ui()</code><br><code>editor_server()</code>")
        viewer("<code>viewer_ui()</code><br><code>viewer_server()</code>")
    end
    subgraph Diagram["<strong>diagram.py</strong>"]
        dir[["<code>set_direction()</code>"]]
        cfg[["<code>render_config()</code>"]]
        consts[("<code>THEMES</code>, <code>LOOKS</code>,<br><code>DIRECTIONS</code>, <code>DEFAULT_CODE</code>")]
    end
    www[("<code>www/</code><br>binding, styles, libraries")]

    run --> create --> appui & srv
    create -.-> www
    appui --> editor & viewer
    srv --> editor & viewer
    viewer --> dir & cfg
    editor & viewer --> consts

    style App fill:#FFFFFF,color:#1B2A41,stroke:#1B2A41,stroke-width:1px,rx:10,ry:10
    style Modules fill:#FFFFFF,color:#1B2A41,stroke:#1B2A41,stroke-width:1px,rx:10,ry:10
    style Diagram fill:#FFFFFF,color:#1B2A41,stroke:#1B2A41,stroke-width:1px,rx:10,ry:10
    style run fill:#2A6F77,color:#FFFFFF
    style create fill:#2A6F77,color:#FFFFFF,rx:5,ry:5
    style appui fill:#2A6F77,color:#FFFFFF,rx:5,ry:5
    style srv fill:#2A6F77,color:#FFFFFF,rx:5,ry:5
    style editor fill:#2A6F77,color:#FFFFFF,rx:5,ry:5
    style viewer fill:#2A6F77,color:#FFFFFF,rx:5,ry:5

app.py assembles the page and launches the server. modules.py holds the two Shiny modules. diagram.py holds plain Python functions and the menu choices.

The call tree from the source

The diagram above is drawn by hand, so it can drift from the code. callgrove reads the source files and builds the same tree without running the app. The cell below runs on every docs build, so the tree always matches the package:

from pathlib import Path

import shypermaid
from callgrove import call_tree_dir

pkg = Path(shypermaid.__file__).parent
call_tree_dir(pkg, root="create_app")
█─create_app
├─█─app_ui
│ ├─editor_ui
│ └─█─viewer_ui
│   └─_tool
└─█─server
  ├─editor_server
  └─█─viewer_server
    ├─code_theme
    ├─█─set_direction
    │ ├─_declaration
    │ └─_set_statement
    └─render_config

The tree starts at create_app(), not run_app(). run_app() passes the app to Shiny as the string "shypermaid.app:app", so there is no call for callgrove to follow, and its tree is a single node.

Each layer shows up one level below the last. create_app() calls app_ui() and server(), those call the modules, and only viewer_server() reaches into diagram.py. _tool() is a private helper that builds the buttons in the viewer’s tool rail.

modules_only=True keeps only the functions decorated with @module.ui or @module.server. The wrappers in between are removed, and the modules move up to take their place:

call_tree_dir(pkg, root="create_app", modules_only=True)
█─create_app
├─editor_ui
├─viewer_ui
├─editor_server
└─viewer_server

Why the helpers are Shiny free

diagram.py never imports shiny. Its two functions take strings and return a string or a dictionary, so the tests call them directly without starting a session. That’s why diagram.py has full test coverage while the module servers do not.

The same split keeps the menu choices in one place. THEMES, LOOKS, and DIRECTIONS fill the viewer’s menus and also validate the arguments to render_config() and set_direction(). A new theme only needs a new dictionary entry.

Why the drawing happens in the browser

Mermaid is a JavaScript library, so the diagram is drawn in the browser, not in Python. The files in www/ handle that side. mermaid-binding.js receives the code from the server, draws it, and runs the pan, zoom, fullscreen, and download tools. styles.css lays out the editor and canvas. vendor/ holds pinned copies of Mermaid and svg-pan-zoom, so the app never reaches out to a CDN.

create_app() serves www/ at /shypermaid through the static_assets argument. The folder ships inside the package, so the paths work after a regular install as well as an editable one.

A name to watch: shypermaid.app

__init__.py re-exports the App object named app from app.py:

from .app import app, create_app, run_app

The re-exported name matches the submodule name, so after import shypermaid the attribute shypermaid.app is the App object, not the module. shiny run shypermaid.app:app still works because it imports the module by its full name. Plain attribute access does not, so code that needs app_ui() or WWW should use from shypermaid.app import app_ui, WWW.

Recap

The package keeps the app, the modules, and the helpers in separate files, and each layer calls only the one below it. The helpers stay free of Shiny so they’re easy to test, and the drawing lives in www/ because Mermaid runs in the browser. The Render Cycle page follows one edit through all three layers.