🔍 methodgraph

Graphical Style Flow Visual Debugger for Python Method Calls, Passed Values, and Execution Flow

• ⚡ Graphical Style Flow Canvas: Interactive node-edge workflow DAG with __start__ and __end__ boundary capsules, smooth curved Bezier connectors, card-style nodes, pan/zoom, and minimap.
• 🎬 Step-by-Step Playback & Time-Travel Scrubber: Animate function execution flows with live pulsing halos, edge particle streams, and synchronized state inspection.
• 🔬 State & Run Inspector: Split-screen drawer featuring collapsible syntax-highlighted object trees for inputs, outputs, exceptions, execution metadata, and run history.
• 🌓 Light & Dark Theme Toggle: Built-in dark and light mode themes with persistent preferences and auto OS detection.
• ⏱️ Trace Waterfall Timeline: Execution timing visualization broken down by function call duration and concurrency spans.
• 🌳 Interactive Call Tree: Nested collapsible hierarchy of function invocations with inline parameter chips and return status.
• 📊 Searchable Data Matrix: Filter, search, and inspect argument values, types, return values, and error tracebacks.
• 🖥️ CLI Runner & Auto Browser Launcher: Trace scripts automatically without changing source code.

🚀 Quick Start

1. Installation

pip install methodgraph

Or install locally in editable mode:

git clone https://github.com/example/methodgraph.git
cd methodgraph
pip install -e .

💡 Usage Modes

Option A: Function Decorator @trace

Trace specific functions and open the graphical visualization when executed:

from methodgraph import trace, show

@trace(show_on_exit=True)
def calculate_tax(amount, rate=0.2):
    return amount * rate

@trace
def process_order(item_id, price, quantity):
    tax = calculate_tax(price * quantity)
    total = (price * quantity) + tax
    return {"item": item_id, "total": total}

# Execute methods
process_order("ITEM-102", price=49.99, quantity=3)

# Generates 'methodgraph_report.html' and opens browser

Option B: Class Decorator @trace_class

Trace all methods within a class automatically:

from methodgraph import trace_class, save_report

@trace_class
class DataPipeline:
    def fetch_data(self, source):
        return [10, 20, 30, 40]

    def transform(self, data, multiplier=2):
        return [x * multiplier for x in data]

    def run(self):
        raw = self.fetch_data("database")
        return self.transform(raw, multiplier=3)

pipeline = DataPipeline()
pipeline.run()

# Save interactive visual report
save_report("pipeline_report.html")

Option C: Context Manager TraceSession

Trace a specific block of code:

from methodgraph import TraceSession

with TraceSession(report_path="session_report.html", auto_open=True) as session:
    data = [5, 12, 18, 24]
    avg = sum(data) / len(data)
    print(f"Average: {avg}")

Option D: CLI Script Tracer (methodgraph run)

Trace any existing Python script without modifying a single line of code!

methodgraph run my_script.py --open

Additional CLI options:

• --open: Open generated HTML report in browser automatically.
• --output report.html: Specify custom report file path.
• --include-stdlib: Include standard library modules in tracing (disabled by default for clean graphs).

🎨 Interactive Features in Graphical Presentation

1. Parameter Inspection: Click any method node to view exact positional args and keyword kwargs, object types, formatted values, and line numbers.
2. Return & Exception Inspector: Clear visual distinction between successful returns and unhandled exceptions (highlighted in crimson red with traceback stack).
3. Execution Bottleneck Finder: Identify slowest methods visually on the Gantt timeline or graph heatmap.
4. Live Search: Filter method calls in real-time by method name, argument name, or argument value substring.

🛠️ Requirements

• Python >= 3.8
• No heavy third-party dependencies required! Generates self-contained HTML/CSS/JS visualizers.

📜 License

MIT License. See LICENSE for details.