memory-graph 0.3.66__tar.gz → 0.3.68__tar.gz

{memory_graph-0.3.66 → memory_graph-0.3.68}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memory_graph
-Version: 0.3.66
+Version: 0.3.68
 Summary: Teaching tool and debugging aid in context of references, mutable data types, and shallow and deep copy.
 Author-email: Bas Terwijn <bterwijn@gmail.com>
 License-Expression: BSD-2-Clause
@@ -176,7 +176,7 @@ ___
 # Python Data Model #
 Learn the right **mental model** to think about Python data. The [Python Data Model](https://docs.python.org/3/reference/datamodel.html) makes a distiction between immutable and mutable types:
 
-* **immutable**: bool, int, float, complex, str, tuple, bytes, frozenset
+* **immutable**: bool, int, float, complex, str, tuple, frozenset, frozendict, bytes
 * **mutable**: list, set, dict, classes, ... (most other types)
 
 
@@ -500,6 +500,7 @@ The ```mg.stack()``` doesn't work well in **watch** context in most debuggers be
 |:---|:---|
 | [pdb](https://docs.python.org/3/library/pdb.html), [pudb](https://pypi.org/project/pudb/) | `mg.stack_pdb()` |
 | [Visual Studio Code](https://code.visualstudio.com/docs/languages/python) | `mg.stack_vscode()` |
+| [Jupyter Notebooks in VS Code](https://code.visualstudio.com/docs/datascience/jupyter-notebooks) | `mg.stack_vscode_jupyter()` |
 | [Cursor AI](https://www.cursor.com/) | `mg.stack_cursor()` |
 | [PyCharm](https://www.jetbrains.com/pycharm/) | `mg.stack_pycharm()` |
 | [Wing](https://wingware.com/) | `mg.stack_wing()` |
@@ -556,6 +557,48 @@ and pressing &lt;Enter&gt; a number of times, results in:
 
 ![debugging.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/debugging.gif)
 
+## Debugging using Exceptions ##
+
+To get the call stack at the point where exception `e` was thrown use `mg.stack_exception(e)`. This allows you to graph the trace back for easier debugging, for example:
+
+``` python
+import memory_graph as mg
+import traceback;
+
+def fun3():
+    d = [0] * 3
+    for i in range(4):
+        d[i] = i  # throws IndexError when i = 3
+    
+def fun2():
+    fun3()
+    
+def fun1():
+    fun2()
+
+try:
+    fun1()
+except Exception as e:
+    traceback.print_exc()           # print trace back
+    mg.show(mg.stack_exception(e))  # graph trace back
+```
+```
+$ python exception_example.py
+Traceback (most recent call last):
+  File "exception_example.py", line 16, in <module>
+    fun1()
+  File "exception_example.py", line 13, in fun1
+    fun2()
+  File "exception_example.py", line 10, in fun2
+    fun3()
+  File "exception_example.py", line 7, in fun3
+    d[i] = i  # throws IndexError when i = 3
+    ~^^^
+IndexError: list assignment index out of range
+```
+![exception_example.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/exception_example.png)
+
+
 # Data Structure Examples #
 Package memory_graph can **visualize the structure of your data** to easily understand and debug data structures, some examples:
 
@@ -695,6 +738,8 @@ Visualization of different sorting algorithms in Memory Graph Web Debugger.
 - [insertion sort](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/insertion_sort.py&breakpoints=13,29&continues=1&timestep=0.2&play)
 - [bubble sort](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/bubble_sort.py&breakpoints=29,38&continues=1&timestep=0.2&play)
 - [cocktail shaker sort](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/cocktail_sort.py&breakpoints=16,45&continues=1&timestep=0.2&play)
+- [bucket sort](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/bucket_sort.py&timestep=0.2&play)
+- [radix sort](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/radix_sort.py&timestep=0.2&play)
 
 
 # Bitwise Operators #
@@ -709,7 +754,7 @@ In this configuration example we show the decimal, binary and [two's complement
 
 A sliding puzzle solver as a challenging example showing how memory_graph deals with large amounts of data. Click "Continue" to step through the breadth-first search generations until a solution path is found:
 
-- [sliding puzzle solver](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/sliding_puzzle.py&breakpoints=17,27,29,40&continues=1)
+- [sliding puzzle solver](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/sliding_puzzle.py&breakpoints=16,26,28,39&continues=1)
 
 ![sliding_puzzle.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/sliding_puzzle.png)
 
@@ -1049,7 +1094,7 @@ import memory_graph as mg
 
 data = []
 x = ['x']
-for i in range(20):
+for i in range(35):
     data.append(x)
 
 mg.show(locals())

{memory_graph-0.3.66 → memory_graph-0.3.68}/README.md

@@ -156,7 +156,7 @@ ___
 # Python Data Model #
 Learn the right **mental model** to think about Python data. The [Python Data Model](https://docs.python.org/3/reference/datamodel.html) makes a distiction between immutable and mutable types:
 
-* **immutable**: bool, int, float, complex, str, tuple, bytes, frozenset
+* **immutable**: bool, int, float, complex, str, tuple, frozenset, frozendict, bytes
 * **mutable**: list, set, dict, classes, ... (most other types)
 
 
@@ -480,6 +480,7 @@ The ```mg.stack()``` doesn't work well in **watch** context in most debuggers be
 |:---|:---|
 | [pdb](https://docs.python.org/3/library/pdb.html), [pudb](https://pypi.org/project/pudb/) | `mg.stack_pdb()` |
 | [Visual Studio Code](https://code.visualstudio.com/docs/languages/python) | `mg.stack_vscode()` |
+| [Jupyter Notebooks in VS Code](https://code.visualstudio.com/docs/datascience/jupyter-notebooks) | `mg.stack_vscode_jupyter()` |
 | [Cursor AI](https://www.cursor.com/) | `mg.stack_cursor()` |
 | [PyCharm](https://www.jetbrains.com/pycharm/) | `mg.stack_pycharm()` |
 | [Wing](https://wingware.com/) | `mg.stack_wing()` |
@@ -536,6 +537,48 @@ and pressing <Enter> a number of times, results in:
 
 ![debugging.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/debugging.gif)
 
+## Debugging using Exceptions ##
+
+To get the call stack at the point where exception `e` was thrown use `mg.stack_exception(e)`. This allows you to graph the trace back for easier debugging, for example:
+
+``` python
+import memory_graph as mg
+import traceback;
+
+def fun3():
+    d = [0] * 3
+    for i in range(4):
+        d[i] = i  # throws IndexError when i = 3
+    
+def fun2():
+    fun3()
+    
+def fun1():
+    fun2()
+
+try:
+    fun1()
+except Exception as e:
+    traceback.print_exc()           # print trace back
+    mg.show(mg.stack_exception(e))  # graph trace back
+```
+```
+$ python exception_example.py
+Traceback (most recent call last):
+  File "exception_example.py", line 16, in <module>
+    fun1()
+  File "exception_example.py", line 13, in fun1
+    fun2()
+  File "exception_example.py", line 10, in fun2
+    fun3()
+  File "exception_example.py", line 7, in fun3
+    d[i] = i  # throws IndexError when i = 3
+    ~^^^
+IndexError: list assignment index out of range
+```
+![exception_example.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/exception_example.png)
+
+
 # Data Structure Examples #
 Package memory_graph can **visualize the structure of your data** to easily understand and debug data structures, some examples:
 
@@ -675,6 +718,8 @@ Visualization of different sorting algorithms in Memory Graph Web Debugger.
 - [insertion sort](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/insertion_sort.py&breakpoints=13,29&continues=1&timestep=0.2&play)
 - [bubble sort](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/bubble_sort.py&breakpoints=29,38&continues=1&timestep=0.2&play)
 - [cocktail shaker sort](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/cocktail_sort.py&breakpoints=16,45&continues=1&timestep=0.2&play)
+- [bucket sort](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/bucket_sort.py&timestep=0.2&play)
+- [radix sort](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/radix_sort.py&timestep=0.2&play)
 
 
 # Bitwise Operators #
@@ -689,7 +734,7 @@ In this configuration example we show the decimal, binary and [two's complement
 
 A sliding puzzle solver as a challenging example showing how memory_graph deals with large amounts of data. Click "Continue" to step through the breadth-first search generations until a solution path is found:
 
-- [sliding puzzle solver](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/sliding_puzzle.py&breakpoints=17,27,29,40&continues=1)
+- [sliding puzzle solver](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/sliding_puzzle.py&breakpoints=16,26,28,39&continues=1)
 
 ![sliding_puzzle.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/sliding_puzzle.png)
 
@@ -1029,7 +1074,7 @@ import memory_graph as mg
 
 data = []
 x = ['x']
-for i in range(20):
+for i in range(35):
     data.append(x)
 
 mg.show(locals())

{memory_graph-0.3.66 → memory_graph-0.3.68}/memory_graph/__init__.py

@@ -2,7 +2,7 @@
 # Copyright (c) 2023, Bas Terwijn.
 # SPDX-License-Identifier: BSD-2-Clause
 
-__version__ = "0.3.66"
+__version__ = "0.3.68"
 __author__ = 'Bas Terwijn'
 
 import memory_graph.memory_to_nodes as memory_to_nodes
@@ -13,6 +13,7 @@ import memory_graph.utils as utils
 import inspect
 import sys
 import itertools as it
+import types
 from memory_graph.call_stack import call_stack
 
 import graphviz
@@ -241,9 +242,63 @@ def stack_slice(begin_functions : List[Tuple[str, int]] = [],
     end_index = stack_end_index(stack_functions, begin_index, end_functions)
     return stack_frames_to_dict(reversed(frameInfos[begin_index+stack_index:end_index+1]))
 
+def stack_multi_slice(drop_functions : List[Tuple[str, int]] = [],
+                      end_functions : List[str] = ["<module>"],
+                      stack_index : int = 0,
+                      frameInfos : List[inspect.FrameInfo] = None,
+                      ignore_frame_condition = None):
+    """
+    Returns a slice of the call stack, dropping all occurrences of the specified drop_functions.
+    Parameters:
+      drop_functions - list of (function-name, offset), drops all matching 'function-name' frames
+                       including 'offset' number of parent frames for each match.
+      end_functions - list of function-names, ends at the index of the first 'function-name'
+                      that is found in the call stack after stack index (inclusive),
+                      otherwise ends at the last index
+      stack_index - number of frames removed from the beginning
+      ignore_frame_condition - optional callable that takes an inspect.FrameInfo and returns True if the frame should be dropped
+    """
+    if frameInfos is None:
+        frameInfos = inspect.stack()
+    
+    stack_functions = [s.function for s in frameInfos]
+    
+    # establish where to start (skipping innermost debugger eval frames)
+    begin_index = stack_begin_index(stack_functions, drop_functions)
+    if begin_index == 0:
+        begin_index += stack_index
+        
+    end_index = stack_end_index(stack_functions, begin_index, end_functions)
+    
+    drop_indices = set()
+    for drop_func, offset in drop_functions:
+        for i, func in enumerate(stack_functions[begin_index:end_index+1]):
+            actual_i = i + begin_index
+            if func == drop_func:
+                for j in range(actual_i, actual_i + offset):
+                    drop_indices.add(j)
+                    
+    if ignore_frame_condition:
+        for i in range(begin_index, end_index + 1):
+            if i not in drop_indices and ignore_frame_condition(frameInfos[i]):
+                drop_indices.add(i)
+    
+    filtered_frames = [frameInfos[i] for i in range(begin_index, end_index + 1) if i not in drop_indices]
+    
+    return stack_frames_to_dict(reversed(filtered_frames))
+
 def stack(end_functions=["<module>"], stack_index=0):
     return stack_slice([], end_functions, stack_index+2)
 
+def stack_exception(exception):
+    """ Get the call stack at the point 'exception' was thrown. """
+    tb = exception.__traceback__
+    frame_infos = []
+    while tb is not None:
+        frame_infos.append(types.SimpleNamespace(frame=tb.tb_frame))
+        tb = tb.tb_next
+    return stack_frames_to_dict(frame_infos)
+
 def stack_pdb(begin_functions=[("trace_dispatch",1)],
               end_functions=["<module>"],
               stack_index=0):
@@ -275,6 +330,56 @@ def stack_wing(begin_functions=[("_py_line_event",1), ("_py_return_event",1)],
     return stack_slice(begin_functions, end_functions, stack_index)
 
 
+banned_vscode_jupyter_strings = ['pydevd', 'debugpy', 'ipython', 'ipykernel', 'asyncio', 'tornado', 'traitlets', 'runpy']
+
+def is_vscode_jupyter_banned(frameInfo):
+    module_name = frameInfo.frame.f_globals.get('__name__', '')
+    filename = frameInfo.filename
+    func_name = frameInfo.function
+    
+    module_name_lower = module_name.lower()
+    func_name_lower = func_name.lower()
+    filename_lower = filename.lower()
+    
+    # Exempt user notebook/cell code from being banned.
+    if module_name == '__main__' or filename_lower.startswith('<ipython-input'):
+        return False
+    
+    for b in banned_vscode_jupyter_strings:
+        if b in module_name_lower or b in func_name_lower or b in filename_lower:
+            return True
+            
+    return False
+
+def stack_vscode_jupyter(drop_functions=[("trace_dispatch",1), ("_line_event",1), ("_return_event",1), ("do_wait_suspend",1), ("_do_wait_suspend",2)],
+                         end_functions=["<module>"],
+                         stack_index=0):
+    """ Get the call stack natively in a 'vscode' debugging 'jupyter' notebook session, 
+    filtering out the noisy environment specific functions and modules that pollute the graph. """
+    # stack_index + 2 to account for stack_vscode_jupyter and stack_multi_slice
+    call_stack_dict = stack_multi_slice(drop_functions, end_functions, stack_index + 2, ignore_frame_condition=is_vscode_jupyter_banned)
+    
+    for level_key, local_dict in call_stack_dict.items():
+        if '__pydevd_ret_val_dict' in local_dict:
+            ret_vals = local_dict.pop('__pydevd_ret_val_dict')
+            if isinstance(ret_vals, dict):
+                for k, v in ret_vals.items():
+                    # filter out Jupyter internal return values, particularly I/O stream writes
+                    if not any(b in k.lower() for b in banned_vscode_jupyter_strings) and 'write' not in k.lower():
+                        # Place return value in the function's own frame if it is still on the stack
+                        target_dict = local_dict
+                        for l_key, l_dict in call_stack_dict.items():
+                            if ": " in l_key and l_key.split(": ", 1)[1] == k:
+                                target_dict = l_dict
+                                break
+                        target_dict[f"<return> {k}"] = v
+        
+        if "<module>" in level_key:
+            call_stack_dict[level_key] = jupyter_locals_filter(local_dict)
+
+    return call_stack_dict
+
+
 def save_call_stack(filename):
     """ Saves the call stack to 'filename' for inspection to see what functions need to be 
     filtered out to create the desired graph. """
@@ -310,6 +415,12 @@ def wing(filename=None, data=None):
         data = stack_wing()
     render(data, filename)
 
+def vscode_jupyter(filename=None, data=None):
+    if data is None:
+        # stack_index=1 since this function counts as an extra stack frame
+        data = stack_vscode_jupyter(stack_index=1)
+    render(data, filename)
+
 def locals_filter(locals, keys):
     """ Filter out the jupyter specific keys that polute the graph. """
     return {k:v for k,v in utils.filter_dict(jupyter_locals)

{memory_graph-0.3.66 → memory_graph-0.3.68}/memory_graph.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memory_graph
-Version: 0.3.66
+Version: 0.3.68
 Summary: Teaching tool and debugging aid in context of references, mutable data types, and shallow and deep copy.
 Author-email: Bas Terwijn <bterwijn@gmail.com>
 License-Expression: BSD-2-Clause
@@ -176,7 +176,7 @@ ___
 # Python Data Model #
 Learn the right **mental model** to think about Python data. The [Python Data Model](https://docs.python.org/3/reference/datamodel.html) makes a distiction between immutable and mutable types:
 
-* **immutable**: bool, int, float, complex, str, tuple, bytes, frozenset
+* **immutable**: bool, int, float, complex, str, tuple, frozenset, frozendict, bytes
 * **mutable**: list, set, dict, classes, ... (most other types)
 
 
@@ -500,6 +500,7 @@ The ```mg.stack()``` doesn't work well in **watch** context in most debuggers be
 |:---|:---|
 | [pdb](https://docs.python.org/3/library/pdb.html), [pudb](https://pypi.org/project/pudb/) | `mg.stack_pdb()` |
 | [Visual Studio Code](https://code.visualstudio.com/docs/languages/python) | `mg.stack_vscode()` |
+| [Jupyter Notebooks in VS Code](https://code.visualstudio.com/docs/datascience/jupyter-notebooks) | `mg.stack_vscode_jupyter()` |
 | [Cursor AI](https://www.cursor.com/) | `mg.stack_cursor()` |
 | [PyCharm](https://www.jetbrains.com/pycharm/) | `mg.stack_pycharm()` |
 | [Wing](https://wingware.com/) | `mg.stack_wing()` |
@@ -556,6 +557,48 @@ and pressing &lt;Enter&gt; a number of times, results in:
 
 ![debugging.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/debugging.gif)
 
+## Debugging using Exceptions ##
+
+To get the call stack at the point where exception `e` was thrown use `mg.stack_exception(e)`. This allows you to graph the trace back for easier debugging, for example:
+
+``` python
+import memory_graph as mg
+import traceback;
+
+def fun3():
+    d = [0] * 3
+    for i in range(4):
+        d[i] = i  # throws IndexError when i = 3
+    
+def fun2():
+    fun3()
+    
+def fun1():
+    fun2()
+
+try:
+    fun1()
+except Exception as e:
+    traceback.print_exc()           # print trace back
+    mg.show(mg.stack_exception(e))  # graph trace back
+```
+```
+$ python exception_example.py
+Traceback (most recent call last):
+  File "exception_example.py", line 16, in <module>
+    fun1()
+  File "exception_example.py", line 13, in fun1
+    fun2()
+  File "exception_example.py", line 10, in fun2
+    fun3()
+  File "exception_example.py", line 7, in fun3
+    d[i] = i  # throws IndexError when i = 3
+    ~^^^
+IndexError: list assignment index out of range
+```
+![exception_example.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/exception_example.png)
+
+
 # Data Structure Examples #
 Package memory_graph can **visualize the structure of your data** to easily understand and debug data structures, some examples:
 
@@ -695,6 +738,8 @@ Visualization of different sorting algorithms in Memory Graph Web Debugger.
 - [insertion sort](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/insertion_sort.py&breakpoints=13,29&continues=1&timestep=0.2&play)
 - [bubble sort](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/bubble_sort.py&breakpoints=29,38&continues=1&timestep=0.2&play)
 - [cocktail shaker sort](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/cocktail_sort.py&breakpoints=16,45&continues=1&timestep=0.2&play)
+- [bucket sort](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/bucket_sort.py&timestep=0.2&play)
+- [radix sort](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/radix_sort.py&timestep=0.2&play)
 
 
 # Bitwise Operators #
@@ -709,7 +754,7 @@ In this configuration example we show the decimal, binary and [two's complement
 
 A sliding puzzle solver as a challenging example showing how memory_graph deals with large amounts of data. Click "Continue" to step through the breadth-first search generations until a solution path is found:
 
-- [sliding puzzle solver](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/sliding_puzzle.py&breakpoints=17,27,29,40&continues=1)
+- [sliding puzzle solver](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/sliding_puzzle.py&breakpoints=16,26,28,39&continues=1)
 
 ![sliding_puzzle.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/sliding_puzzle.png)
 
@@ -1049,7 +1094,7 @@ import memory_graph as mg
 
 data = []
 x = ['x']
-for i in range(20):
+for i in range(35):
     data.append(x)
 
 mg.show(locals())

{memory_graph-0.3.66 → memory_graph-0.3.68}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "memory_graph"
-version = "0.3.66"
+version = "0.3.68"
 description = "Teaching tool and debugging aid in context of references, mutable data types, and shallow and deep copy."
 authors = [
     {name = "Bas Terwijn", email = "bterwijn@gmail.com"}