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

jupyter_python_tutor-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+jupyter_python_tutor/__init__.py,sha256=wUrbX9qkGSp-sJjUEF5bvevIBpWB2Mx7ixEzyg4_VFI,373
+jupyter_python_tutor/magics.py,sha256=5U-IIVMqRgiBKiVDMPh5kwuo3wovZVj__M3W7bJ3yWc,3718
+jupyter_python_tutor/renderer.py,sha256=GOnPKKWN-EPnawk2BsF26ONfE_zEzRIApa5hGv6pPds,33920
+jupyter_python_tutor/tracer.py,sha256=LXe2Kwk8fCi5AOYAsDenEMcehJ4Uux0y6aq5U82-FQk,23271
+jupyter_python_tutor-0.2.0.dist-info/licenses/LICENSE,sha256=l2oOhGEO85UPMUiHAgK3C4t3OP8J2KMTQ5FuKFwSVmg,1065
+jupyter_python_tutor-0.2.0.dist-info/METADATA,sha256=R9NdMV-YAjnFuakzTpIJ7FWrtxSHLPwgwHRv62qgZ0A,5268
+jupyter_python_tutor-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+jupyter_python_tutor-0.2.0.dist-info/top_level.txt,sha256=e4mne6ggtOeo_pmq5fKZ6crLqXsUq-d0MR83Ir9JvGQ,21
+jupyter_python_tutor-0.2.0.dist-info/RECORD,,

jupyter_python_tutor-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

jupyter_python_tutor-0.2.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+jupyter_python_tutor