!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:
Circular Doubly Linked List ##

class Linked_List: """ Circular doubly linked list """

def __init__(self, value=None, prev=None, next=None): self.prev = prev if prev else self self.value = value self.next = next if next else self

def add_back(self, value): if self.value == None: self.value = value else: new_node = Linked_List(value, prev=self.prev, next=self) self.prev.next = new_node self.prev = new_node

linked_list = Linked_List() n = 100 for i in range(n): value = random.randrange(n) linked_list.add_back(value) mg.block(mg.show, locals()) # <--- draw locals

!linked_list.png

Linked List in Cursor AI ###
Here we show values being added to a Linked List in Cursor AI. When adding the last value '5' we "Step Into" the code to show more of the details.
!linked_list.gif
Or see it in the Memory Graph Web Debugger.
Binary Tree ##

class BinTree:

def __init__(self, value=None, smaller=None, larger=None): self.smaller = smaller self.value = value self.larger = larger

def add(self, value): if self.value is None: self.value = value elif value < self.value: if self.smaller is None: self.smaller = BinTree(value) else: self.smaller.add(value) else: if self.larger is None: self.larger = BinTree(value) else: self.larger.add(value) mg.block(mg.show, mg.stack()) # <--- draw stack

tree = BinTree() n = 100 for i in range(n): value = random.randrange(n) tree.add(value)

!bin_tree.png

Binary Tree in Visual Studio Code ###
Here we show values being inserted in a Binary Tree in Visual Studio Code. When inserting the last value '29' we "Step Into" the code to show the recursive implementation.
!images/bin_tree.gif
See it in the Memory Graph Web Debugger or see the more advanced Multiway Tree with more than two children per node, making the tree less deep and more efficient.
Hash Set ##

class HashSet:

def __init__(self, capacity=15): self.buckets = [None] * capacity

def add(self, value): index = hash(value) % len(self.buckets) if self.buckets[index] is None: self.buckets[index] = [] bucket = self.buckets[index] bucket.append(value) mg.block(mg.show, locals()) # <--- draw locals

def contains(self, value): index = hash(value) % len(self.buckets) if self.buckets[index] is None: return False return value in self.buckets[index]

def remove(self, value): index = hash(value) % len(self.buckets) if self.buckets[index] is not None: self.buckets[index].remove(value) hash_set = HashSet() n = 100 for i in range(n): new_value = random.randrange(n) hash_set.add(new_value)

!hash_set.png

Hash Set in PyCharm ###
Here we show values being inserted in a HashSet in PyCharm. When inserting the last value '44' we "Step Into" the code to show more of the details.
!images/hash_set.gif
Or see it in the Memory Graph Web Debugger.
Sorting Algorithms #
Visualization of different sorting algorithms in Memory Graph Web Debugger.
!selections_sort.png
selection sort
insertion sort
bubble sort
cocktail shaker sort
bucket sort
radix sort
Bitwise Operators #
In this configuration example we show the decimal, binary and two's complement representation representation of int values of dictionary subclass Bits to show the result of bitwise operators. The ~ (inverse) operator can be a bit confusing if not shown with two's complement representation.
bitwise operators
!bitwise_operators.png
Sliding Puzzle Solver #
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
!sliding_puzzle.png
Flow Control #
Some examples where we focus more on the flow of execution in Python code.
Different Methods ##
This example shows the difference between 'instance', 'class' and 'static' methods:

# class variables: count = 0 unique_value = 0

def __init__(self): print("__init__ called, initialize instance variables of object") self.my_instance_variable = [] # create instance variable My_Class.count += 1 # also change class variable

def my_instance_method(self): print("my_instance_method called, access to instance variables via 'self'") self.my_instance_variable.append(My_Class.unique_value) My_Class.unique_value += 1 # also change class variable

@classmethod def my_class_method(cls): print("my_class_method called, access to class variables via 'cls', no instance variables") print(f"{cls.count=}")

@staticmethod def my_static_method(): print("my_static_method called, no 'self' or 'cls'") print(f"{My_Class.count=}") # but still access to class variables

obj1 = My_Class() obj2 = My_Class()

obj1.my_instance_method() obj1.my_class_method() obj1.my_static_method()

for _ in range(2): obj1.my_instance_method() obj2.my_instance_method()

print(f"{obj1.count=}") # reading class variable if no instance variable found obj1.count = 100 # creating instance variable print(f"{obj1.count=}") # now finding and reading instance variable print(f"{My_Class.count}") # class variable still available via class name print(f"{obj2.count=}") # obj2 still reads the class variable

Run it in the Memory Graph Web Debugger.

Inheritance ##
This example shows the flow of control when using inheritance with:
super()

class variable message_count

def send(self, sender, receiver, message): self.log.append((type(self).__name__, self.priority, sender, receiver, message)) Notification_Service.message_count += 1

class Email_Notification(Notification_Service): def __init__(self, priority, from_email): super().__init__(priority) self.from_email = from_email def send(self, to_email, message): super().send(self.from_email, to_email, message) print(f'sending Email from:{self.from_email} to:{to_email}') print(f'priority: {self.priority} message: "{message}"')

class SMS_Notification(Notification_Service): def __init__(self, priority, from_nr): super().__init__(priority) self.from_nr = from_nr def send(self, to_nr, message): super().send(self.from_nr, to_nr, message) print(f'sending SMS from:{self.from_nr} to:{to_nr}') print(f'priority: {self.priority} message: "{message}"') email = Email_Notification(3, '[email protected]') email.send('[email protected]', 'Your report is ready') email.send('[email protected]', 'Update to Privacy Policy') sms = SMS_Notification(3, '0123456789') sms.send('001122334455', 'Update to Privacy Policy')

Run it in the Memory Graph Web Debugger.

Iterators ##
What actually happens when Python executes a for-loop?

Behind the scenes, Python uses the iterator protocol:

- iter(container): creates an iterator.
next(iterator): retrieves one value at a time.

When there are no more values, the iterator raises StopIteration. The for-loop catches this exception automatically and ends the loop. For containers that support backward iteration, Python also provides:

reversed(container): creates a backward iterator.

We can support these operations in our own classes by implementing:

This provides a powerful abstraction: an algorithm can process values without needing to know how a container stores them internally. The same algorithm can therefore work with lists, sets, dictionaries, linked lists, trees, and many other containers.
Run a Linked_List iterator example in the Memory Graph Web Debugger.
Decorator ##
This example shows the flow of control when using a decorator. A decorator wraps a function and is active before and after the function is called.

@log_call def calculate_total(price, quantity, rounding=False): result = price * quantity return round(result) if rounding else result

@log_call def send_email(receiver, message, sender="[email protected]"): print(f"Sending email to:{receiver} from:{sender}, {message}")

total = calculate_total(7.5, 3, rounding=True) print(total) send_email("[email protected]", "Your order is ready")

Run it in the Memory Graph Web Debugger.

Exception Handling ##
This example shows the flow of control when using exception handling.

def fun1(): try: return fun2() except NameError as e: print(type(e), e) print('fun1() returns')

try: fun1() except LookupError as e: print(type(e), e) print('program ended cleanly')

Run it in the Memory Graph Web Debugger. In the program an IndexError exception is raised which propagates up the call stack until it reaches an except clause that matches its type where it is handled. Here, it is handled by the LookupError except clause because IndexError is a subclass of LookupError. Exceptions that are not handled terminate the execution of a program while its traceback is shown for analyses.

!exception_tree.png
Lazy Evaluation ##
In the following Eager and Lazy ealuation examples, we use this pr() function to print in what order things are created and used.

With eager evaluation, the function creates all three elements up front and stores them in a list before iteration begins. With lazy evaluation, the function returns a generator that creates each element only when it is needed.

<table>
    <tr> <td width="50%" valign="top"><strong>Eager</strong></td> <td width="50%" valign="top"><strong>Lazy</strong></td></tr>
    <tr><td width="50%" valign="top">

for i in fun(): pr('use:', i)

Run in Memory Graph Web Debugger

</td><td width="50%" valign="top">

for i in fun(): pr('use:', i)

Run in Memory Graph Web Debugger

</td></tr>
    <tr><td width="50%" valign="top">

for i in fun(): pr('use:', i)

Run in Memory Graph Web Debugger

</td><td width="50%" valign="top">

for i in fun(): pr('use:', i)

Run in Memory Graph Web Debugger

</td></tr>
    <tr><td width="50%" valign="top">

</td><td width="50%" valign="top">

Lazy evaluation is critical when you want to quickly start to process the first elements of a large stream of data, that may not even fit in your RAM entirely, or process just a section of an infite stream.

</td></tr>
</table>
Configuration #
Different aspects of memory_graph can be configured. The default configuration can be reset by calling 'mg.config_default.reset()'. The Memory Graph Web Debugger gives examples of the most important configurations.
mg.config.reopen_viewer : bool
  - If True the viewer is reopened each time show() is called, this might change window focus, default True.
mg.config.render_filename : str
  - The default filename to render to, default 'memory_graph.pdf'.
mg.config.type_labels : bool
  - If True the type of each node is shown as label, default True.
mg.config.block_prints_location : bool
  - If True the source location is printed in block(), default True.
  
mg.config.press_enter_message : str
  - Message to ask user to press &lt;Enter&gt; in block(), set to None to disable.
mg.config.max_string_length : int
  - The maximum length of strings shown in the graph. Longer strings will be truncated.
mg.config.embedded_types : set[type]
  - Holds all types for which no separate node is drawn but that are embedded in their parent Node.
mg.config.embedded_key_types : set[type]
  - Holds all types that are embedded as key in a Node_Key_Value node, even when not in 'embedded_types'.
mg.config.embedding_types : set[type]
  - Holds all dictionary types that embed their key-value tuple children.
mg.config.no_index_types : set[type]
  - Holds all types like 'set' and 'frozenset' that should not have indices as Node_Linear.
mg.config.type_to_node : dict[type, fun(data) -> Node]
  - Determines how a data type is converted to a Node subclass for visualization in the graph.
mg.config.type_to_color : dict[type, color]
  - Maps a type to the graphviz color it gets in the graph.
mg.config.type_to_horizontal : dict[type, bool]
  - Maps a type to its orientation for Node_Linear and Node_Key_Value. Use 'True' for horizontal and 'False' for vertical. If not specified these nodes vertical unless they have references to children.
mg.config.type_to_slicer : dict[type, int]
  - Maps a type to a Slicer. A slicer determines how many elements of a data type are shown in the graph to prevent the graph from getting too big. 'Slicer()' does no slicing, 'Slicer(1,2,3)' shows just 1 element at the beginning, 2 in the middle, and 3 at the end.
mg.config.max_graph_depth : int
  - The maxium depth of the graph with default value 1000.
mg.config.graph_cut_symbol : str
  - The symbol indicating where the graph is cut short with default ✂.
  
mg.config.type_to_depth : dict[type, int]
  - Maps a type to graph depth to limit the graph size.
mg.config.max_missing_edges : int
  - Maximum number of missing edges that are shown with default value 2. Dashed references are used to indicate that there are more references to a node than are shown.
mg.config.fontname : str
  - The font used in the graph, default 'Times-Roman' (widely available on the web).
mg.config.fontsize : str
  - The font size used in the graph, default '14'.
Functions ##
mg.layout(horizontal: bool = None)
  - Set graph layout to 'True' for horizontal, 'False' for vertical, or 'None' to toggle.
mg.dark_mode(b: bool = None)
  - Set dark mode to 'True' or 'False', or 'None' to toggle.
mg.transparent_background(b: bool = None)
  - Set transparent background to 'True' or 'False', or 'None' to toggle.
Simplified Graph ##
Memory_graph simplifies the visualization (and the viewer's mental model) by not showing separate nodes for immutable types like bool, int, float, complex, and str by default. This simplification can sometimes be slightly misleading. As in the example below, after a shallow copy, lists a and b technically share their int values, but the graph makes it appear as though a and b each have their own copies. However, since int is immutable, this simplification will never lead to unexpected changes (changing a's ints won’t affect b) so will never result in bugs.
The simplification strikes a balance: it is slightly misleading but keeps the graph clean and easy to understand to focus on mutable types where unexpected changes can occur. This is why it is the default behavior. If you do want to show separate nodes for int values, such as for educational purposes, you can simply remove int from the mg.config.embedded_types set:

a = [100, 200, 300] b = a.copy() mg.render(locals(), 'embedded1.png')

mg.config.embedded_types.remove(int) # now show separate nodes for int values

mg.render(locals(), 'embedded2.png')

| !embedded1 | !embedded2 |
|:-----------------------------------------------------------:|:-------------------------------------------------------------:|
| embedded1.png — simplified | embedded2.png — technically correct |

Additionally, the simplification hides away the [reuse of small int values \[-5, 256\]](https://docs.python.org/3/c-api/long.html#c.PyLong_FromLong) in the current CPython implementation, an optimization that might otherwise confuse beginner Python programmers. For instance, after executing a[1]+=1; b[1]+=1 the 201 value is, maybe surprisingly, still shared between a and b, whereas executing a[2]+=1; b[2]+=1 does not result in sharing the 301 value. Similarly CPython uses String Interning to reuse small strings.

Introspection #
Sometimes the introspection fails or is not as desired. For example the bintrees.avltree.Node object doesn't show any attributes in the graph below.

Create an AVL tree

mg.show(locals())