pytutor-tui

A terminal UI Python tutor / visualizer, inspired by Python Tutor.

Step through a Python program's execution and watch the source code, variables, and output change line by line — rendered as nested box diagrams like the website.

Features

• Source code viewer with syntax highlighting (Pygments, GitHub-dark style) and the current line highlighted with a ▶ band as you step
• Variables panel showing globals/locals as compact, bordered boxes (lists, dicts, sets, tuples, and objects drawn as nested boxes)
• Aliasing / connectivity: shared references are detected and every box gets a stable #n id; aliases show → shares #n so you can visually trace which variables point to the same object (like Python Tutor's arrows)
• The variable(s) that changed on the current step are marked with a ▶ pointer so you can see exactly what just happened
• Variables panel is scrollable on both axes; use + / - to zoom (scale) the boxes in and out to fit large structures
• A draggable divider between the code and the variables panel lets you resize the views to taste
• Output panel showing accumulated stdout up to the current step
• Exception tracebacks shown inline when a program crashes
• Step controls: ←/→ step back/forward, r restart, End jump to end, +/- zoom, q quit
• Load from a file (CLI argument) or paste code directly in the app (Ctrl+Enter)

Install

uv sync

Run

# Visualize a file
uv run python main.py examples/test.py

# Or paste code interactively (no argument)
uv run python main.py

How it works

tracer.py uses sys.settrace to record a TraceStep snapshot (line number, locals, globals, stdout) for every executed line. The TUI precomputes all steps up front, then stepping is just moving an index — no re-execution, no side effects.

Project layout

• tracer.py — Tracer / TraceStep: records execution steps
• viz.py — VarsView and ObjectBox: renders variables as box diagrams
• main.py — Textual app, screens, and step controls