lectrace 1.0.0__tar.gz

lectrace-1.0.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+env/
+_site/
+.lectrace_cache.json
+frontend/node_modules/
+frontend/dist/
+frontend/**/*.js
+!frontend/eslint.config.js
+frontend/tsconfig.tsbuildinfo
+.DS_Store
+*.swp

lectrace-1.0.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: lectrace
+Version: 1.0.0
+Summary: Write Python lecture code. Get an interactive viewer on GitHub Pages.
+Author-email: "PraiseGod D. Adesanmi" <dayopraisegod@gmail.com>
+License: MIT
+Requires-Python: >=3.11
+Provides-Extra: arxiv
+Requires-Dist: beautifulsoup4; extra == 'arxiv'
+Description-Content-Type: text/markdown
+
+# lectrace
+
+Write Python lecture code. Get an interactive step-through viewer on GitHub Pages — automatically.
+
+lectrace traces your Python code line by line using `sys.settrace`, captures variable state and rendered content at each step, and produces a static React app that lets anyone step through the execution with arrow keys. No Node.js, no configuration, no build step for the user — just Python.
+
+> Inspired by [edtrace](https://github.com/percyliang/edtrace) by Percy Liang.
+
+---
+
+## Install
+
+```sh
+uv add lectrace
+# or
+pip install lectrace
+```
+
+Requires Python 3.11+. Zero mandatory dependencies — lectrace uses the standard library only. numpy, torch, and sympy are detected and rendered automatically if they are already installed in your environment.
+
+---
+
+## A lecture file
+
+A lecture is any `.py` file that imports from `lectrace` and defines a `main()` function:
+
+```python
+# 01_binary_search.py
+from lectrace import text, link
+
+def binary_search(arr, target):
+    lo, hi = 0, len(arr) - 1
+    while lo <= hi:              # @inspect lo hi
+        mid = (lo + hi) // 2    # @inspect mid
+        if arr[mid] == target:
+            return mid
+        elif arr[mid] < target:
+            lo = mid + 1
+        else:
+            hi = mid - 1
+    return -1
+
+def main():
+    text("# Binary Search")
+    text("Finds a target in a sorted array in $O(\\log n)$ time.")
+
+    arr = [2, 5, 8, 12, 16, 23, 38, 42]  # @inspect arr
+    result = binary_search(arr, 23)       # @inspect result
+
+    text(f"Found 23 at index `{result}`")
+    link(binary_search)   # click to jump to the function definition
+```
+
+---
+
+## Directives
+
+Directives are inline comments that control tracing and display:
+
+| Directive | Effect |
+|-----------|--------|
+| `# @inspect x y` | Show `x` and `y` in the variable panel after this line runs |
+| `# @clear x` | Remove `x` from the variable panel |
+| `# @stepover` | Execute this line as a single step — don't trace into any calls it makes |
+| `# @hide` | Run this line silently — never shown in the viewer |
+
+---
+
+## Rendering functions
+
+Call these anywhere inside `main()` or any function it calls:
+
+| Function | What it renders |
+|----------|----------------|
+| `text("# Heading")` | Markdown with LaTeX math (`$...$` inline, `$$...$$` display) |
+| `text("...", verbatim=True)` | Monospace, whitespace preserved |
+| `image("fig.png", width=400)` | Local file or remote URL (cached) |
+| `video("demo.mp4")` | Embedded video with controls |
+| `link(MyClass)` | Clickable jump to that class or function in the viewer |
+| `link(title="Paper", url="...", authors=["Smith"], date="2024")` | Reference card with hover metadata |
+| `plot({...})` | Interactive Vega-Lite chart |
+| `note("speaker annotation")` | Presenter note, hidden until `N` is pressed |
+| `system_text(["python3", "--version"])` | Shell command output as verbatim text |
+
+---
+
+## Custom type rendering
+
+Implement `__lectrace__` on any class to control how it appears in the variable panel:
+
+```python
+class Node:
+    def __init__(self, val, left=None, right=None):
+        self.val = val
+        self.left = left
+        self.right = right
+
+    def __lectrace__(self):
+        return {
+            "val": self.val,
+            "left": self.left.val if self.left else None,
+            "right": self.right.val if self.right else None,
+        }
+```
+
+Without `__lectrace__`, nested objects show their full repr. With it, you control exactly what students see.
+
+---
+
+## File naming
+
+| Pattern | Behaviour |
+|---------|-----------|
+| `01_intro.py` | Lecture — appears in sidebar, traced and deployed |
+| `02_sorting.py` | Lecture — sidebar order follows alphabetical sort |
+| `_utils.py` | Helper — imported normally, never traced or shown |
+
+Number prefixes control sidebar order. Helper files starting with `_` are ignored by lectrace entirely.
+
+```
+my-course/
+  _data.py            ← shared data, ignored by lectrace
+  01_intro.py         ← first in sidebar
+  02_complexity.py    ← second
+  03_sorting.py       ← third
+```
+
+---
+
+## CLI
+
+```sh
+lectrace serve                  # build + serve all lectures at http://localhost:7000
+lectrace serve 01_intro.py      # serve a single file
+lectrace build --output _site   # build static site for deployment
+lectrace init                   # generate GitHub Actions workflow + lectrace.toml
+lectrace run 01_intro.py        # execute and print trace stats (no server)
+```
+
+---
+
+## Deploy to GitHub Pages
+
+```sh
+lectrace init   # generates .github/workflows/lectrace.yml
+git add .
+git commit -m "add lectures"
+git push
+```
+
+Enable GitHub Pages in your repo settings (Source: **GitHub Actions**). Every push to `main` rebuilds and redeploys automatically.
+
+---
+
+## How it works
+
+- **Tracer** — `sys.settrace` intercepts every line of execution. At each step it captures the call stack, inspected variable values (serialized to JSON), and any pending renderings.
+- **Serializer** — converts Python values to JSON. Primitives are direct. Collections recurse. numpy/torch/sympy are imported lazily only when encountered.
+- **Builder** — discovers lecture files, runs each through the tracer, writes `traces/*.json` plus a `traces/index.json` manifest. Incremental: files are skipped if their SHA-256 hash hasn't changed.
+- **Viewer** — a pre-built React + TypeScript SPA bundled into `lectrace/_static/` and shipped inside the pip package. Uses HashRouter so it works at any URL depth with zero configuration. Math via KaTeX, charts via Vega-Lite, syntax highlighting via highlight.js.
+
+---
+
+## Documentation
+
+Full documentation: **https://praisegee.github.io/lectrace/**
+
+- [Getting Started](https://praisegee.github.io/lectrace/getting-started/)
+- [Directives](https://praisegee.github.io/lectrace/directives/)
+- [Rendering API](https://praisegee.github.io/lectrace/rendering-api/)
+- [Custom Types](https://praisegee.github.io/lectrace/custom-types/)
+- [Deploying](https://praisegee.github.io/lectrace/deploying/)
+- [API Reference](https://praisegee.github.io/lectrace/api-reference/)
+

lectrace-1.0.0/README.md

@@ -0,0 +1,174 @@
+# lectrace
+
+Write Python lecture code. Get an interactive step-through viewer on GitHub Pages — automatically.
+
+lectrace traces your Python code line by line using `sys.settrace`, captures variable state and rendered content at each step, and produces a static React app that lets anyone step through the execution with arrow keys. No Node.js, no configuration, no build step for the user — just Python.
+
+> Inspired by [edtrace](https://github.com/percyliang/edtrace) by Percy Liang.
+
+---
+
+## Install
+
+```sh
+uv add lectrace
+# or
+pip install lectrace
+```
+
+Requires Python 3.11+. Zero mandatory dependencies — lectrace uses the standard library only. numpy, torch, and sympy are detected and rendered automatically if they are already installed in your environment.
+
+---
+
+## A lecture file
+
+A lecture is any `.py` file that imports from `lectrace` and defines a `main()` function:
+
+```python
+# 01_binary_search.py
+from lectrace import text, link
+
+def binary_search(arr, target):
+    lo, hi = 0, len(arr) - 1
+    while lo <= hi:              # @inspect lo hi
+        mid = (lo + hi) // 2    # @inspect mid
+        if arr[mid] == target:
+            return mid
+        elif arr[mid] < target:
+            lo = mid + 1
+        else:
+            hi = mid - 1
+    return -1
+
+def main():
+    text("# Binary Search")
+    text("Finds a target in a sorted array in $O(\\log n)$ time.")
+
+    arr = [2, 5, 8, 12, 16, 23, 38, 42]  # @inspect arr
+    result = binary_search(arr, 23)       # @inspect result
+
+    text(f"Found 23 at index `{result}`")
+    link(binary_search)   # click to jump to the function definition
+```
+
+---
+
+## Directives
+
+Directives are inline comments that control tracing and display:
+
+| Directive | Effect |
+|-----------|--------|
+| `# @inspect x y` | Show `x` and `y` in the variable panel after this line runs |
+| `# @clear x` | Remove `x` from the variable panel |
+| `# @stepover` | Execute this line as a single step — don't trace into any calls it makes |
+| `# @hide` | Run this line silently — never shown in the viewer |
+
+---
+
+## Rendering functions
+
+Call these anywhere inside `main()` or any function it calls:
+
+| Function | What it renders |
+|----------|----------------|
+| `text("# Heading")` | Markdown with LaTeX math (`$...$` inline, `$$...$$` display) |
+| `text("...", verbatim=True)` | Monospace, whitespace preserved |
+| `image("fig.png", width=400)` | Local file or remote URL (cached) |
+| `video("demo.mp4")` | Embedded video with controls |
+| `link(MyClass)` | Clickable jump to that class or function in the viewer |
+| `link(title="Paper", url="...", authors=["Smith"], date="2024")` | Reference card with hover metadata |
+| `plot({...})` | Interactive Vega-Lite chart |
+| `note("speaker annotation")` | Presenter note, hidden until `N` is pressed |
+| `system_text(["python3", "--version"])` | Shell command output as verbatim text |
+
+---
+
+## Custom type rendering
+
+Implement `__lectrace__` on any class to control how it appears in the variable panel:
+
+```python
+class Node:
+    def __init__(self, val, left=None, right=None):
+        self.val = val
+        self.left = left
+        self.right = right
+
+    def __lectrace__(self):
+        return {
+            "val": self.val,
+            "left": self.left.val if self.left else None,
+            "right": self.right.val if self.right else None,
+        }
+```
+
+Without `__lectrace__`, nested objects show their full repr. With it, you control exactly what students see.
+
+---
+
+## File naming
+
+| Pattern | Behaviour |
+|---------|-----------|
+| `01_intro.py` | Lecture — appears in sidebar, traced and deployed |
+| `02_sorting.py` | Lecture — sidebar order follows alphabetical sort |
+| `_utils.py` | Helper — imported normally, never traced or shown |
+
+Number prefixes control sidebar order. Helper files starting with `_` are ignored by lectrace entirely.
+
+```
+my-course/
+  _data.py            ← shared data, ignored by lectrace
+  01_intro.py         ← first in sidebar
+  02_complexity.py    ← second
+  03_sorting.py       ← third
+```
+
+---
+
+## CLI
+
+```sh
+lectrace serve                  # build + serve all lectures at http://localhost:7000
+lectrace serve 01_intro.py      # serve a single file
+lectrace build --output _site   # build static site for deployment
+lectrace init                   # generate GitHub Actions workflow + lectrace.toml
+lectrace run 01_intro.py        # execute and print trace stats (no server)
+```
+
+---
+
+## Deploy to GitHub Pages
+
+```sh
+lectrace init   # generates .github/workflows/lectrace.yml
+git add .
+git commit -m "add lectures"
+git push
+```
+
+Enable GitHub Pages in your repo settings (Source: **GitHub Actions**). Every push to `main` rebuilds and redeploys automatically.
+
+---
+
+## How it works
+
+- **Tracer** — `sys.settrace` intercepts every line of execution. At each step it captures the call stack, inspected variable values (serialized to JSON), and any pending renderings.
+- **Serializer** — converts Python values to JSON. Primitives are direct. Collections recurse. numpy/torch/sympy are imported lazily only when encountered.
+- **Builder** — discovers lecture files, runs each through the tracer, writes `traces/*.json` plus a `traces/index.json` manifest. Incremental: files are skipped if their SHA-256 hash hasn't changed.
+- **Viewer** — a pre-built React + TypeScript SPA bundled into `lectrace/_static/` and shipped inside the pip package. Uses HashRouter so it works at any URL depth with zero configuration. Math via KaTeX, charts via Vega-Lite, syntax highlighting via highlight.js.
+
+---
+
+## Documentation
+
+Full documentation: **https://praisegee.github.io/lectrace/**
+
+- [Getting Started](https://praisegee.github.io/lectrace/getting-started/)
+- [Directives](https://praisegee.github.io/lectrace/directives/)
+- [Rendering API](https://praisegee.github.io/lectrace/rendering-api/)
+- [Custom Types](https://praisegee.github.io/lectrace/custom-types/)
+- [Deploying](https://praisegee.github.io/lectrace/deploying/)
+- [API Reference](https://praisegee.github.io/lectrace/api-reference/)
+

lectrace-1.0.0/frontend/App.tsx

@@ -0,0 +1,13 @@
+import { HashRouter, Routes, Route } from "react-router-dom";
+import { TraceApp } from "./components/TraceApp";
+import "./index.css";
+
+export default function App() {
+  return (
+    <HashRouter>
+      <Routes>
+        <Route path="/" element={<TraceApp />} />
+      </Routes>
+    </HashRouter>
+  );
+}

lectrace-1.0.0/frontend/components/TraceApp.tsx

@@ -0,0 +1,46 @@
+import { useSearchParams } from "react-router-dom";
+import { TraceBrowser } from "./TraceBrowser";
+import { TraceViewer } from "./TraceViewer";
+
+export function TraceApp() {
+  const [params, setParams] = useSearchParams();
+  const tracePath = params.get("trace");
+
+  return (
+    <div className="app-layout">
+      <TraceBrowser />
+      <main className="app-main">
+        {tracePath ? (
+          <TraceViewer />
+        ) : (
+          <TracePrompt onSelect={(id) => setParams({ trace: id })} />
+        )}
+      </main>
+    </div>
+  );
+}
+
+function TracePrompt({ onSelect }: { onSelect: (id: string) => void }) {
+  return (
+    <div className="trace-prompt">
+      <h2>Open a Lecture</h2>
+      <p>Select a lecture from the sidebar, or type a trace name below.</p>
+      <form
+        onSubmit={(e) => {
+          e.preventDefault();
+          const val = (e.currentTarget.elements.namedItem("trace") as HTMLInputElement).value.trim();
+          if (val) onSelect(val);
+        }}
+      >
+        <input
+          name="trace"
+          type="text"
+          placeholder="e.g. lecture_01 or traces/lecture_01.json"
+          autoFocus
+          className="trace-input"
+        />
+        <button type="submit">Open</button>
+      </form>
+    </div>
+  );
+}

lectrace-1.0.0/frontend/components/TraceBrowser.tsx

@@ -0,0 +1,39 @@
+import { useEffect, useState } from "react";
+import { useSearchParams } from "react-router-dom";
+import type { TraceIndex } from "../types/trace";
+
+export function TraceBrowser() {
+  const [index, setIndex] = useState<TraceIndex | null>(null);
+  const [params, setParams] = useSearchParams();
+  const active = params.get("trace");
+
+  useEffect(() => {
+    fetch("./traces/index.json")
+      .then((r) => r.json())
+      .then(setIndex)
+      .catch(() => null);
+  }, []);
+
+  if (!index || index.traces.length === 0) return null;
+
+  const select = (id: string) =>
+    setParams((p) => { p.set("trace", id); p.delete("step"); return p; });
+
+  return (
+    <nav className="trace-browser">
+      <div className="trace-browser-title">Lectures</div>
+      <ul>
+        {index.traces.map((entry) => (
+          <li
+            key={entry.id}
+            className={entry.id === active ? "active" : ""}
+            onClick={() => select(entry.id)}
+          >
+            <span className="entry-title">{entry.title}</span>
+            <span className="entry-steps">{entry.step_count} steps</span>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  );
+}

lectrace-1.0.0/frontend/components/TraceViewer/EnvPanel.tsx

@@ -0,0 +1,64 @@
+import type { Trace, Value } from "../../types/trace";
+import { ValueRenderer } from "../renderers/ValueRenderer";
+import { useDrag } from "../../hooks/useDrag";
+import { inSameFunction, isAncestorOf } from "../../hooks/useNavigation";
+
+interface Props {
+  trace: Trace;
+  stepIndex: number;
+}
+
+export function EnvPanel({ trace, stepIndex }: Props) {
+  const { position, onMouseDown, isDragging } = useDrag({ x: 20, y: 80 });
+  const env = buildEnv(trace, stepIndex);
+
+  if (Object.keys(env).length === 0) return null;
+
+  return (
+    <div
+      className="env-panel"
+      style={{
+        left: position.x,
+        top: position.y,
+        cursor: isDragging.current ? "grabbing" : "grab",
+      }}
+      onMouseDown={onMouseDown}
+    >
+      <table className="env-table">
+        <tbody>
+          {Object.entries(env).map(([name, value]) => (
+            <tr key={name}>
+              <td className="env-key">{name}</td>
+              <td className="env-eq">=</td>
+              <td><ValueRenderer value={value} /></td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+function buildEnv(trace: Trace, stepIndex: number): Record<string, Value> {
+  const current = trace.steps[stepIndex];
+  const envs: Record<string, Value | null>[] = [];
+
+  for (let i = stepIndex; i >= 0; i--) {
+    const step = trace.steps[i];
+    if (inSameFunction(step.stack, current.stack)) {
+      if (Object.keys(step.env).length > 0) envs.push(step.env as Record<string, Value | null>);
+    } else if (isAncestorOf(step.stack, current.stack)) {
+      break;
+    }
+  }
+
+  envs.reverse();
+  const merged: Record<string, Value | null> = {};
+  for (const e of envs) Object.assign(merged, e);
+
+  for (const key of Object.keys(merged)) {
+    if (merged[key] === null) delete merged[key];
+  }
+
+  return merged as Record<string, Value>;
+}

lectrace-1.0.0/frontend/components/TraceViewer/LinesPanel.tsx

@@ -0,0 +1,148 @@
+import { useMemo, useCallback } from "react";
+import hljs from "highlight.js/lib/core";
+import python from "highlight.js/lib/languages/python";
+import "highlight.js/styles/github.css";
+import type { Trace, Rendering } from "../../types/trace";
+import { computeLinesToShow } from "../../hooks/useNavigation";
+import { MarkdownView } from "../renderers/MarkdownView";
+import { ExternalLinkCard } from "../renderers/ExternalLinkCard";
+import { PlotView } from "../renderers/PlotView";
+
+hljs.registerLanguage("python", python);
+
+interface Props {
+  trace: Trace;
+  path: string;
+  lineNumber: number;
+  stepIndex: number;
+  rawMode: boolean;
+  animateMode: boolean;
+  showNotes: boolean;
+  onGotoLine: (ln: number) => void;
+  onGotoLocation: (path: string, ln: number) => void;
+}
+
+export function LinesPanel({
+  trace, path, lineNumber, stepIndex,
+  rawMode, animateMode, showNotes,
+  onGotoLine, onGotoLocation,
+}: Props) {
+  const fileContents = trace.files[path] ?? "";
+
+  const highlightedLines = useMemo(() => {
+    const highlighted = hljs.highlight(fileContents, { language: "python" }).value;
+    return highlighted.split("\n");
+  }, [fileContents]);
+
+  const linesToShow = useMemo(
+    () => computeLinesToShow(trace, stepIndex),
+    [trace, stepIndex],
+  );
+
+  const lineToRenderings = useMemo(() => {
+    const map = new Map<number, Rendering[]>();
+    for (const step of trace.steps) {
+      const frame = step.stack.at(-1);
+      if (frame) map.set(frame.line_number, step.renderings);
+    }
+    return map;
+  }, [trace.steps]);
+
+  const hidden = new Set(trace.hidden_line_numbers[path] ?? []);
+
+  const scrollRef = useCallback((el: HTMLElement | null) => {
+    if (!el) return;
+    const rect = el.getBoundingClientRect();
+    const inView = rect.top >= 50 && rect.bottom <= window.innerHeight - 50;
+    if (!inView) {
+      const dist = Math.min(Math.abs(rect.top), Math.abs(rect.bottom - window.innerHeight));
+      el.scrollIntoView({ behavior: dist < 150 ? "smooth" : "instant", block: "center" });
+    }
+  }, []);
+
+  return (
+    <div className="lines-panel">
+      {highlightedLines.map((htmlLine, idx) => {
+        const ln = idx + 1;
+        if (hidden.has(ln)) return null;
+
+        const loc = `${path}:${ln}`;
+        const isCurrent = ln === lineNumber;
+        const cloaked = animateMode && !linesToShow.has(loc);
+        const allRenderings = lineToRenderings.get(ln) ?? [];
+        const renderings = allRenderings.filter((r) => r.type !== "note");
+        const notes = allRenderings.filter((r): r is Extract<Rendering, { type: "note" }> => r.type === "note");
+
+        return (
+          <div
+            key={ln}
+            ref={isCurrent ? scrollRef : null}
+            className={["line", isCurrent ? "current-line" : "", cloaked ? "cloaked" : ""].filter(Boolean).join(" ")}
+          >
+            <span
+              className="line-number"
+              onClick={() => onGotoLine(ln)}
+              title={`Go to line ${ln}`}
+            >
+              {ln}
+            </span>
+            {!rawMode && renderings.length > 0 ? (
+              <span className="renderings">
+                <span className="indent" dangerouslySetInnerHTML={{ __html: htmlLine.match(/^(\s*)/)?.[0] ?? "" }} />
+                {renderings.map((r, i) => (
+                  <span key={i}>{renderRendering(r, onGotoLocation)}</span>
+                ))}
+              </span>
+            ) : (
+              <span
+                className="code-line"
+                dangerouslySetInnerHTML={{ __html: rawMode ? htmlLine : stripDirectives(htmlLine) }}
+              />
+            )}
+            {showNotes && notes.map((r, i) => (
+              <span key={i} className="note-text">{r.data}</span>
+            ))}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+function renderRendering(r: Rendering, onGotoLocation: (path: string, ln: number) => void): React.ReactNode {
+  switch (r.type) {
+    case "markdown":
+      return <MarkdownView content={r.data} style={r.style} />;
+    case "image":
+      return <img src={r.data} style={r.style} alt="" />;
+    case "video":
+      return <video controls style={r.style}><source src={r.data} /></video>;
+    case "link":
+      if (r.internal_link) {
+        const { path, line_number } = r.internal_link;
+        return (
+          <a href="#" style={r.style} onClick={(e) => { e.preventDefault(); onGotoLocation(path, line_number); }}>
+            {r.data ?? `${path}:${line_number}`}
+          </a>
+        );
+      }
+      if (r.external_link) {
+        return <ExternalLinkCard link={r.external_link} anchorText={r.data} style={r.style} />;
+      }
+      return null;
+    case "plot":
+      return <PlotView spec={r.data} style={r.style} />;
+    default: {
+      const fallback = r as { data?: string; style?: React.CSSProperties };
+      return <span style={fallback.style}>{fallback.data}</span>;
+    }
+  }
+}
+
+function stripDirectives(htmlLine: string): string {
+  const i = htmlLine.indexOf("#");
+  if (i === -1) return htmlLine;
+  const code = htmlLine.slice(0, i);
+  const comment = htmlLine.slice(i).replace(/@\S+/g, "").replace(/#\s*$/, "");
+  return comment.trim() === "" ? code : code + comment;
+}