jupyter-python-tutor 0.2.0__tar.gz

jupyter_python_tutor-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dive4dec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jupyter_python_tutor-0.2.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: jupyter-python-tutor
+Version: 0.2.0
+Summary: Python Tutor-style step-by-step code visualization for JupyterLab 4.x and Notebook 7
+Author: dive4dec
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dive4dec/jupyter-python-tutor
+Project-URL: Repository, https://github.com/dive4dec/jupyter-python-tutor
+Project-URL: Issues, https://github.com/dive4dec/jupyter-python-tutor/issues
+Project-URL: Changelog, https://github.com/dive4dec/jupyter-python-tutor/blob/main/CHANGELOG.md
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ipython>=8.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# jupyter-python-tutor
+
+Python Tutor–style step-by-step code visualization directly inside JupyterLab 4.x and Notebook 7 cells.
+
+## Quick Start
+
+```bash
+pip install jupyter-python-tutor
+```
+
+In a Jupyter cell:
+
+```python
+%load_ext jupyter_python_tutor
+```
+
+Then use the `%%tutor` cell magic:
+
+```python
+%%tutor
+x = 3
+y = x + 4
+print(y)
+```
+
+An interactive trace appears below the cell — drag the slider to navigate
+through execution, see variable values change at each line, with SVG arrows
+from frame variables to heap objects (like [Python Tutor](https://pythontutor.com)).
+
+## Features
+
+- **Interactive slider navigation** — drag the slider (or use ◀ ▶ buttons / ← → arrow keys) to scrub through execution steps
+- **SVG pointer arrows** — arrows from frame variables to heap objects, like OPT_Mentor / Python Tutor
+- **Single-step view** — only the current step is shown (not all steps stacked)
+- **Call stack visualization** — global frame + local frames with line numbers
+- **Heap objects** — lists, dicts, class instances, functions, and other objects shown as boxes with arrows pointing to them
+- **Resizable columns** — drag the vertical dividers between code / variables / objects to resize; double-click a divider to collapse/expand
+- **Auto-height** — iframe height follows the tallest column content (no fixed height, no internal scroll)
+- **AST-based variable filtering** — only variables used by the traced code are shown (no IPython internals, no contamination from other cells)
+- **stdout capture** — `print()` output is displayed per step
+- **functools.wraps-safe** — functions show their true name (`__code__.co_name`), not the wrapper's `__name__`
+- **Trusted notebook support** — renders fully (with JS, CSS, arrows) in trusted notebooks; `jupyter trust notebook.ipynb` after execution
+- **Works with Notebook 7** — compatible with the new Jupyter Notebook 7 (JupyterLab-based)
+- **Pure Python** — no compiled extensions, works in CPython 3.8+
+
+## Options
+
+```
+%%tutor --max-steps 1000   # Limit trace steps (default: 5000)
+%%tutor --raw              # Output trace as JSON instead of HTML
+%%tutor --height 400       # Set minimum widget height (default: 500)
+```
+
+## Examples
+
+### Loops
+
+```python
+%%tutor
+total = 0
+for i in range(5):
+    total += i
+print(f"Sum: {total}")
+```
+
+### Functions with recursion
+
+```python
+%%tutor
+def factorial(n):
+    if n <= 1:
+        return 1
+    return n * factorial(n - 1)
+
+result = factorial(4)
+print(result)
+```
+
+### Classes and inheritance
+
+```python
+%%tutor
+class Animal:
+    def __init__(self, name):
+        self.name = name
+    def speak(self):
+        return f"{self.name} says hello"
+
+class Dog(Animal):
+    def speak(self):
+        return f"{self.name} barks"
+
+d = Dog("Rex")
+print(d.speak())
+```
+
+## How It Works
+
+1. **Tracing**: The `%%tutor` magic compiles the cell code and executes it under
+   `sys.settrace()`. At each line/call/return event, a snapshot of all local and
+   global variables is captured. AST analysis (`ast.parse`) extracts the set of
+   names the traced code touches, so only code-relevant variables are shown
+   (filtering out IPython internals and variables from other cells).
+
+2. **Rendering**: The trace steps are rendered as a complete HTML page inside
+   an `<iframe srcdoc="...">`. This bypasses JupyterLab 4's HTML sanitizer
+   (which strips `<script>`, `<style>`, `<button>`, `<input>`, etc. from
+   untrusted output). In trusted notebooks, the iframe renders with full
+   CSS + JavaScript — enabling slider navigation, SVG arrows, draggable
+   dividers, and auto-height.
+
+3. **Arrows**: SVG paths are computed at render time from the bounding boxes
+   of pointer boxes (in frame variables) to heap objects. Arrows redraw on
+   slider navigation, column resize, and window resize.
+
+4. **JupyterLab 4 compatibility**: JupyterLab 4's HTML sanitizer (DOMPurify)
+   strips JavaScript and external URLs from untrusted notebooks. The iframe
+   `srcdoc` approach bypasses this entirely in trusted notebooks. Run
+   `jupyter trust your_notebook.ipynb` after executing cells with `%%tutor`
+   to ensure the visualization renders correctly.
+
+## Limitations
+
+- **Trusted notebooks required** for full rendering (arrows, slider, dividers).
+  Untrusted notebooks will show a stripped-down version.
+- `sys.settrace()` adds overhead — very long loops will be slow; use `--max-steps` to limit
+- Threads are not traced (only the main thread)
+
+## License
+
+MIT

jupyter_python_tutor-0.2.0/README.md

@@ -0,0 +1,131 @@
+# jupyter-python-tutor
+
+Python Tutor–style step-by-step code visualization directly inside JupyterLab 4.x and Notebook 7 cells.
+
+## Quick Start
+
+```bash
+pip install jupyter-python-tutor
+```
+
+In a Jupyter cell:
+
+```python
+%load_ext jupyter_python_tutor
+```
+
+Then use the `%%tutor` cell magic:
+
+```python
+%%tutor
+x = 3
+y = x + 4
+print(y)
+```
+
+An interactive trace appears below the cell — drag the slider to navigate
+through execution, see variable values change at each line, with SVG arrows
+from frame variables to heap objects (like [Python Tutor](https://pythontutor.com)).
+
+## Features
+
+- **Interactive slider navigation** — drag the slider (or use ◀ ▶ buttons / ← → arrow keys) to scrub through execution steps
+- **SVG pointer arrows** — arrows from frame variables to heap objects, like OPT_Mentor / Python Tutor
+- **Single-step view** — only the current step is shown (not all steps stacked)
+- **Call stack visualization** — global frame + local frames with line numbers
+- **Heap objects** — lists, dicts, class instances, functions, and other objects shown as boxes with arrows pointing to them
+- **Resizable columns** — drag the vertical dividers between code / variables / objects to resize; double-click a divider to collapse/expand
+- **Auto-height** — iframe height follows the tallest column content (no fixed height, no internal scroll)
+- **AST-based variable filtering** — only variables used by the traced code are shown (no IPython internals, no contamination from other cells)
+- **stdout capture** — `print()` output is displayed per step
+- **functools.wraps-safe** — functions show their true name (`__code__.co_name`), not the wrapper's `__name__`
+- **Trusted notebook support** — renders fully (with JS, CSS, arrows) in trusted notebooks; `jupyter trust notebook.ipynb` after execution
+- **Works with Notebook 7** — compatible with the new Jupyter Notebook 7 (JupyterLab-based)
+- **Pure Python** — no compiled extensions, works in CPython 3.8+
+
+## Options
+
+```
+%%tutor --max-steps 1000   # Limit trace steps (default: 5000)
+%%tutor --raw              # Output trace as JSON instead of HTML
+%%tutor --height 400       # Set minimum widget height (default: 500)
+```
+
+## Examples
+
+### Loops
+
+```python
+%%tutor
+total = 0
+for i in range(5):
+    total += i
+print(f"Sum: {total}")
+```
+
+### Functions with recursion
+
+```python
+%%tutor
+def factorial(n):
+    if n <= 1:
+        return 1
+    return n * factorial(n - 1)
+
+result = factorial(4)
+print(result)
+```
+
+### Classes and inheritance
+
+```python
+%%tutor
+class Animal:
+    def __init__(self, name):
+        self.name = name
+    def speak(self):
+        return f"{self.name} says hello"
+
+class Dog(Animal):
+    def speak(self):
+        return f"{self.name} barks"
+
+d = Dog("Rex")
+print(d.speak())
+```
+
+## How It Works
+
+1. **Tracing**: The `%%tutor` magic compiles the cell code and executes it under
+   `sys.settrace()`. At each line/call/return event, a snapshot of all local and
+   global variables is captured. AST analysis (`ast.parse`) extracts the set of
+   names the traced code touches, so only code-relevant variables are shown
+   (filtering out IPython internals and variables from other cells).
+
+2. **Rendering**: The trace steps are rendered as a complete HTML page inside
+   an `<iframe srcdoc="...">`. This bypasses JupyterLab 4's HTML sanitizer
+   (which strips `<script>`, `<style>`, `<button>`, `<input>`, etc. from
+   untrusted output). In trusted notebooks, the iframe renders with full
+   CSS + JavaScript — enabling slider navigation, SVG arrows, draggable
+   dividers, and auto-height.
+
+3. **Arrows**: SVG paths are computed at render time from the bounding boxes
+   of pointer boxes (in frame variables) to heap objects. Arrows redraw on
+   slider navigation, column resize, and window resize.
+
+4. **JupyterLab 4 compatibility**: JupyterLab 4's HTML sanitizer (DOMPurify)
+   strips JavaScript and external URLs from untrusted notebooks. The iframe
+   `srcdoc` approach bypasses this entirely in trusted notebooks. Run
+   `jupyter trust your_notebook.ipynb` after executing cells with `%%tutor`
+   to ensure the visualization renders correctly.
+
+## Limitations
+
+- **Trusted notebooks required** for full rendering (arrows, slider, dividers).
+  Untrusted notebooks will show a stripped-down version.
+- `sys.settrace()` adds overhead — very long loops will be slow; use `--max-steps` to limit
+- Threads are not traced (only the main thread)
+
+## License
+
+MIT

jupyter_python_tutor-0.2.0/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-0.2.0/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)