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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jupyter-python-tutor
-Version: 0.3.3
+Version: 0.3.4
 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.3 → jupyter_python_tutor-0.3.4}/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.3"
+__version__ = "0.3.4"
 
 __all__ = ["trace_code", "render_trace", "load_ipython_extension"]

{jupyter_python_tutor-0.3.3 → jupyter_python_tutor-0.3.4}/jupyter_python_tutor/magics.py

@@ -12,20 +12,31 @@ Options:
     %%pytutor --raw              — output the trace as JSON instead of HTML
     %%pytutor --height 400       — set max-height of the variables panel (px)
     %%pytutor --input 2026       — pre-collected input for input() calls
+    %%pytutor --no-scroll        — window fits all content (no inner scrollbars)
+
+Configure scrolling for the entire notebook:
+
+    %pytutor_config --no-scroll   # default to fit-all (no inner scroll)
+    %pytutor_config --scroll      # default to fixed window with inner scroll
+    %pytutor_config --reset       # back to defaults
+    %pytutor_config               # show current settings
 """
 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 IPython.core.magic import Magics, magics_class, cell_magic, line_magic
+from IPython.display import HTML, JSON, display
 
 from .tracer import trace_code
 from .renderer import render_trace
 
 __all__ = ["TutorMagics", "load_ipython_extension", "unload_ipython_extension"]
 
+# Defaults
+_DEFAULT_SCROLL = True
+
 
 def _make_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
@@ -50,19 +61,78 @@ def _make_parser() -> argparse.ArgumentParser:
              "Repeat --input for multiple values: --input 2026 --input John. "
              "If omitted and code contains input(), a dialog prompts for values.",
     )
+    parser.add_argument(
+        "--no-scroll", dest="no_scroll", action="store_true",
+        help="Fit-all for this cell: window grows to show all content, no inner scroll",
+    )
+    parser.add_argument(
+        "--scroll", dest="use_scroll", action="store_true",
+        help="Fixed window with inner scroll for this cell (overrides --no-scroll config)",
+    )
     return parser
 
 
 @magics_class
 class TutorMagics(Magics):
-    """Register the %%pytutor cell magic."""
+    """Register the %%pytutor cell magic and %pytutor_config line magic."""
+
+    def __init__(self, shell):
+        super().__init__(shell)
+        # Per-notebook config stored on the magics instance.
+        self._scroll = _DEFAULT_SCROLL
+
+    # ── %pytutor_config ──────────────────────────────────────────────
+
+    @line_magic("pytutor_config")
+    def pytutor_config(self, line: str):
+        """Configure how %%pytutor visualizations behave for this notebook.
+
+        Examples::
+
+            %pytutor_config --no-scroll   # default to fit-all (no inner scroll)
+            %pytutor_config --scroll      # default to fixed window with inner scroll
+            %pytutor_config --reset       # back to defaults
+            %pytutor_config               # show current settings
+        """
+        parser = argparse.ArgumentParser(prog="%pytutor_config", add_help=False)
+        parser.add_argument("--no-scroll", dest="no_scroll", action="store_true",
+                            help="Default to fit-all: window grows to show all content, no inner scroll")
+        parser.add_argument("--scroll", dest="use_scroll", action="store_true",
+                            help="Default to fixed window with inner scroll (the default)")
+        parser.add_argument("--reset", action="store_true",
+                            help="Reset all settings to defaults")
+        try:
+            args = parser.parse_known_args(line.split() if line else [])[0]
+        except SystemExit:
+            return
+
+        if args.reset:
+            self._scroll = _DEFAULT_SCROLL
+            display(HTML("<p>pytutor config reset to defaults.</p>"))
+            return
+
+        # --no-scroll / --scroll are both store_true; --no-scroll wins if both given.
+        if args.no_scroll:
+            self._scroll = False
+        elif args.use_scroll:
+            self._scroll = True
+
+        # Show current settings
+        display(HTML(
+            "<table style='font-family:monospace;font-size:13px;'>"
+            f"<tr><td><b>Scrolling</b></td>"
+            f"<td>{'fixed window (inner scroll)' if self._scroll else 'fit-all (no inner scroll)'}</td></tr>"
+            "</table>"
+        ))
+
+    # ── %%pytutor ────────────────────────────────────────────────────
 
     @cell_magic("pytutor")
     def pytutor(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 [])
+            args, _unknown = parser.parse_known_args(line.split() if line else [])
         except SystemExit:
             return
 
@@ -87,6 +157,14 @@ class TutorMagics(Magics):
             inputs=inputs,
         )
 
+        # Scrolling: a cell flag wins; otherwise fall back to the notebook default.
+        if args.no_scroll:
+            scroll = False
+        elif args.use_scroll:
+            scroll = True
+        else:
+            scroll = self._scroll
+
         if args.raw:
             return JSON(steps)
         else:
@@ -96,7 +174,7 @@ class TutorMagics(Magics):
             # 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)
+            result = render_trace(steps, source_code=cell, height=args.height, scroll=scroll)
             import warnings
             with warnings.catch_warnings():
                 # Suppress IPython's "Consider using IFrame instead" warning —

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

@@ -42,10 +42,22 @@ import json
 __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."""
+def _generate_inner_html(
+    steps: list[dict], source_code: str, height: int = 500, scroll: bool = True
+) -> str:
+    """Generate the full HTML page that goes inside the iframe srcdoc.
+
+    ``scroll`` controls the initial scrolling mode:
+      - True (default): fixed-height window, the columns scroll internally.
+      - False: the window grows to fit ALL content (no inner scrollbars); the
+        parent page's auto-resize watcher stretches the iframe to match.
+    The mode can also be toggled at runtime via the "⤢ Fit all / ⇅ Scroll"
+    button in the navbar.
+    """
     if not steps:
         return '<!DOCTYPE html><html><body><p style="color:red;">No trace steps to display.</p></body></html>'
+    initial_scroll_js = "true" if scroll else "false"
+    widget_cls = "jpt-widget" if scroll else "jpt-widget no-scroll"
 
     # Determine source lines
     if source_code:
@@ -144,6 +156,13 @@ body {{
 }}
 .jpt-navbar button:hover {{ background: #f0f0f0; }}
 .jpt-navbar button:disabled {{ opacity: 0.4; cursor: default; }}
+.jpt-mode-btn {{
+  margin-left: auto;
+  font-weight: 600;
+  background: #fff;
+}}
+.jpt-mode-btn.active {{ background: #3b82f6; color: #fff; border-color: #2563eb; }}
+.jpt-mode-btn.active:hover {{ background: #2563eb; }}
 .jpt-slider {{
   flex: 1;
   min-width: 100px;
@@ -190,6 +209,24 @@ body {{
   overflow: hidden;
   min-height: 0;
 }}
+/* No-scroll ("fit all") mode: the widget grows to fit its full content and the
+   columns stop scrolling internally. The parent auto-resize watcher then
+   stretches the iframe to the new height. Placed after the base rules so it
+   wins the cascade. */
+.jpt-widget.no-scroll {{
+  height: auto !important;
+  min-height: 120px;
+}}
+.jpt-widget.no-scroll .jpt-main,
+.jpt-widget.no-scroll .jpt-right-panel {{
+  overflow: visible;
+  min-height: 0;
+}}
+.jpt-widget.no-scroll .jpt-code-section,
+.jpt-widget.no-scroll .jpt-frames-section,
+.jpt-widget.no-scroll .jpt-heap-section {{
+  overflow: visible;
+}}
 .jpt-code-section {{
   flex: 0 0 40%;
   min-width: 30px;
@@ -411,7 +448,7 @@ body {{
 </style>
 </head>
 <body>
-<div class="jpt-widget" id="jptWidget" style="height:{height}px;position:relative;">
+<div class="{widget_cls}" 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">
@@ -427,6 +464,7 @@ body {{
     <button id="btnNext" title="Next">▶</button>
     <button id="btnLast" title="Last">⏭</button>
     <span class="jpt-step-counter" id="stepCounter">Step 1 of {n_steps}</span>
+    <button id="btn-scroll-mode" class="jpt-mode-btn" title="Toggle scrolling: off = window fits all content (no inner scroll); on = fixed window with inner scroll">⇅ Scroll</button>
   </div>
   <div class="jpt-output-section">
     <div class="jpt-output-label">Program Output</div>
@@ -940,6 +978,33 @@ body {{
   divider1.addEventListener('dblclick', toggleCollapse(divider1, codeSection));
   divider2.addEventListener('dblclick', toggleCollapse(divider2, framesSection));
 
+  // ── Scroll mode (fixed window + inner scroll  ⇄  fit-all, no inner scroll) ──
+  // scrollMode true  = fixed-height window, columns scroll internally.
+  // scrollMode false = window grows to fit ALL content (no inner scrollbars);
+  // the parent page's auto-resize watcher stretches the iframe to match.
+  var scrollMode = {initial_scroll_js};
+  var scrollBtn = document.getElementById('btn-scroll-mode');
+  var jptWidgetEl = document.querySelector('.jpt-widget');
+  function applyScrollMode() {{
+    jptWidgetEl.classList.toggle('no-scroll', !scrollMode);
+    if (scrollMode) {{
+      scrollBtn.textContent = '⇅ Scroll';
+      scrollBtn.classList.remove('active');
+      scrollBtn.title = 'Scrolling ON: fixed window, columns scroll internally. Click to fit all content (no inner scroll).';
+    }} else {{
+      scrollBtn.textContent = '⤢ Fit all';
+      scrollBtn.classList.add('active');
+      scrollBtn.title = 'Scrolling OFF: window fits all content. Click to return to fixed window with inner scroll.';
+    }}
+    // Re-lay arrows once the box has settled at its new size.
+    requestAnimationFrame(function() {{ requestAnimationFrame(drawArrows); }});
+  }}
+  scrollBtn.onclick = function() {{
+    scrollMode = !scrollMode;
+    applyScrollMode();
+  }};
+  if (!scrollMode) {{ applyScrollMode(); }}
+
   // 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.
@@ -961,12 +1026,19 @@ def render_trace(
     steps: list[dict],
     source_code: str | None = None,
     height: int = 500,
+    scroll: bool = True,
 ) -> str:
     """Render trace steps as interactive HTML inside an iframe.
 
     The entire visualization (HTML + CSS + JS) is wrapped in
     ``<iframe srcdoc="...">`` which works in trusted JupyterLab notebooks.
 
+    ``height`` sets the fixed window height in *scrolling* mode. ``scroll``
+    sets the initial scrolling mode: ``True`` (default) = fixed window with
+    inner column scrollbars; ``False`` = the window grows to fit all content
+    (no inner scrollbars). Students can flip it at any time with the
+    "⤢ Fit all / ⇅ Scroll" button in the navbar.
+
     Features:
       - Fixed widget height with internal scrolling — no "dancing" cell
       - Slider navigation (``<input type="range">``) — drag to scrub through steps
@@ -977,7 +1049,7 @@ def render_trace(
       - Heap only shows objects reachable from the current call stack
       - Keyboard navigation (← → arrows)
     """
-    inner = _generate_inner_html(steps, source_code or "", height)
+    inner = _generate_inner_html(steps, source_code or "", height, scroll=scroll)
     # Escape for srcdoc attribute
     escaped = html.escape(inner, quote=True)
     # Match cpp-tutor's approach exactly to prevent "dancing":

{jupyter_python_tutor-0.3.3 → jupyter_python_tutor-0.3.4}/jupyter_python_tutor.egg-info/PKG-INFO

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

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

@@ -77,3 +77,55 @@ c = Circle('red', 5)
     def test_height_option(self, ipython):
         result = ipython.run_cell_magic("pytutor", "--height 500", "x = 3")
         assert result is None or hasattr(result, 'children') or "jpt" in str(result)
+
+
+class TestScrollModeMagic:
+    """Test the --no-scroll/--scroll cell flag and the %pytutor_config line magic."""
+
+    def _run_cell_capturing_scroll(self, ipython, line=""):
+        """Run %%pytutor with render_trace mocked; return the scroll kwarg passed."""
+        from unittest import mock
+        with mock.patch(
+            "jupyter_python_tutor.magics.render_trace",
+            return_value="<html></html>",
+        ) as mr:
+            ipython.run_cell_magic("pytutor", line, "x = 3")
+            assert mr.called, "render_trace was not called"
+            return mr.call_args.kwargs.get("scroll")
+
+    def test_config_magic_registered(self, ipython):
+        assert "pytutor_config" in ipython.magics_manager.magics["line"]
+
+    def test_default_scroll_true(self, ipython):
+        ipython.run_line_magic("pytutor_config", "--reset")
+        assert self._run_cell_capturing_scroll(ipython) is True
+
+    def test_cell_no_scroll_flag(self, ipython):
+        ipython.run_line_magic("pytutor_config", "--reset")
+        assert self._run_cell_capturing_scroll(ipython, line="--no-scroll") is False
+
+    def test_cell_scroll_overrides_config(self, ipython):
+        ipython.run_line_magic("pytutor_config", "--no-scroll")
+        # a cell --scroll wins over the notebook --no-scroll default
+        assert self._run_cell_capturing_scroll(ipython, line="--scroll") is True
+
+    def test_config_no_scroll(self, ipython):
+        ipython.run_line_magic("pytutor_config", "--no-scroll")
+        assert self._run_cell_capturing_scroll(ipython) is False
+
+    def test_config_scroll_restores(self, ipython):
+        ipython.run_line_magic("pytutor_config", "--no-scroll")
+        ipython.run_line_magic("pytutor_config", "--scroll")
+        assert self._run_cell_capturing_scroll(ipython) is True
+
+    def test_config_reset(self, ipython):
+        ipython.run_line_magic("pytutor_config", "--no-scroll")
+        ipython.run_line_magic("pytutor_config", "--reset")
+        assert self._run_cell_capturing_scroll(ipython) is True
+
+    def test_config_no_args_shows_setting(self, ipython):
+        ipython.run_line_magic("pytutor_config", "--no-scroll")
+        # running with no args displays the current setting (no exception)
+        ipython.run_line_magic("pytutor_config", "")
+        # and it is still no-scroll
+        assert self._run_cell_capturing_scroll(ipython) is False

{jupyter_python_tutor-0.3.3 → jupyter_python_tutor-0.3.4}/tests/test_renderer.py

@@ -416,3 +416,57 @@ class TestErrorDisplay:
         import json
         data = json.loads(jsline.strip()[len("var steps = "):-1])
         assert not any(s.get("error") for s in data)
+
+
+class TestScrollMode:
+    """Test the optional scrolling (fixed window  ⇄  fit-all) feature."""
+
+    def _inner(self, scroll: bool) -> str:
+        steps = trace_code("x = 1\ny = 2")
+        return _get_srcdoc_content(
+            render_trace(steps, source_code="x = 1\ny = 2", scroll=scroll)
+        )
+
+    def test_default_is_scroll_mode(self):
+        inner = _get_srcdoc_content(render_trace(trace_code("x = 1"), source_code="x = 1"))
+        # Default scroll=True: no 'no-scroll' class on the widget
+        assert 'class="jpt-widget no-scroll"' not in inner
+        assert "var scrollMode = true;" in inner
+
+    def test_no_scroll_mode_class(self):
+        inner = self._inner(False)
+        assert 'class="jpt-widget no-scroll"' in inner
+        assert "var scrollMode = false;" in inner
+
+    def test_no_scroll_css_present(self):
+        inner = self._inner(False)
+        assert ".jpt-widget.no-scroll" in inner
+        # columns stop scrolling in fit-all
+        assert ".jpt-widget.no-scroll .jpt-code-section" in inner
+
+    def test_mode_button_present(self):
+        inner = self._inner(False)
+        assert 'id="btn-scroll-mode"' in inner
+        assert "jpt-mode-btn" in inner
+
+    def test_mode_button_active_state_in_js(self):
+        inner = self._inner(False)
+        # applyScrollMode swaps label + active class
+        assert "applyScrollMode" in inner
+        assert "Fit all" in inner
+        assert "⇅ Scroll" in inner
+
+    def test_toggle_redraws_arrows(self):
+        inner = self._inner(False)
+        # fitting all changes layout, so arrows must be re-laid out
+        assert "requestAnimationFrame(drawArrows)" in inner
+
+
+class TestScrollParamSignature:
+    """render_trace / _generate_inner_html accept a scroll parameter."""
+
+    def test_render_trace_has_scroll_param(self):
+        import inspect
+        sig = inspect.signature(render_trace)
+        assert "scroll" in sig.parameters
+        assert sig.parameters["scroll"].default is True