jupyter-python-tutor 0.3.1__tar.gz → 0.3.3__tar.gz

{jupyter_python_tutor-0.3.1 → jupyter_python_tutor-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jupyter-python-tutor
-Version: 0.3.1
+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.1 → jupyter_python_tutor-0.3.3}/jupyter_python_tutor/__init__.py

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

{jupyter_python_tutor-0.3.1 → jupyter_python_tutor-0.3.3}/jupyter_python_tutor/renderer.py

@@ -68,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),
@@ -250,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;
@@ -278,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;
@@ -400,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">
@@ -435,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');
@@ -543,7 +576,7 @@ body {{
     return result;
   }}
 
-  function renderCode(lineNo, prevLineNo) {{
+  function renderCode(lineNo, prevLineNo, errorLineNo) {{
     if (!lineNo || lineNo < 1) lineNo = 1;
     if (!prevLineNo) prevLineNo = 0;
     var html = '';
@@ -552,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>';
@@ -761,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 (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;
@@ -899,8 +940,17 @@ body {{
   divider1.addEventListener('dblclick', toggleCollapse(divider1, codeSection));
   divider2.addEventListener('dblclick', toggleCollapse(divider2, framesSection));
 
-  // Initial render
-  renderStep(0);
+  // 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>

{jupyter_python_tutor-0.3.1 → jupyter_python_tutor-0.3.3}/jupyter_python_tutor/tracer.py

@@ -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.1 → jupyter_python_tutor-0.3.3}/jupyter_python_tutor.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jupyter-python-tutor
-Version: 0.3.1
+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.1 → jupyter_python_tutor-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "jupyter-python-tutor"
-version = "0.3.1"
+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.1 → jupyter_python_tutor-0.3.3}/tests/test_renderer.py

@@ -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.1 → jupyter_python_tutor-0.3.3}/tests/test_tracer.py

@@ -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"