memory-graph 0.3.30__py3-none-any.whl

memory_graph/__init__.py

@@ -0,0 +1,322 @@
+# This file is part of memory_graph.
+# Copyright (c) 2023, Bas Terwijn.
+# SPDX-License-Identifier: BSD-2-Clause
+
+import memory_graph.memory_to_nodes as memory_to_nodes
+import memory_graph.config as config
+import memory_graph.config_default
+import memory_graph.config_helpers as config_helper
+import memory_graph.utils as utils
+
+import inspect
+import sys
+import itertools as it
+from memory_graph.call_stack import call_stack
+
+import graphviz
+
+# Add 'mg' to builtins so it is available in all subsequent imports
+import memory_graph as mg
+import builtins
+if not hasattr(builtins, "mg"):
+    builtins.mg = mg
+
+__version__ = "0.3.30"
+__author__ = 'Bas Terwijn'
+render_filename = 'memory_graph.pdf'
+render_filename_count = 0
+last_show_filename = None
+block_prints_location = True
+press_enter_message = "Press <Enter> to continue..."
+
+def get_source_location(stack_index=0):
+    """ Helper function to get the source location of the stack with 'stack_index' of the call stack. """
+    frameInfo = inspect.stack()[1+stack_index] # get frameInfo of calling frame
+    filename= frameInfo.filename
+    line_nr= frameInfo.lineno
+    function = frameInfo.function
+    return f'{filename}:{line_nr} in "{function}"'
+
+def block(fun=None, *args, **kwargs):
+    """
+    Calls the given function `fun` with specified arguments and keyword arguments,
+    waits for the user to press Enter, and returns the result of `fun`.
+    """
+    stack_index = 0
+    if 'stack_index' in kwargs:
+        stack_index = kwargs['stack_index']
+        del kwargs['stack_index']
+    result = None
+    if callable(fun):
+        result = fun(*args, **kwargs)
+    if memory_graph.block_prints_location:
+        print('blocked at ' + get_source_location(1+stack_index), end=', ')
+    if memory_graph.press_enter_message:
+        print(memory_graph.press_enter_message)
+    input()
+    return result
+
+def block_deprecated_message():
+    print("Warning: 'block=True' deprecated, use mg.block(fun) instead.")
+    input(f"{get_source_location(3)}, Press <Enter> to continue...")
+
+def create_graph(data,
+                 colors = None,
+                 vertical_orientations = None,
+                 slicers = None):
+    """ Creates and returns a memory graph from 'data'. """
+    config_helper.set_config(colors, vertical_orientations, slicers)
+    graphviz_graph = memory_to_nodes.memory_to_nodes(data)
+    return graphviz_graph
+
+def number_filename(outfile):
+    """ Returns the 'outfile' with 'render_filename_count'. """
+    global render_filename_count
+    splits = outfile.split('.')
+    if len(splits)>1:
+        splits[-2]+=str(render_filename_count)
+        render_filename_count += 1
+        return '.'.join(splits)
+    return self.filename
+
+def render(data, outfile=None, view=False, block=False,
+                 colors = None,
+                 vertical_orientations = None,
+                 slicers = None,
+                 numbered = False):
+    """ Renders the graph of 'data' to 'outfile' or `memory_graph.render_filename` when not specified. """
+    if outfile is None:
+        outfile = memory_graph.render_filename
+    graph = create_graph(data, colors, vertical_orientations, slicers)
+    if numbered:
+        outfile = number_filename(outfile)
+    if outfile.endswith('.gv') or outfile.endswith('.dot'):
+        graph.save(filename=outfile)
+    else:
+        graph.render(outfile=outfile, view=view, cleanup=False, quiet=False, quiet_view=False)
+    if block:
+        block_deprecated_message()
+
+def show(data, outfile=None, view=False, block=False,
+                 colors = None,
+                 vertical_orientations = None,
+                 slicers = None,
+                 numbered = False):
+    """ Shows the graph of 'data' by first rendering and then opening the default viewer
+    application by file extension at first call, when the outfile changes, or
+    when view is True. """
+    if outfile is None:
+        outfile = memory_graph.render_filename
+    open_view = (outfile != memory_graph.last_show_filename) or view
+    render(data=data, outfile=outfile, view=open_view, block=block,
+           colors=colors,
+           vertical_orientations=vertical_orientations,
+           slicers=slicers, numbered=numbered)
+    memory_graph.last_show_filename = outfile
+
+    
+# ------------ aliases
+
+def sl(stack_index=0, colors = None, vertical_orientations = None, slicers = None):
+    """ 
+    Shows the graph of locals() and blocks. 
+    """
+    data = get_locals_from_call_stack(stack_index=1+stack_index)
+    memory_graph.show(data, colors=colors, vertical_orientations=vertical_orientations, slicers=slicers)
+    
+def ss(stack_index=0, colors = None, vertical_orientations = None, slicers = None):
+    """ 
+    Shows the graph of mg.stack() and blocks. 
+    """
+    data = stack(stack_index=1+stack_index)
+    memory_graph.show(data, colors=colors, vertical_orientations=vertical_orientations, slicers=slicers)
+
+def bsl(stack_index=0, colors = None, vertical_orientations = None, slicers = None):
+    """ 
+    Shows the graph of locals() and blocks. 
+    """
+    data = get_locals_from_call_stack(stack_index=1+stack_index)
+    memory_graph.block(memory_graph.show, data, stack_index=1+stack_index, block=False, 
+                       colors=colors, vertical_orientations=vertical_orientations, slicers=slicers)
+    
+def bss(stack_index=0, colors = None, vertical_orientations = None, slicers = None):
+    """ 
+    Shows the graph of mg.stack() and blocks. 
+    """
+    data = stack(stack_index=1+stack_index)
+    memory_graph.block(memory_graph.show, data, stack_index=1+stack_index, block=False, 
+                       colors=colors, vertical_orientations=vertical_orientations, slicers=slicers)
+
+def rl(stack_index=0, colors = None, vertical_orientations = None, slicers = None):
+    """ 
+    Shows the graph of locals() and blocks. 
+    """
+    data = get_locals_from_call_stack(stack_index=1+stack_index)
+    memory_graph.render(data, block=False, colors=colors, vertical_orientations=vertical_orientations, slicers=slicers)
+    
+def rs(stack_index=0, colors = None, vertical_orientations = None, slicers = None):
+    """ 
+    Shows the graph of mg.stack() and blocks. 
+    """
+    data = stack(stack_index=1+stack_index)
+    memory_graph.render(data, block=False, colors=colors, vertical_orientations=vertical_orientations, slicers=slicers)
+
+def brl(stack_index=0, colors = None, vertical_orientations = None, slicers = None):
+    """ 
+    Shows the graph of locals() and blocks. 
+    """
+    data = get_locals_from_call_stack(stack_index=1+stack_index)
+    memory_graph.block(memory_graph.render, data, stack_index=1+stack_index, block=False, 
+                       colors=colors, vertical_orientations=vertical_orientations, slicers=slicers)
+    
+def brs(stack_index=0, colors = None, vertical_orientations = None, slicers = None):
+    """ 
+    Shows the graph of mg.stack() and blocks. 
+    """
+    data = stack(stack_index=1+stack_index)
+    memory_graph.block(memory_graph.render, data, stack_index=1+stack_index, block=False, 
+                       colors=colors, vertical_orientations=vertical_orientations, slicers=slicers)
+
+def l(stack_index=0, colors = None, vertical_orientations = None, slicers = None):
+    """ 
+    Shows the graph of locals() and blocks. 
+    """
+    bsl(stack_index=1+stack_index, colors=colors, vertical_orientations=vertical_orientations, slicers=slicers)
+    
+def s(stack_index=0, colors = None, vertical_orientations = None, slicers = None):
+    """ 
+    Shows the graph of mg.stack() and blocks. 
+    """
+    bss(stack_index=1+stack_index, colors=colors, vertical_orientations=vertical_orientations, slicers=slicers)
+
+
+# ------------ call stack
+
+def get_locals_from_call_stack(stack_index=0):
+    """ Helper function to get locals of the stack with 'stack_inex' of the call stack. """
+    frameInfo = inspect.stack()[1+stack_index] # get frameInfo of calling frame
+    return frameInfo.frame.f_locals
+
+def get_function_name(frameInfo):
+    frame = frameInfo.frame
+    func_name = frame.f_code.co_name
+    if 'self' in frame.f_locals:  # instance method
+        return f"{frame.f_locals['self'].__class__.__name__}.{func_name}"
+    elif 'cls' in frame.f_locals:  # class method
+        return f"{frame.f_locals['cls'].__name__}.{func_name}"
+    else:  # forget about static method, too complex
+        return func_name  # just the function
+
+def stack_frames_to_dict(frames):
+    """ Returns a dictionary representing the data on the call stack. 
+    Each key is the stack level and function name, each value is the locals of the frame at that level. 
+    """
+    def to_dict(value): #  fix by TerenceTux for Python 3.13
+        return {k: v for k, v in value.items()}
+    return call_stack({f"{level}: {get_function_name(frameInfo)}" : to_dict(frameInfo.frame.f_locals)
+            for level, frameInfo in enumerate(frames)})
+
+def locals():
+    """ Returns local variables. """
+    return locals()
+
+def stack(through_function="<module>",stack_index=0):
+    return get_call_stack(through_function, 1+stack_index)
+def get_call_stack(through_function="<module>",stack_index=0):
+    """ Gets the call stack up to and including the function 'through_function'. """
+    frames = reversed(list(
+        utils.take_through(lambda i: i.function==through_function, inspect.stack()[1+stack_index:])
+        ))
+    return stack_frames_to_dict(frames)
+
+def stack_after_through(after_function,through_function="<module>"):
+    return get_call_stack_after_through(after_function, through_function)
+def get_call_stack_after_through(after_function,through_function="<module>", drop=0):
+    """ Gets the call stack after the function 'after_function' up to and includeing the function 'through_function'
+        and drops the first 'drop' stack frames. """
+    frames = reversed(list(it.islice(
+            utils.take_through(lambda i: i.function == through_function,
+            utils.take_after(lambda i: i.function == after_function, inspect.stack()))
+            , drop, None)))
+    return stack_frames_to_dict(frames)
+
+def stack_pdb(after_function="trace_dispatch",through_function="<module>"):
+    return get_call_stack_pdb(after_function, through_function)
+def get_call_stack_pdb(after_function="trace_dispatch",through_function="<module>"):
+    """ Get the call stack in a 'pdb' debugger session, filtering out the 'pdb' functions that polute the graph. """
+    return get_call_stack_after_through(after_function,through_function)
+
+def stack_vscode(after_function="do_wait_suspend",through_function="<module>"):
+    return get_call_stack_vscode(after_function, through_function)
+def get_call_stack_vscode(after_function="do_wait_suspend",through_function="<module>"):
+    """ Get the call stack in a 'vscode' debugger session, filtering out the 'vscode' functions that polute the graph. """
+    return get_call_stack_after_through(after_function,through_function)
+
+def stack_cursor(after_function="do_wait_suspend",through_function="<module>"):
+    return get_call_stack_cursor(after_function, through_function)
+def get_call_stack_cursor(after_function="do_wait_suspend",through_function="<module>"):
+    """ Get the call stack in a 'cursor' debugger session, filtering out the 'cursor' functions that polute the graph. """
+    return get_call_stack_after_through(after_function,through_function)
+
+def stack_pycharm(after_function="do_wait_suspend",through_function="<module>"):
+    return get_call_stack_pycharm(after_function, through_function)
+def get_call_stack_pycharm(after_function="do_wait_suspend",through_function="<module>"):
+    """ Get the call stack in a 'vscode' debugger session, filtering out the 'vscode' functions that polute the graph. """
+    return get_call_stack_after_through(after_function,through_function, 1)
+
+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. """
+    with open(filename,'w') as file:
+        for frame in inspect.stack():
+            file.write(f"function:{frame.function} filename:{frame.filename}\n")
+
+def print_call_stack_vars(stack_index=0):
+    """ Prints all variables on the call stack. """
+    for level, frameInfo in enumerate(reversed(inspect.stack())):
+        print('=====',level,frameInfo.function)
+        print(tuple(frameInfo.frame.f_locals.keys()))
+
+
+# ------------ jupyter filtering
+
+jupyter_filter_keys = {'exit','quit','v','In','Out','jupyter_filter_keys'}
+def jupyter_locals_filter(jupyter_locals):
+    """ Filter out the jupyter specific keys that polute the graph. """
+    return {k:v for k,v in utils.filter_dict(jupyter_locals)
+            if k not in jupyter_filter_keys and k[0] != '_'}
+
+def locals_jupyter(stack_index=0):
+    """ Get the locals of the calling frame in a jupyter notebook, filtering out the jupyter specific keys. """
+    return jupyter_locals_filter(get_locals_from_call_stack(1+stack_index))
+
+def stack_jupyter(through_function="<module>",stack_index=0):
+    return get_call_stack_jupyter(through_function, 1+stack_index)
+def get_call_stack_jupyter(through_function="<module>",stack_index=0):
+    """ Get the call stack in a jupyter notebook, filtering out the jupyter specific keys. """
+    call_stack = get_call_stack(through_function,1+stack_index)
+    globals_frame = next(iter(call_stack))
+    call_stack[globals_frame] = jupyter_locals_filter(call_stack[globals_frame])
+    return call_stack
+
+
+# ------------ ipython filtering
+
+ipython_filter_keys = {'mg_visualization_status', 'sys', 'ipython', 'In', 'Out', 'get_ipython', 'exit', 'quit', 'open'}
+def ipython_locals_filter(ipython_locals):
+    """ Filter out the ipython specific keys that polute the graph. """
+    return {k:v for k,v in utils.filter_dict(ipython_locals)
+            if k not in ipython_filter_keys and k[0] != '_'}
+
+def locals_ipython(stack_index=0):
+    """ Get the locals of the calling frame in a ipython, filtering out the ipython specific keys. """
+    return ipython_locals_filter(get_locals_from_call_stack(1+stack_index))
+
+def stack_ipython(through_function="<module>",stack_index=0):
+    return get_call_stack_ipython(through_function, 1+stack_index)
+def get_call_stack_ipython(through_function="<module>",stack_index=0):
+    """ Get the call stack in a ipython, filtering out the ipython specific keys. """
+    call_stack = get_call_stack(through_function,1+stack_index)
+    globals_frame = next(iter(call_stack))
+    call_stack[globals_frame] = ipython_locals_filter(call_stack[globals_frame])
+    return call_stack

memory_graph/call_stack.py

@@ -0,0 +1,9 @@
+# This file is part of memory_graph.
+# Copyright (c) 2023, Bas Terwijn.
+# SPDX-License-Identifier: BSD-2-Clause
+
+class call_stack(dict):
+    """Inherits from dict to give the call stack it own name and color. """
+    
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)

memory_graph/config.py

@@ -0,0 +1,35 @@
+# This file is part of memory_graph.
+# Copyright (c) 2023, Bas Terwijn.
+# SPDX-License-Identifier: BSD-2-Clause
+
+""" Configuration file for the graph visualizer. The configuration values are set later by the 'config_default.py' file. """
+
+
+max_string_length = None
+graph_stability = None
+
+not_node_types = {}
+no_child_references_types = set()
+
+type_to_string = { }
+
+def to_string(data):
+    """ Convert data to string. """
+    data_type = type(data)
+    if data_type in type_to_string:
+        return type_to_string[data_type](data)
+    return str(data)
+
+type_to_node = { }
+
+type_to_color = { }
+
+type_to_vertical_orientation = { }
+
+type_to_slicer = { }
+
+max_graph_depth = None
+graph_cut_symbol = None
+max_missing_edges = None
+
+type_to_depth = { }

memory_graph/config_default.py

@@ -0,0 +1,108 @@
+# This file is part of memory_graph.
+# Copyright (c) 2023, Bas Terwijn.
+# SPDX-License-Identifier: BSD-2-Clause
+
+""" Sets the default configuration values for the memory graph. """
+from memory_graph.node_leaf      import Node_Leaf
+from memory_graph.node_linear    import Node_Linear
+from memory_graph.node_key_value import Node_Key_Value
+from memory_graph.node_table     import Node_Table
+
+from memory_graph.call_stack import call_stack
+from memory_graph.slicer import Slicer
+
+import memory_graph.config as config
+import memory_graph.utils as utils
+
+import types
+
+
+""" The maximum length of strings shown in the graph. Longer strings will be truncated. """
+config.max_string_length = 42
+
+""" The number of references keeping child nodes in order versus other references pulling them out. """
+config.graph_stability = 10
+
+""" Types that by default will not have references pointing to them in the graph but instead will be visualized in the node of their parent. """
+config.not_node_types = {
+    type(None), bool, int, float, complex, str,
+    types.FunctionType,
+    types.MethodType,
+    classmethod,
+    staticmethod,
+    type(len),
+}
+
+""" Types that will not have references pointing to their children in the graph but instead will have their children visualized in their node. """
+config.no_child_references_types = {dict, types.MappingProxyType}
+
+""" Types that need an special conversion """
+config.type_to_string = {
+    types.FunctionType: lambda data: data.__qualname__,
+    types.MethodType: lambda data: data.__qualname__,
+    classmethod: lambda data: data.__qualname__,
+    staticmethod: lambda data: data.__qualname__,
+    type(len): lambda data: data.__qualname__,
+}
+
+""" Conversion from type to Node objects. """
+config.type_to_node = {
+    str: lambda data: Node_Leaf(data, data), # visit as whole string, don't iterate over characters
+    call_stack: lambda data: Node_Key_Value(data, data.items()),
+    type: lambda data: Node_Key_Value(data, utils.filter_type_attributes(vars(data).items())),
+    range: lambda data: Node_Key_Value(data, {'start':data.start, 'stop':data.stop, 'step':data.step}.items()),
+    dict: lambda data: (
+        Node_Key_Value(data, utils.filter_dict(data) )
+            if dict in config.no_child_references_types else 
+        Node_Linear(data, utils.filter_dict(data) )
+        ),
+    }
+
+""" Colors of different types in the graph. """
+config.type_to_color = {
+    # ================= singular
+    type(None) : "gray",
+    bool : "pink",
+    int : "green",
+    float : "violetred1",
+    complex : "yellow",
+    str : "cyan",
+    # ================= linear
+    tuple : "orange",
+    list : "lightcoral",
+    set : "orchid1",
+    frozenset : "orchid2",
+    bytes : "khaki1",
+    bytearray : "khaki2",
+    # ================= key_value
+    Node_Key_Value : "seagreen1", # for classes
+    call_stack : 'khaki',
+    type: "seagreen3",            # where class variables are stored
+    dict : "#60a5ff",
+    types.MappingProxyType : "dodgerblue2", # not used
+    range : "cornsilk2",
+}
+
+""" Types that will be visualized in vertical orientation if 'True', or horizontal orientation 
+if 'False'. Otherwise the Node decides based on it having references."""
+config.type_to_vertical_orientation = {
+}
+
+""" Slicer objects for different types. """
+config.type_to_slicer = {
+    Node_Linear: Slicer(5,3,5),
+    Node_Key_Value: Slicer(5,3,5),
+    Node_Table: (Slicer(3,2,3), Slicer(3,2,3)),
+}
+
+""" The maximum depth of nodes in the graph. When the graph gets too big set this to a small positive number. A `✂` symbol indictes where the graph is cut short. """
+config.max_graph_depth = 12
+config.graph_cut_symbol = '✂'
+
+
+""" Maximum introspection depth for different types. """
+config.type_to_depth = {
+    }
+
+""" Maximum number of missing edges that are shown. """
+config.max_missing_edges = 2

memory_graph/config_helpers.py

@@ -0,0 +1,56 @@
+# This file is part of memory_graph.
+# Copyright (c) 2023, Bas Terwijn.
+# SPDX-License-Identifier: BSD-2-Clause
+
+""" This module provides helper functions to access the configuration of the memory graph. """
+from memory_graph.slicer import Slicer
+
+import memory_graph.config as config
+
+type_to_color = None
+type_to_vertical_orientation = None
+type_to_slicer = None
+
+def set_config(colors=None, vertical_orientations=None, slicers=None):
+    global type_to_color
+    global type_to_vertical_orientation
+    global type_to_slicer
+    type_to_color = config.type_to_color.copy()
+    type_to_vertical_orientation = config.type_to_vertical_orientation.copy()
+    type_to_slicer = config.type_to_slicer.copy()
+    if colors:
+        type_to_color                |= colors
+    if vertical_orientations:
+        type_to_vertical_orientation |= vertical_orientations
+    if slicers:
+        type_to_slicer               |= slicers
+
+def get_property(data_id, data_type, node_type, dictionary, default):
+    if data_id in dictionary:
+        return dictionary[data_id]
+    if data_type in dictionary:
+        return dictionary[data_type]
+    if node_type in dictionary:
+        return dictionary[node_type]
+    return default
+
+def get_color(node, default='white'):
+    return get_property(node.get_id(),
+                        node.get_type(),
+                        type(node),
+                        type_to_color, 
+                        default)
+    
+def get_vertical_orientation(node, default):
+    return get_property(node.get_id(),
+                        node.get_type(),
+                        type(node),
+                        type_to_vertical_orientation, 
+                        default)
+
+def get_slicer(node, data, default=Slicer(3,2,3)):
+    return get_property(id(data),
+                        type(data),
+                        type(node), 
+                        type_to_slicer, 
+                        default)

memory_graph/extension_numpy.py

@@ -0,0 +1,30 @@
+# This file is part of memory_graph.
+# Copyright (c) 2023, Bas Terwijn.
+# SPDX-License-Identifier: BSD-2-Clause
+
+""" Extension to add the memory graph configuration for Numpy types. """
+from memory_graph.node_linear import Node_Linear
+from memory_graph.node_table import Node_Table
+
+import memory_graph.config as config
+
+import numpy as np
+
+config.not_node_types |= {
+    np.int8, np.int16, np.int32, np.int64, np.uint8, np.uint16, np.uint32, np.uint64, 
+    np.float16, np.float32, np.float64,
+    np.complex64, np.complex128,
+    np.bool_, np.bytes_, np.str_, np.datetime64, np.timedelta64
+}
+
+def ndarrayy_to_node(ndarrayy_data):
+    if len(ndarrayy_data.shape) == 2:
+        return Node_Table(ndarrayy_data, ndarrayy_data)
+    else:
+        return Node_Linear(ndarrayy_data, ndarrayy_data)
+    
+config.type_to_node[np.matrix] = lambda data : Node_Table(data, np.asarray(data)) # convert to ndarray to avoid infinite recursion due to index issue
+config.type_to_node[np.ndarray] = lambda data :  ndarrayy_to_node(data)
+
+config.type_to_color[np.ndarray] = "hotpink1"
+config.type_to_color[np.matrix] = "hotpink2"

memory_graph/extension_pandas.py

@@ -0,0 +1,26 @@
+# This file is part of memory_graph.
+# Copyright (c) 2023, Bas Terwijn.
+# SPDX-License-Identifier: BSD-2-Clause
+
+""" Extension to add the memory graph configuration for Pandas type. """
+from memory_graph.node_linear import Node_Linear
+from memory_graph.node_table import Node_Table
+
+import memory_graph.config as config
+
+import pandas as pd
+
+config.type_to_node[pd.DataFrame] = lambda data : (
+    Node_Table(data, 
+               data.values.tolist(),
+               col_names = data.columns.tolist(),
+               row_names = [ str(i) for i in data.index.tolist()]
+            )
+)
+
+config.type_to_node[pd.Series] = lambda data : (
+    Node_Linear(data, data.tolist())
+)
+
+config.type_to_color[pd.DataFrame] = "olivedrab1"
+config.type_to_color[pd.Series] = "olivedrab2"