lectrace¶

Write Python lecture code. Get an interactive step-through viewer on GitHub Pages — automatically.

# 01_intro.py
from lectrace import text

def main():
    x = [1, 2, 3]  # @inspect x
    text("# Introduction")
    text("Step through this lecture with the arrow keys.")
    text("Math works too: $e^{i\\pi} + 1 = 0$")

lectrace serve 01_intro.py   # preview at http://localhost:7000
git push                      # → live on GitHub Pages automatically

Why lectrace?¶

Teaching code is different from writing code. Students need to step through execution, see variable state change, and understand why each line runs — not just read a static file.

lectrace gives you that without any frontend work. Write Python, add a few comments, push to GitHub. The interactive viewer is generated automatically.

Zero mandatory dependencies. Pure Python standard library. Bring your own numpy, torch, or sympy — lectrace detects and renders them automatically.

Features¶

• Step-through execution — navigate forward and backward through every line
• Variable panel — inspect named variables as they change
• Markdown + LaTeX — render text, headings, and math inline with code
• Interactive charts — embed Vega-Lite plots directly in lectures
• Directives — @inspect, @hide, @stepover, @clear as inline comments
• Custom type rendering — implement __lectrace__ on any class
• Zero configuration — auto-discovers lecture files, deploys to GitHub Pages with one command
• Animation mode — progressively reveal code as you step through it

Quick install¶

uv add lectrace

pip install lectrace

Next steps¶