methodgraph 0.1.0__tar.gz

methodgraph-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Antigravity
+
+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 IN Schnitt ODER 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.

methodgraph-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include methodgraph/templates *

methodgraph-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: methodgraph
+Version: 0.1.0
+Summary: Graphical flow debugger for Python method calls, arguments, return values, and execution flow.
+Author-email: Sagar Kariya <sbkariya99@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 🔍 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
+
+```bash
+pip install methodgraph
+```
+
+Or install locally in editable mode:
+
+```bash
+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:
+
+```python
+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:
+
+```python
+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:
+
+```python
+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!
+
+```bash
+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](LICENSE) for details.
+

methodgraph-0.1.0/README.md

@@ -0,0 +1,138 @@
+# 🔍 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
+
+```bash
+pip install methodgraph
+```
+
+Or install locally in editable mode:
+
+```bash
+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:
+
+```python
+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:
+
+```python
+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:
+
+```python
+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!
+
+```bash
+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](LICENSE) for details.
+

methodgraph-0.1.0/methodgraph/__init__.py

@@ -0,0 +1,28 @@
+"""
+methodgraph - Graphical visual flow debugger for Python method calls & passed values.
+"""
+
+from .tracer import trace, trace_class, TraceSession, get_active_collector, reset_active_collector
+from .renderer import render_and_save, open_in_browser
+
+__version__ = "0.1.0"
+__all__ = [
+    "trace",
+    "trace_class",
+    "TraceSession",
+    "save_report",
+    "show",
+    "__version__",
+]
+
+def save_report(output_path: str = "methodgraph_report.html") -> str:
+    """Saves current active execution trace to an interactive HTML report file."""
+    collector = get_active_collector()
+    summary = collector.build_summary()
+    return render_and_save(summary, output_path)
+
+def show(output_path: str = "methodgraph_report.html"):
+    """Saves current trace and opens the graphical report in default browser."""
+    path = save_report(output_path)
+    open_in_browser(path)
+

methodgraph-0.1.0/methodgraph/cli.py

@@ -0,0 +1,79 @@
+import argparse
+import os
+import sys
+
+from .tracer import SystemTracer, get_active_collector
+from .renderer import render_and_save, open_in_browser
+from .server import serve_report
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="methodgraph",
+        description="methodgraph: Graphical style visual debugger and flow tracer for Python method calls & passed values."
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Available subcommands")
+
+    # Command: run
+    run_parser = subparsers.add_parser("run", help="Run and trace a Python script dynamically.")
+    run_parser.add_argument("script", help="Path to Python script to trace.")
+    run_parser.add_argument("-o", "--output", default="methodgraph_report.html", help="Report output file path (default: methodgraph_report.html).")
+    run_parser.add_argument("--open", action="store_true", help="Automatically open report in browser when finished.")
+    run_parser.add_argument("--include-stdlib", action="store_true", help="Include Python standard library calls in trace.")
+    run_parser.add_argument("script_args", nargs=argparse.REMAINDER, help="Arguments to pass to target script.")
+
+    # Command: view / serve
+    view_parser = subparsers.add_parser("view", help="View/Serve an existing report file.")
+    view_parser.add_argument("report", nargs="?", default="methodgraph_report.html", help="Path to report HTML file.")
+    view_parser.add_argument("-p", "--port", type=int, default=8080, help="Port to serve report on (default: 8080).")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    if args.command == "run":
+        script_path = os.path.abspath(args.script)
+        if not os.path.exists(script_path):
+            print(f"[methodgraph] Error: Script '{script_path}' not found.")
+            sys.exit(1)
+
+        sys.argv = [script_path] + (args.script_args or [])
+        
+        sys_tracer = SystemTracer(include_stdlib=args.include_stdlib)
+        collector = get_active_collector()
+
+        print(f"[methodgraph] Tracing script: {script_path}...")
+        sys.settrace(sys_tracer.trace_dispatch)
+        
+        try:
+            with open(script_path, "r", encoding="utf-8") as f:
+                code_content = f.read()
+            global_scope = {
+                "__file__": script_path,
+                "__name__": "__main__",
+                "__doc__": None,
+                "__package__": None,
+            }
+            compiled_code = compile(code_content, script_path, 'exec')
+            exec(compiled_code, global_scope)
+        except BaseException as e:
+            if not isinstance(e, SystemExit):
+                print(f"[methodgraph] Script execution error: {e}")
+        finally:
+            sys.settrace(None)
+            
+        summary = collector.build_summary()
+        output_file = render_and_save(summary, args.output)
+        print(f"[methodgraph] Visual trace saved to: {output_file} ({summary['total_calls']} method calls captured)")
+
+        if args.open:
+            open_in_browser(output_file)
+
+    elif args.command == "view":
+        serve_report(args.report, port=args.port, open_browser=True)
+
+
+if __name__ == "__main__":
+    main()
+