PyPI - jupyter-python-tutor - Versions diffs - 0.3.0__tar.gz → 0.3.3__tar.gz - Mend

jupyter-python-tutor 0.3.0tar.gz → 0.3.3tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

{jupyter_python_tutor-0.3.0 → jupyter_python_tutor-0.3.3}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jupyter-python-tutor
-Version: 0.3.0
+Version: 0.3.3
 Summary: Python Tutor-style step-by-step code visualization for JupyterLab 4.x and Notebook 7
 Author: dive4dec
 License-Expression: MIT

{jupyter_python_tutor-0.3.0 → jupyter_python_tutor-0.3.3}/jupyter_python_tutor/__init__.py RENAMED Viewed

@@ -11,6 +11,6 @@ from .tracer import trace_code
 from .renderer import render_trace
 from .magics import load_ipython_extension
-__version__ = "0.2.0"
+__version__ = "0.3.3"
 __all__ = ["trace_code", "render_trace", "load_ipython_extension"]

{jupyter_python_tutor-0.3.0 → jupyter_python_tutor-0.3.3}/jupyter_python_tutor/renderer.py RENAMED Viewed

@@ -1,12 +1,11 @@
-"""Render a trace as interactive HTML inside an iframe srcdoc.
+"""Render a Python trace as interactive HTML inside an iframe srcdoc.
 JupyterLab 4 sanitizes HTML output from untrusted notebooks, stripping
 ``<style>``, ``<script>``, ``<iframe>``, ``<button>``, ``<input>``, etc.
 However, when a notebook is **trusted** (either run live by the user, or
 signed with ``jupyter trust``), all HTML passes through unsanitized.
-This renderer wraps the entire visualization in ``<iframe srcdoc="...">``,
-which:
+This renderer wraps the entire visualization in ``<iframe srcdoc="...">``, which:
   - Works in trusted notebooks (live execution + signed notebooks)
   - Contains full HTML with ``<style>``, ``<script>``, ``<input type="range">``
   - Is fully isolated from JupyterLab's CSS/JS
@@ -26,11 +25,12 @@ Layout (OPT_Mentor / Python Tutor style):
   │              │  └──┘           │  └──┘                    │
   └──────────────┴───────────────────────────────────────────┘
-Key design:
-  - Slider navigation (``<input type="range">``) — not number buttons
-  - SVG arrows from frame variables to heap objects (like OPT_Mentor/jsPlumb)
+Key design (matches jupyter-cpp-tutor):
+  - Fixed widget height with internal scrolling — no "dancing" cell
+  - Slider navigation (``<input type="range">``)
+  - SVG arrows from frame variables to heap objects
   - Single-step view — only current step shown, JS swaps content
-  - Resizable code panel (draggable divider)
+  - Draggable dividers between columns (double-click to collapse)
   - Functions show TRUE name (co_name), not __name__ (functools.wraps-safe)
   - Heap only shows objects reachable from the current call stack
 """
@@ -39,17 +39,11 @@ from __future__ import annotations
 import html
 import json
-__all__ = ["render_trace", "render_trace_widget"]
+__all__ = ["render_trace"]
 def _generate_inner_html(steps: list[dict], source_code: str, height: int = 500) -> str:
-    """Generate the full HTML page that goes inside the iframe srcdoc.
-    This is a self-contained HTML page with:
-      - CSS for the visualization layout
-      - All step data embedded as JSON
-      - JavaScript for step navigation, SVG arrows, resizing
-    """
+    """Generate the full HTML page that goes inside the iframe srcdoc."""
     if not steps:
         return '<!DOCTYPE html><html><body><p style="color:red;">No trace steps to display.</p></body></html>'
@@ -74,6 +68,8 @@ def _generate_inner_html(steps: list[dict], source_code: str, height: int = 500)
             "stdout": step.get("stdout", ""),
             "call_stack": [],
             "return_value": step.get("return_value"),
+            "error": step.get("error"),
+            "func": step.get("func"),
             "event": step.get("event", ""),
             "input_prompt": step.get("input_prompt", ""),
             "input_index": step.get("input_index", -1),
@@ -107,7 +103,7 @@ def _generate_inner_html(steps: list[dict], source_code: str, height: int = 500)
     steps_json = json.dumps(clean_steps, ensure_ascii=False)
     source_json = json.dumps(source_lines, ensure_ascii=False)
-    return f"""<!DOCTYPE html>
+    return rf"""<!DOCTYPE html>
 <html lang="en">
 <head>
 <meta charset="utf-8">
@@ -187,55 +183,58 @@ body {{
   overflow-y: auto;
   min-height: 20px;
 }}
-/* Main area */
+/* Main content area — flex, internal scroll, fixed height */
 .jpt-main {{
   display: flex;
-  align-items: stretch;
+  flex: 1;
+  overflow: hidden;
+  min-height: 0;
 }}
 .jpt-code-section {{
   flex: 0 0 40%;
   min-width: 30px;
   overflow: auto;
   background: #fafafa;
-  position: relative;
+  border-right: 1px solid #d4d4d4;
 }}
 .jpt-code-section::-webkit-scrollbar {{ width: 8px; height: 8px; }}
 .jpt-code-section::-webkit-scrollbar-thumb {{ background: #cbd5e1; border-radius: 4px; }}
-/* Draggable vertical dividers between columns */
+/* Draggable dividers */
 .jpt-divider {{
   flex: 0 0 6px;
   cursor: col-resize;
   background: #d4d4d4;
-  position: relative;
   user-select: none;
   -webkit-user-select: none;
   transition: background 0.15s;
+  flex-shrink: 0;
 }}
 .jpt-divider:hover {{ background: #3b82f6; }}
 .jpt-divider.jpt-dragging {{ background: #2563eb; }}
 .jpt-divider.jpt-collapsed {{ background: #9ca3af; cursor: pointer; }}
-.jpt-divider.jpt-collapsed:hover {{ background: #3b82f6; }}
-/* Right panel holds frames-divider-heap, no overflow so SVG arrows stay aligned */
+/* Right panel holds frames + heap, with SVG overlay */
 .jpt-right-panel {{
   flex: 1;
   display: flex;
   min-width: 0;
   position: relative;
+  overflow: hidden;
 }}
 .jpt-frames-section {{
   flex: 0 0 35%;
   min-width: 30px;
+  overflow: auto;
   padding: 6px;
   background: #fafafa;
 }}
 .jpt-heap-section {{
   flex: 1;
+  overflow: auto;
   padding: 6px;
   background: #f5f5f5;
-  position: relative;
   min-width: 30px;
 }}
-/* Code */
+/* Code lines */
 .jpt-code-line {{
   display: flex;
   align-items: baseline;
@@ -253,6 +252,31 @@ body {{
   background: #fce7f3;
   border-left: 3px solid #e10c65;
 }}
+.jpt-code-line.jpt-error {{
+  background: #fee2e2;
+  border-left: 3px solid #dc2626;
+}}
+.jpt-error .jpt-arrow {{ color: #dc2626; }}
+.jpt-error .jpt-code-text {{ color: #b91c1c; font-weight: 600; }}
+/* Error banner shown in the Program Output panel on exception steps */
+.jpt-error-banner {{
+  margin-top: 4px;
+  background: #fee2e2;
+  border: 1px solid #fca5a5;
+  border-left: 4px solid #dc2626;
+  border-radius: 4px;
+  padding: 6px 10px;
+  color: #991b1b;
+  font-family: 'DejaVu Sans Mono', monospace;
+  font-size: 12px;
+  white-space: pre-wrap;
+  word-break: break-word;
+}}
+.jpt-error-banner .jpt-error-banner-title {{
+  display: block;
+  font-weight: 700;
+  margin-bottom: 2px;
+}}
 .jpt-arrow {{
   width: 16px; flex: 0 0 16px; text-align: center;
   color: transparent; font-weight: bold; user-select: none;
@@ -264,12 +288,12 @@ body {{
 }}
 .jpt-code-text {{ flex: 1; padding-left: 4px; }}
 /* Python syntax highlighting */
-.jpt-tok-kw {{ color: #c678dd; font-weight: 600; }}      /* keywords: def, if, for... */
-.jpt-tok-str {{ color: #98c379; }}                       /* strings */
-.jpt-tok-num {{ color: #d19a66; }}                       /* numbers */
-.jpt-tok-com {{ color: #7c7c7c; font-style: italic; }}   /* comments */
-.jpt-tok-fn  {{ color: #61afef; }}                       /* function names */
-.jpt-tok-builtin {{ color: #56b6c2; }}                   /* builtins: print, len... */
+.jpt-tok-kw {{ color: #c678dd; font-weight: 600; }}
+.jpt-tok-str {{ color: #98c379; }}
+.jpt-tok-num {{ color: #d19a66; }}
+.jpt-tok-com {{ color: #7c7c7c; font-style: italic; }}
+.jpt-tok-fn  {{ color: #61afef; }}
+.jpt-tok-builtin {{ color: #56b6c2; }}
 /* Frames */
 .jpt-frame {{
   border: 1px solid #bae6fd; border-radius: 4px; background: #f0f9ff;
@@ -281,6 +305,10 @@ body {{
   display: flex; justify-content: space-between;
 }}
 .jpt-frame-line {{ font-size: 10px; font-weight: normal; color: #64748b; }}
+.jpt-return-badge {{
+  font-size: 10px; font-weight: 600; color: #065f46; background: #d1fae5;
+  border-radius: 3px; padding: 0 5px; font-family: 'DejaVu Sans Mono', monospace;
+}}
 .jpt-frame-body {{ padding: 3px 8px; }}
 .jpt-var-row {{
   display: flex; align-items: center; padding: 1px 0; font-size: 12px; gap: 2px;
@@ -348,7 +376,6 @@ body {{
   pointer-events: none; z-index: 10;
 }}
 .jpt-arrow-path {{ stroke: #6b7280; stroke-width: 1.5; fill: none; marker-end: url(#arrowhead); }}
-.jpt-arrow-path-highlight {{ stroke: #3b82f6; stroke-width: 2; }}
 /* Input dialog overlay */
 .jpt-input-overlay {{
   position: absolute; top: 0; left: 0; width: 100%; height: 100%;
@@ -384,7 +411,7 @@ body {{
 </style>
 </head>
 <body>
-<div class="jpt-widget" id="jptWidget">
+<div class="jpt-widget" id="jptWidget" style="height:{height}px;position:relative;">
   <!-- Input dialog overlay (hidden by default) -->
   <div class="jpt-input-overlay" id="inputOverlay" style="display:none;">
     <div class="jpt-input-dialog">
@@ -404,6 +431,7 @@ body {{
   <div class="jpt-output-section">
     <div class="jpt-output-label">Program Output</div>
     <div class="jpt-stdout" id="stdout"></div>
+    <div class="jpt-error-banner" id="errorBanner" style="display:none;"></div>
     <div class="jpt-input-badge" id="inputBadge" style="display:none;"></div>
   </div>
   <div class="jpt-main">
@@ -439,6 +467,7 @@ body {{
   var slider = document.getElementById('slider');
   var stepCounter = document.getElementById('stepCounter');
   var stdout = document.getElementById('stdout');
+  var errorBanner = document.getElementById('errorBanner');
   var codeDisplay = document.getElementById('codeDisplay');
   var framesSection = document.getElementById('framesSection');
   var heapContent = document.getElementById('heapContent');
@@ -454,8 +483,7 @@ body {{
   }}
   function funcDisplayName(ref) {{
-    if (ref.true_name) return ref.true_name;
-    return ref.name || 'func';
+    return ref.true_name || ref.name;
   }}
   // ─── Python syntax highlighting ──────────────────────────────────
@@ -472,41 +500,33 @@ body {{
   var builtinSet = {{}}; PY_BUILTINS.forEach(function(b){{ builtinSet[b] = 1; }});
   function highlightPython(line) {{
-    // Tokenize: comments, strings, numbers, identifiers, operators
     var result = '';
     var i = 0;
     while (i < line.length) {{
       var ch = line[i];
-      // Comment
       if (ch === '#') {{
         result += '<span class="jpt-tok-com">' + escapeHtml(line.substring(i)) + '</span>';
         break;
       }}
-      // String (single, double, triple)
       if (ch === '"' || ch === "'") {{
         var quote = ch;
-        // Check triple-quote
         if (line.substring(i, i+3) === quote+quote+quote) {{
           var end = line.indexOf(quote+quote+quote, i+3);
           if (end < 0) end = line.length - 3;
-          var s = line.substring(i, end+3);
-          result += '<span class="jpt-tok-str">' + escapeHtml(s) + '</span>';
+          result += '<span class="jpt-tok-str">' + escapeHtml(line.substring(i, end+3)) + '</span>';
           i = end + 3;
           continue;
         }}
-        // Single/double quote — find matching close (handle escapes)
         var j = i + 1;
         while (j < line.length) {{
           if (line[j] === '\\\\') {{ j += 2; continue; }}
           if (line[j] === quote) {{ j++; break; }}
           j++;
         }}
-        var s = line.substring(i, j);
-        result += '<span class="jpt-tok-str">' + escapeHtml(s) + '</span>';
+        result += '<span class="jpt-tok-str">' + escapeHtml(line.substring(i, j)) + '</span>';
         i = j;
         continue;
       }}
-      // f-string prefix (f, r, b, fr, rf, etc. before quote)
       if (/[frbFRB]/.test(ch) && i+1 < line.length && (line[i+1] === '"' || line[i+1] === "'")) {{
         var j = i;
         while (j < line.length && /[frbFRB]/.test(line[j])) j++;
@@ -518,17 +538,14 @@ body {{
             if (line[k] === quote) {{ k++; break; }}
             k++;
           }}
-          var s = line.substring(i, k);
-          result += '<span class="jpt-tok-str">' + escapeHtml(s) + '</span>';
+          result += '<span class="jpt-tok-str">' + escapeHtml(line.substring(i, k)) + '</span>';
           i = k;
           continue;
         }}
       }}
-      // Number
       if (/[0-9]/.test(ch) || (ch === '.' && i+1 < line.length && /[0-9]/.test(line[i+1]))) {{
         var j = i;
-        while (j < line.length && /[0-9._xXeE+\-a-fA-F]/.test(line[j])) {{
-          // stop on +/- if not part of exponent
+        while (j < line.length && /[0-9._xXeE+\\-a-fA-F]/.test(line[j])) {{
           if ((line[j] === '+' || line[j] === '-') && !/[eE]/.test(line[j-1])) break;
           j++;
         }}
@@ -536,12 +553,10 @@ body {{
         i = j;
         continue;
       }}
-      // Identifier / keyword / builtin
       if (/[a-zA-Z_]/.test(ch)) {{
         var j = i;
         while (j < line.length && /[a-zA-Z0-9_]/.test(line[j])) j++;
         var word = line.substring(i, j);
-        // Check if followed by ( → function call
         var afterWord = line.substring(j).trim();
         if (kwSet[word]) {{
           result += '<span class="jpt-tok-kw">' + escapeHtml(word) + '</span>';
@@ -555,14 +570,13 @@ body {{
         i = j;
         continue;
       }}
-      // Default: escape and output
       result += escapeHtml(ch);
       i++;
     }}
     return result;
   }}
-  function renderCode(lineNo, prevLineNo) {{
+  function renderCode(lineNo, prevLineNo, errorLineNo) {{
     if (!lineNo || lineNo < 1) lineNo = 1;
     if (!prevLineNo) prevLineNo = 0;
     var html = '';
@@ -571,10 +585,11 @@ body {{
       var line = sourceLines[i] || '';
       var highlighted = line.trim() ? highlightPython(line) : '&nbsp;';
       var cls = '';
-      if (ln === lineNo) cls = ' jpt-current';
+      if (errorLineNo && ln === errorLineNo) cls = ' jpt-error';
+      else if (ln === lineNo) cls = ' jpt-current';
       else if (ln === prevLineNo) cls = ' jpt-executed';
       html += '<div class="jpt-code-line' + cls + '">' +
-              '<span class="jpt-arrow">▶</span>' +
+              '<span class="jpt-arrow">' + (errorLineNo && ln === errorLineNo ? '✗' : '▶') + '</span>' +
               '<span class="jpt-lineno">' + ln + '</span>' +
               '<span class="jpt-code-text">' + highlighted + '</span>' +
               '</div>';
@@ -672,7 +687,7 @@ body {{
         html += '<div class="jpt-heap-object jpt-heap-module" data-heap-id="' + heapId + '">' +
                 '<div class="jpt-heap-type-label">module ' + escapeHtml(ref.name) + '</div></div>';
       }} else if (ref.is_function) {{
-        var tn = ref.true_name || ref.name;
+        var tn = funcDisplayName(ref);
         var dn = ref.display_name || ref.name;
         var attrs = details.attrs || [];
         var attrHtml = '';
@@ -710,14 +725,11 @@ body {{
   }}
   function drawArrows() {{
-    // Clear existing arrows (keep defs)
     while (svgOverlay.lastChild && svgOverlay.lastChild.tagName !== 'defs') {{
       svgOverlay.removeChild(svgOverlay.lastChild);
     }}
-    // SVG overlay lives in .jpt-right-panel, spanning both frames and heap
     var rightPanel = document.getElementById('rightPanel');
     var panelRect = rightPanel.getBoundingClientRect();
-    // Find all pointer boxes in frames and matching heap objects
     var pointers = framesSection.querySelectorAll('.jpt-var-pointer[data-heap-id]');
     for (var i = 0; i < pointers.length; i++) {{
       var ptr = pointers[i];
@@ -727,12 +739,10 @@ body {{
       if (!heapObj) continue;
       var ptrRect = ptr.getBoundingClientRect();
       var objRect = heapObj.getBoundingClientRect();
-      // Convert to SVG coordinates (relative to rightPanel)
       var x1 = ptrRect.right - panelRect.left;
       var y1 = ptrRect.top + ptrRect.height / 2 - panelRect.top;
       var x2 = objRect.left - panelRect.left;
       var y2 = objRect.top + objRect.height / 2 - panelRect.top;
-      // Draw a curved path from pointer to heap object
       var midX = x1 + (x2 - x1) * 0.5;
       var path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
       path.setAttribute('d', 'M ' + x1 + ' ' + y1 + ' C ' + midX + ' ' + y1 + ', ' + midX + ' ' + y2 + ', ' + x2 + ' ' + y2);
@@ -741,45 +751,21 @@ body {{
     }}
   }}
-  function autoResize() {{
-    // Auto-resize widget to fit content — the widget's height follows
-    // the tallest of code/frames/heap so there is no internal scroll
-    // and arrows never detach from their targets.
-    // The parent page polls the widget height and resizes the iframe.
-    var codeH = codeDisplay.scrollHeight;
-    var framesH = framesSection.scrollHeight;
-    var heapH = heapContent.scrollHeight;
-    var contentH = Math.max(codeH, framesH, heapH, {height});
-    // Add navbar + output section heights
-    var navbarH = document.querySelector('.jpt-navbar').offsetHeight;
-    var outputH = document.querySelector('.jpt-output-section').offsetHeight;
-    var totalH = contentH + navbarH + outputH + 12;  // +12 for borders/padding
-    // Set widget height so parent script can read it
-    document.getElementById('jptWidget').style.height = totalH + 'px';
-  }}
   // ─── Input handling ──────────────────────────────────────────────
-  // inputsCollected: cached values for each input_index
-  // Once collected, navigation back/forth never re-prompts.
-  var inputsCollected = {{}};  // input_index → value string
+  var inputsCollected = {{}};
   var inputOverlay = document.getElementById('inputOverlay');
   var inputDialogLabel = document.getElementById('inputDialogLabel');
   var inputDialogInput = document.getElementById('inputDialogInput');
   var inputDialogBtn = document.getElementById('inputDialogBtn');
-  // Pre-populate from step data (inputs already provided during tracing)
   for (var si = 0; si < nSteps; si++) {{
     var ss = steps[si];
     if (ss.input_index >= 0 && ss.input_index !== undefined) {{
-      // Extract the input value from stdout: prompt + value + newline
-      // The value is what the user typed (echoed after the prompt)
       if (!(ss.input_index in inputsCollected)) {{
         var prompt = ss.input_prompt || '';
         var out = ss.stdout || '';
-        // stdout contains prompt + value + newline, find the value
         if (out.includes(prompt)) {{
           var afterPrompt = out.substring(out.indexOf(prompt) + prompt.length);
-          // The value is everything up to the first newline
           var nl = afterPrompt.indexOf(String.fromCharCode(10));
           if (nl >= 0) {{
             inputsCollected[ss.input_index] = afterPrompt.substring(0, nl);
@@ -791,7 +777,6 @@ body {{
     }}
   }}
-  // Show input badge in output section if this step has input
   function updateInputBadge(step) {{
     var badge = document.getElementById('inputBadge');
     if (!badge) return;
@@ -810,12 +795,19 @@ body {{
     curStep = idx;
     var step = steps[idx];
     var prevLine = (idx > 0) ? steps[idx - 1].line : 0;
-    renderCode(step.line || 0, prevLine);
+    var isError = (step.event === 'exception' && step.error);
+    renderCode(step.line || 0, prevLine, isError ? step.line : 0);
     renderFrames(step);
     renderHeap(step);
     stdout.textContent = step.stdout || '';
-    if (!step.stdout) stdout.style.color = '#86efac', stdout.style.fontStyle = 'italic', stdout.textContent = '(no output yet)';
-    else stdout.style.color = '#166534', stdout.style.fontStyle = 'normal';
+    if (!step.stdout) {{ stdout.style.color = '#86efac'; stdout.style.fontStyle = 'italic'; stdout.textContent = '(no output yet)'; }}
+    else {{ stdout.style.color = '#166534'; stdout.style.fontStyle = 'normal'; }}
+    if (isError) {{
+      errorBanner.innerHTML = '<span class="jpt-error-banner-title">Uncaught exception</span>' + escapeHtml(step.error);
+      errorBanner.style.display = 'block';
+    }} else {{
+      errorBanner.style.display = 'none';
+    }}
     updateInputBadge(step);
     stepCounter.textContent = 'Step ' + (idx + 1) + ' of ' + nSteps;
     slider.value = idx;
@@ -823,18 +815,12 @@ body {{
     btnPrev.disabled = (idx === 0);
     btnNext.disabled = (idx === nSteps - 1);
     btnLast.disabled = (idx === nSteps - 1);
-    // Draw arrows + auto-resize after DOM is updated
+    // Draw arrows after DOM is updated (height is fixed, no resize needed)
     requestAnimationFrame(function() {{
       requestAnimationFrame(function() {{
-        autoResize();
         drawArrows();
       }});
     }});
-    // Safety: also redraw after a longer delay in case rAF fires too early
-    setTimeout(function() {{
-      autoResize();
-      drawArrows();
-    }}, 100);
   }}
   // Event handlers
@@ -850,14 +836,12 @@ body {{
     else if (e.key === 'ArrowRight') {{ renderStep(curStep + 1); e.preventDefault(); }}
   }});
-  // Redraw arrows + auto-resize on window resize and scroll
-  window.addEventListener('resize', function() {{ autoResize(); drawArrows(); }});
+  // Redraw arrows on resize/scroll (height is fixed, just reposition arrows)
+  window.addEventListener('resize', drawArrows);
   framesSection.addEventListener('scroll', drawArrows);
   heapContent.addEventListener('scroll', drawArrows);
   // ─── Draggable dividers ──────────────────────────────────────────
-  // Divider 1: between code section and right panel
-  // Divider 2: between frames section and heap section
   var divider1 = document.getElementById('divider1');
   var divider2 = document.getElementById('divider2');
   var codeSection = document.getElementById('codeSection');
@@ -865,13 +849,11 @@ body {{
   var mainEl = document.querySelector('.jpt-main');
   var rightPanelEl = document.getElementById('rightPanel');
-  // Remember pre-collapse flex values so we can restore
   var savedCodeFlex = '0 0 40%';
   var savedFramesFlex = '0 0 35%';
-  function startDrag(divider, opts) {{
+  function startDrag(divider) {{
     return function(e) {{
-      // Don't start drag if it was a double-click (collapse toggle)
       if (divider._justCollapsed) {{
         divider._justCollapsed = false;
         return;
@@ -881,43 +863,35 @@ body {{
       var startX = e.clientX;
       var startCodeW = codeSection.offsetWidth;
       var startFramesW = framesSection.offsetWidth;
-      var startHeapW = heapSection.offsetWidth;
       var mainW = mainEl.offsetWidth;
       var panelW = rightPanelEl.offsetWidth;
       function onMove(ev) {{
         var dx = ev.clientX - startX;
         if (divider === divider1) {{
-          // Resize code vs (divider + right panel)
           var newCodeW = Math.max(30, Math.min(mainW - 60, startCodeW + dx));
           var pct = (newCodeW / mainW) * 100;
           codeSection.style.flex = '0 0 ' + pct + '%';
-          // Ensure right panel takes remaining space
           rightPanelEl.style.flex = '1';
         }} else {{
-          // Resize frames vs heap within right panel
           var newFramesW = Math.max(30, Math.min(panelW - 36, startFramesW + dx));
           var fPct = (newFramesW / panelW) * 100;
           framesSection.style.flex = '0 0 ' + fPct + '%';
           heapSection.style.flex = '1';
         }}
-        // Live redraw: arrows must follow the new column positions
         drawArrows();
-        autoResize();
       }}
-      function onUp(ev) {{
+      function onUp() {{
         divider.classList.remove('jpt-dragging');
         document.removeEventListener('mousemove', onMove);
         document.removeEventListener('mouseup', onUp);
-        // Save flex values for collapse restore
         if (divider === divider1) {{
           savedCodeFlex = codeSection.style.flex || '0 0 40%';
         }} else {{
           savedFramesFlex = framesSection.style.flex || '0 0 35%';
         }}
         drawArrows();
-        autoResize();
       }}
       document.addEventListener('mousemove', onMove);
@@ -925,14 +899,12 @@ body {{
     }};
   }}
-  // Double-click to collapse/expand
-  function toggleCollapse(divider, sectionToHide, savedFlexVar, flexVarName) {{
+  function toggleCollapse(divider, sectionToHide) {{
     return function(e) {{
       e.preventDefault();
       e.stopPropagation();
       var isCollapsed = divider.classList.contains('jpt-collapsed');
       if (isCollapsed) {{
-        // Expand: restore saved flex
         divider.classList.remove('jpt-collapsed');
         sectionToHide.style.display = '';
         if (divider === divider1) {{
@@ -943,7 +915,6 @@ body {{
           heapSection.style.flex = '1';
         }}
       }} else {{
-        // Collapse: save current flex then hide
         if (divider === divider1) {{
           savedCodeFlex = codeSection.style.flex || '0 0 40%';
         }} else {{
@@ -951,7 +922,6 @@ body {{
         }}
         divider.classList.add('jpt-collapsed');
         sectionToHide.style.display = 'none';
-        // Let the other side take full space
         if (divider === divider1) {{
           codeSection.style.flex = '0 0 0';
           rightPanelEl.style.flex = '1';
@@ -962,17 +932,25 @@ body {{
       }}
       divider._justCollapsed = true;
       drawArrows();
-      autoResize();
     }};
   }}
-  divider1.addEventListener('mousedown', startDrag(divider1, {{}}));
-  divider2.addEventListener('mousedown', startDrag(divider2, {{}}));
-  divider1.addEventListener('dblclick', toggleCollapse(divider1, codeSection, savedCodeFlex, 'savedCodeFlex'));
-  divider2.addEventListener('dblclick', toggleCollapse(divider2, framesSection, savedFramesFlex, 'savedFramesFlex'));
-  // Initial render
-  renderStep(0);
+  divider1.addEventListener('mousedown', startDrag(divider1));
+  divider2.addEventListener('mousedown', startDrag(divider2));
+  divider1.addEventListener('dblclick', toggleCollapse(divider1, codeSection));
+  divider2.addEventListener('dblclick', toggleCollapse(divider2, framesSection));
+  // Initial render — if the program raises an error, start on the
+  // first exception step (like Python Tutor, which steps to the error),
+  // so the red line + error message are visible immediately.
+  var initialStep = 0;
+  for (var si0 = 0; si0 < nSteps; si0++) {{
+    if (steps[si0].event === 'exception' && steps[si0].error) {{
+      initialStep = si0;
+      break;
+    }}
+  }}
+  renderStep(initialStep);
 }})();
 </script>
 </body>
@@ -983,7 +961,6 @@ def render_trace(
     steps: list[dict],
     source_code: str | None = None,
     height: int = 500,
-    widget_id: str | None = None,
 ) -> str:
     """Render trace steps as interactive HTML inside an iframe.
@@ -991,10 +968,11 @@ def render_trace(
     ``<iframe srcdoc="...">`` which works in trusted JupyterLab notebooks.
     Features:
+      - Fixed widget height with internal scrolling — no "dancing" cell
       - Slider navigation (``<input type="range">``) — drag to scrub through steps
       - SVG arrows from frame variables to heap objects (like OPT_Mentor)
       - Single-step view — only current step shown, JS swaps content
-      - Resizable code panel (CSS ``resize: horizontal``)
+      - Draggable dividers between columns (double-click to collapse)
       - Functions show TRUE name (co_name), not __name__ (functools.wraps-safe)
       - Heap only shows objects reachable from the current call stack
       - Keyboard navigation (← → arrows)
@@ -1002,31 +980,33 @@ def render_trace(
     inner = _generate_inner_html(steps, source_code or "", height)
     # Escape for srcdoc attribute
     escaped = html.escape(inner, quote=True)
-    # The iframe auto-resizes via a polling script in the parent that checks
-    # each iframe's content height and adjusts. This works in trusted notebooks
-    # where <script> survives sanitization.
+    # Match cpp-tutor's approach exactly to prevent "dancing":
+    # 1. border:none so offsetHeight === style.height (no mismatch loop)
+    # 2. display:block + margin:0 to avoid inline baseline gap
+    # 3. Script reads body.scrollHeight + 20 (idempotent — always writes
+    #    the same value, so no reflow)
+    # 4. onload for initial sizing (stripped by DOMPurify when untrusted,
+    #    but setInterval catches up within 200ms)
     return (
         f'<iframe srcdoc="{escaped}" class="jpt-iframe" '
-        f'style="width:100%;border:1px solid #d4d4d4;border-radius:6px;"></iframe>'
-        f'<script>(function(){{'
-        f'var frame=this.previousElementSibling;'
-        f'function resize(){{'
+        f'style="width:100%;border:none;overflow:hidden;'
+        f'display:block;margin:0;" '
+        f'onload="this.style.height=this.contentDocument.body.scrollHeight+20+\'px\'">'
+        f'</iframe>'
+        f'<script>'
+        f'(function(){{'
+        f'function autoResize(){{'
+        f'document.querySelectorAll(\'iframe.jpt-iframe\').forEach(function(frame){{'
         f'try{{'
-        f'var d=frame.contentDocument;'
-        f'if(!d)return;'
-        f'var w=d.getElementById("jptWidget");'
-        f'if(!w)return;'
-        f'var h=w.offsetHeight+20;'
-        f'if(h>0&&frame.offsetHeight!==h){{frame.style.height=h+"px";}}'
+        f'var h=frame.contentDocument.body.scrollHeight;'
+        f'if(h>0)frame.style.height=(h+20)+\'px\';'
         f'}}catch(e){{}}'
+        f'}});'
         f'}}'
-        f'resize();'
-        f'setInterval(resize,200);'
-        f'}}).call(document.currentScript);'
+        f'if(!window._jptPollStarted){{'
+        f'window._jptPollStarted=true;'
+        f'setInterval(autoResize,200);'
+        f'}}'
+        f'}})();'
         f'</script>'
     )
-def render_trace_widget(steps: list[dict], source_code: str | None = None) -> str:
-    """Alias for render_trace (returns HTML string)."""
-    return render_trace(steps, source_code=source_code)

{jupyter_python_tutor-0.3.0 → jupyter_python_tutor-0.3.3}/jupyter_python_tutor/tracer.py RENAMED Viewed

@@ -514,14 +514,35 @@ def _trace_code_internal(
     # Same object always gets the same label across all steps.
     id_map: dict[int, str] = {}
+    # Frames that have seen an 'exception' event but not yet resumed
+    # (no intervening 'line'/'call' in the same frame).  A 'return' event
+    # from such a frame is a spurious interpreter artifact of exception
+    # unwinding (Python fires 'return' with arg=None as each frame is
+    # popped), NOT a real return — we suppress it so the student isn't
+    # shown a misleading "Return: None" step after an error.
+    pending_exc_frames: set[int] = set()
     def _trace(frame, event, arg):
         nonlocal step_count, _current_input_prompt, _current_input_index
         if frame.f_code.co_filename != filename:
             return _trace  # skip frames from other files
         if step_count >= max_steps:
             raise _StepLimitExceeded()  # stop execution, not just tracing
+        # Suppress the synthetic module-frame 'call' event.  CPython fires it
+        # with f_lineno == 0 before the first line runs, which rendered a
+        # phantom "line 0" step.  The first real 'line' event is step 1, so
+        # the visualization now starts at line 1 (matching Python Tutor).
+        if frame.f_code.co_name == "<module>" and event == "call":
+            return _trace
         step_count += 1
+        if event in ("line", "call"):
+            # Execution resumed in this frame → any earlier exception was
+            # caught here, so clear its unwinding marker.
+            pending_exc_frames.discard(id(frame))
         # Capture input info from the PREVIOUS step's execution.
         # input() runs during line execution (between trace callbacks),
         # so _current_input_prompt was set by the line that just ran.
@@ -561,7 +582,22 @@ def _trace_code_internal(
                 "input_index": step_input_index,
             })
         elif event == "return":
-            ret_repr = _safe_repr(arg) if arg is not None else "None"
+            # Suppress the spurious 'return' (arg=None) that CPython emits
+            # when an exception unwinds a frame that did NOT catch it.
+            # (During unwinding even the module frame reports line 0, so
+            # this also keeps the phantom "line 0" out of error traces.)
+            if id(frame) in pending_exc_frames:
+                pending_exc_frames.discard(id(frame))
+                return _trace
+            pending_exc_frames.discard(id(frame))
+            if frame.f_code.co_name == "<module>":
+                # Scripts don't return values.  Keep this step — it is the
+                # one that carries the FINAL state (all variables bound,
+                # complete stdout, since 'line' events fire before each
+                # statement) — but present no return value.
+                ret_repr = None
+            else:
+                ret_repr = _safe_repr(arg) if arg is not None else "None"
             steps.append({
                 "line": lineno,
                 "source": source,
@@ -578,6 +614,15 @@ def _trace_code_internal(
             # Don't record our internal exception
             if exc_type is _StepLimitExceeded:
                 return None
+            if lineno == 0:
+                # The interpreter re-fires the 'exception' event as a frame
+                # finishes unwinding; that second event reports line 0
+                # (no source line).  Only the first event — with the real
+                # line number — is worth showing.
+                return _trace
+            # Mark this frame as mid-unwind; a 'return' or re-fired
+            # 'exception' from it before resuming is spurious.
+            pending_exc_frames.add(id(frame))
             steps.append({
                 "line": lineno,
                 "source": source,
@@ -603,17 +648,22 @@ def _trace_code_internal(
     except _StepLimitExceeded:
         pass  # execution stopped due to step limit
     except Exception as e:
-        steps.append({
-            "line": 0,
-            "source": f"# {type(e).__name__}: {e}",
-            "call_stack": [],
-            "event": "exception",
-            "func": "<module>",
-            "error": f"{type(e).__name__}: {e}",
-            "stdout": captured.getvalue(),
-            "input_prompt": "",
-            "input_index": -1,
-        })
+        # Safety net for exceptions the trace callback can't see (e.g.
+        # SyntaxError, which is raised before execution starts).  If the
+        # trace already recorded the exception with its real line number,
+        # don't append a duplicate "line 0" step.
+        if not any(s.get("event") == "exception" for s in steps):
+            steps.append({
+                "line": 0,
+                "source": f"# {type(e).__name__}: {e}",
+                "call_stack": [],
+                "event": "exception",
+                "func": "<module>",
+                "error": f"{type(e).__name__}: {e}",
+                "stdout": captured.getvalue(),
+                "input_prompt": "",
+                "input_index": -1,
+            })
     finally:
         sys.settrace(old_trace)
         sys.stdout = old_stdout

{jupyter_python_tutor-0.3.0 → jupyter_python_tutor-0.3.3}/jupyter_python_tutor.egg-info/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jupyter-python-tutor
-Version: 0.3.0
+Version: 0.3.3
 Summary: Python Tutor-style step-by-step code visualization for JupyterLab 4.x and Notebook 7
 Author: dive4dec
 License-Expression: MIT

{jupyter_python_tutor-0.3.0 → jupyter_python_tutor-0.3.3}/pyproject.toml RENAMED Viewed

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "jupyter-python-tutor"
-version = "0.3.0"
+version = "0.3.3"
 description = "Python Tutor-style step-by-step code visualization for JupyterLab 4.x and Notebook 7"
 readme = "README.md"
 license = "MIT"

{jupyter_python_tutor-0.3.0 → jupyter_python_tutor-0.3.3}/tests/test_renderer.py RENAMED Viewed

@@ -371,3 +371,48 @@ outer(5)
         result = render_trace(steps, source_code=code)
         assert "<iframe" in result
         assert "outer" in result or "inner" in result
+class TestErrorDisplay:
+    """Error steps must be delivered to and displayed by the frontend."""
+    def test_error_field_delivered_to_frontend(self):
+        code = 'x = 1+"1"\nprint(x)'
+        steps = trace_code(code)
+        result = render_trace(steps, source_code=code)
+        # The error message must survive into the embedded step JSON
+        # (it was previously dropped by the clean_step projection).
+        # (quotes are HTML-escaped inside the srcdoc, so match a stable
+        # unquoted substring)
+        assert "unsupported operand type(s) for +" in result
+        assert "int" in result and "str" in result
+    def test_frontend_has_error_rendering(self):
+        code = 'x = 1+"1"'
+        steps = trace_code(code)
+        inner = _get_srcdoc_content(render_trace(steps, source_code=code))
+        assert 'id="errorBanner"' in inner                 # banner element
+        assert ".jpt-code-line.jpt-error" in inner          # red line CSS
+        assert "Uncaught exception" in inner                # banner text
+        assert "jpt-error" in inner                         # line gets class
+    def test_frontend_starts_at_error_step(self):
+        code = 'x = 1+"1"\nprint(x)'
+        steps = trace_code(code)
+        inner = _get_srcdoc_content(render_trace(steps, source_code=code))
+        # Auto-jump: initial step is the first exception step
+        assert "initialStep" in inner
+        assert "event === 'exception'" in inner
+    def test_no_error_banner_for_successful_code(self):
+        steps = trace_code("x = 1\nprint(x)")
+        result = render_trace(steps, source_code="x = 1\nprint(x)")
+        # No exception steps → no error data in the embedded JSON
+        assert "Uncaught exception" in _get_srcdoc_content(result)  # CSS/JS strings
+        # but no step carries an error payload
+        import html as H
+        src = _get_srcdoc_content(result)
+        jsline = [l for l in src.splitlines() if l.strip().startswith("var steps = ")][0]
+        import json
+        data = json.loads(jsline.strip()[len("var steps = "):-1])
+        assert not any(s.get("error") for s in data)

{jupyter_python_tutor-0.3.0 → jupyter_python_tutor-0.3.3}/tests/test_tracer.py RENAMED Viewed

@@ -13,6 +13,10 @@ class TestBasicTracing:
     def test_simple_assignment(self):
         steps = get_trace("x = 3")
         assert len(steps) >= 1
+        # No synthetic "call <module>" (line 0) step — the first step is
+        # the first real line.
+        assert steps[0]["event"] == "line"
+        assert steps[0]["line"] == 1
         assert steps[-1]["event"] in ("line", "return")
     def test_step_has_line_number(self):
@@ -282,6 +286,91 @@ class TestErrorHandling:
         steps = get_trace("1/0")
         assert any(s.get("event") == "exception" for s in steps)
+    def test_uncaught_error_has_correct_line_and_message(self):
+        steps = get_trace('x = 1+"1"\nprint(x)')
+        excs = [s for s in steps if s.get("event") == "exception"]
+        assert len(excs) >= 1
+        # The failing line is highlighted
+        assert any(s["line"] == 1 for s in excs)
+        # The error message matches Python's
+        first = excs[0]
+        assert "TypeError" in first["error"]
+        assert "unsupported operand type(s) for +: 'int' and 'str'" in first["error"]
+    def test_no_phantom_return_after_uncaught_error(self):
+        """CPython fires a spurious 'return' (arg=None) when an uncaught
+        exception unwinds a frame.  The tracer must not surface it as a
+        'Return: None' step."""
+        steps = get_trace('x = 1+"1"\nprint(x)')
+        for s in steps:
+            if s["event"] == "return":
+                assert s.get("return_value") != "None", \
+                    f"phantom None-return step leaked: {s}"
+        # Exact step sequence: line 1 -> exception(s); no call/return steps
+        events = [s["event"] for s in steps]
+        assert events[0] == "line"
+        assert steps[0]["line"] == 1  # no phantom "call <module> line 0"
+        assert all(e == "exception" for e in events[1:])
+    def test_no_phantom_return_uncaught_in_nested_function(self):
+        steps = get_trace('def f():\n    return 1/0\n\ny = f()\nprint(y)')
+        for s in steps:
+            if s["event"] == "return":
+                assert s.get("return_value") != "None"
+        assert any(s["event"] == "exception" and "division by zero" in s["error"]
+                   for s in steps)
+    def test_real_return_kept_when_error_caught_in_same_frame(self):
+        code = ("def f():\n"
+                "    try:\n"
+                "        x = 1/0\n"
+                "    except ZeroDivisionError:\n"
+                "        x = 5\n"
+                "    return x\n"
+                "\ny = f()\nprint(y)")
+        steps = get_trace(code)
+        returns = [s for s in steps if s["event"] == "return"]
+        # f() really returns 5 — that step must survive
+        assert any(s.get("return_value") == "5" for s in returns)
+        assert any(s["event"] == "exception" for s in steps)
+    def test_real_return_kept_when_error_caught_in_caller(self):
+        code = ("def f():\n"
+                "    return 1/0\n"
+                "\ntry:\n"
+                "    f()\n"
+                "except ZeroDivisionError:\n"
+                "    pass\n"
+                'print("done")')
+        steps = get_trace(code)
+        # module finally returns None as a normal (non-unwind) return
+        assert any(s["event"] == "return" and s["func"] == "<module>"
+                   for s in steps)
+        assert "done" in steps[-1]["stdout"]
+    def test_no_line0_step_and_final_state_preserved(self):
+        """The synthetic module 'call' (line 0) must not be a step, and the
+        final module 'return' step must carry the complete final state
+        (all variables + all stdout) with NO return_value on the module."""
+        steps = get_trace("x = 3\ny = 4\nprint(x + y)")
+        assert steps[0]["line"] == 1
+        assert all(s["line"] >= 1 for s in steps)
+        last = steps[-1]
+        assert last["event"] == "return"
+        assert last["func"] == "<module>"
+        assert last.get("return_value") is None  # scripts don't return values
+        gv = last["call_stack"][0]
+        assert gv["simple_vars"].get("x") == "3"
+        assert gv["simple_vars"].get("y") == "4"
+        assert "7" in last["stdout"]
+    def test_module_return_has_no_return_value(self):
+        steps = get_trace("x = 1")
+        for s in steps:
+            if s["event"] == "return" and s["func"] == "<module>":
+                assert s.get("return_value") is None, \
+                    f"module frame must not show a return value: {s.get('return_value')!r}"
     def test_max_steps_limit(self):
         # Infinite loop should be stopped
         code = "while True:\n    pass"