jupyter-python-tutor 0.2.0__py3-none-any.whl

jupyter_python_tutor/__init__.py

@@ -0,0 +1,16 @@
+"""jupyter-python-tutor: Python Tutor-style visualization for JupyterLab 4.x and Notebook 7.
+
+Usage in a Jupyter cell:
+
+    %%tutor
+    x = 3
+    y = x + 4
+    print(y)
+"""
+from .tracer import trace_code
+from .renderer import render_trace
+from .magics import load_ipython_extension
+
+__version__ = "0.2.0"
+
+__all__ = ["trace_code", "render_trace", "load_ipython_extension"]

jupyter_python_tutor/magics.py

@@ -0,0 +1,109 @@
+"""IPython cell magic for jupyter-python-tutor.
+
+Usage in a Jupyter cell:
+
+    %%tutor
+    x = 3
+    y = x + 4
+    print(y)
+
+Options:
+    %%tutor --max-steps 1000   — limit the number of trace steps
+    %%tutor --raw              — output the trace as JSON instead of HTML
+    %%tutor --height 400       — set max-height of the variables panel (px)
+"""
+from __future__ import annotations
+
+import argparse
+import typing
+
+from IPython.core.magic import Magics, magics_class, cell_magic
+from IPython.display import HTML, JSON
+
+from .tracer import trace_code
+from .renderer import render_trace
+
+__all__ = ["TutorMagics", "load_ipython_extension", "unload_ipython_extension"]
+
+
+def _make_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="%%tutor",
+        description="Trace Python code and display an interactive visualization.",
+    )
+    parser.add_argument(
+        "--max-steps", type=int, default=5000,
+        help="Maximum number of trace steps to capture (default: 5000)",
+    )
+    parser.add_argument(
+        "--raw", action="store_true",
+        help="Output trace as JSON instead of interactive HTML",
+    )
+    parser.add_argument(
+        "--height", type=int, default=300,
+        help="Max height of the variables panel in pixels (default: 300)",
+    )
+    return parser
+
+
+@magics_class
+class TutorMagics(Magics):
+    """Register the %%tutor cell magic."""
+
+    @cell_magic("tutor")
+    def tutor(self, line: str, cell: str):
+        """Trace the cell code and display an interactive visualization."""
+        parser = _make_parser()
+        try:
+            args = parser.parse_args(line.split() if line else [])
+        except SystemExit:
+            return
+
+        # Pass the ACTUAL user namespace (not a copy) so that:
+        # 1. Variables/classes/functions from previous cells are available
+        # 2. Variables created by the traced code persist in the kernel
+        #    (just like a normal Jupyter cell)
+        # This matches how a regular cell works and how the Jupyter visual
+        # debugger operates.
+        user_ns = self.shell.user_ns
+
+        steps = trace_code(
+            cell,
+            max_steps=args.max_steps,
+            user_globals=user_ns,
+        )
+
+        if args.raw:
+            return JSON(steps)
+        else:
+            # render_trace returns an HTML string with an <iframe srcdoc="...">
+            # containing full CSS + JS for interactive visualization.
+            # The iframe approach bypasses JupyterLab's HTML sanitizer, which
+            # strips <style>, <script>, <iframe>, <input>, etc. from untrusted
+            # outputs. When the user runs the cell live, the output is trusted
+            # and the iframe renders with full interactivity (slider, SVG arrows).
+            result = render_trace(steps, source_code=cell, height=args.height)
+            import warnings
+            with warnings.catch_warnings():
+                # Suppress IPython's "Consider using IFrame instead" warning —
+                # we intentionally use HTML(iframe srcdoc) because IFrame()
+                # requires a URL, not inline HTML.
+                warnings.filterwarnings("ignore", message="Consider using IPython.display.IFrame")
+                from IPython.display import HTML, display
+                display(HTML(result))
+
+
+def load_ipython_extension(ipython):
+    """Load the extension in IPython/Jupyter.
+
+    Usage::
+
+        %load_ext jupyter_python_tutor
+    """
+    ipython.register_magics(TutorMagics)
+
+
+def unload_ipython_extension(ipython):
+    """Unload the extension."""
+    if "tutor" in ipython.magics_manager.magics["cell"]:
+        ipython.magics_manager.magics["cell"].pop("tutor", None)