methodgraph 0.1.0__py3-none-any.whl

methodgraph/tracer.py

@@ -0,0 +1,297 @@
+import functools
+import inspect
+import os
+import sys
+import threading
+import atexit
+from typing import Any, Callable, Dict, List, Optional, Type, Union
+
+from .collector import ExecutionTraceCollector, safe_serialize_val
+from .renderer import render_and_save, open_in_browser
+
+_report_scheduled = False
+
+def _generate_atexit_report(report_path: str):
+    global _report_scheduled
+    if not _report_scheduled:
+        return
+    collector = get_active_collector()
+    summary = collector.build_summary()
+    html_path = render_and_save(summary, report_path)
+    open_in_browser(html_path)
+
+# Thread-local storage for managing nested call stacks per thread
+_thread_local = threading.local()
+
+def _get_call_stack() -> List[int]:
+    if not hasattr(_thread_local, "call_stack"):
+        _thread_local.call_stack = []
+    return _thread_local.call_stack
+
+_global_collector: Optional[ExecutionTraceCollector] = None
+_global_collector_lock = threading.Lock()
+
+def get_active_collector() -> ExecutionTraceCollector:
+    global _global_collector
+    with _global_collector_lock:
+        if _global_collector is None:
+            _global_collector = ExecutionTraceCollector()
+        return _global_collector
+
+def reset_active_collector() -> ExecutionTraceCollector:
+    global _global_collector
+    with _global_collector_lock:
+        _global_collector = ExecutionTraceCollector()
+        return _global_collector
+
+
+def _capture_function_args(func: Callable, args: tuple, kwargs: dict) -> tuple:
+    """Parses positional args and kwargs into structured data list and dict."""
+    args_data = []
+    kwargs_data = {}
+    
+    try:
+        sig = inspect.signature(func)
+        bound_args = sig.bind(*args, **kwargs)
+        bound_args.apply_defaults()
+        
+        for name, val in bound_args.arguments.items():
+            param_kind = sig.parameters[name].kind if name in sig.parameters else None
+            
+            if param_kind == inspect.Parameter.VAR_POSITIONAL: # *args
+                for idx, item in enumerate(val):
+                    args_data.append({
+                        "name": f"*{name}[{idx}]",
+                        "val_info": safe_serialize_val(item)
+                    })
+            elif param_kind == inspect.Parameter.VAR_KEYWORD: # **kwargs
+                for k, item in val.items():
+                    kwargs_data[k] = safe_serialize_val(item)
+            else:
+                # Regular parameter or self/cls
+                if name in ("self", "cls"):
+                    # Record self/cls cleanly
+                    args_data.append({
+                        "name": name,
+                        "val_info": safe_serialize_val(val, max_depth=1)
+                    })
+                else:
+                    kwargs_data[name] = safe_serialize_val(val)
+    except Exception:
+        # Fallback if signature binding fails (C extensions or dynamic builtins)
+        for idx, item in enumerate(args):
+            args_data.append({
+                "name": f"arg_{idx}",
+                "val_info": safe_serialize_val(item)
+            })
+        for k, v in kwargs.items():
+            kwargs_data[k] = safe_serialize_val(v)
+
+    return args_data, kwargs_data
+
+
+class trace:
+    """Decorator to trace a function or method execution."""
+    
+    def __init__(self, func: Optional[Callable] = None, *, show_on_exit: bool = False, report_path: str = "methodgraph_report.html"):
+        self.func = func
+        self.show_on_exit = show_on_exit
+        self.report_path = report_path
+        
+        if func is not None:
+            functools.update_wrapper(self, func)
+
+    def __call__(self, *args, **kwargs):
+        if self.func is None:
+            # Used as @trace(...) with arguments
+            func_to_wrap = args[0]
+            @functools.wraps(func_to_wrap)
+            def wrapper(*w_args, **w_kwargs):
+                return self._invoke(func_to_wrap, w_args, w_kwargs)
+            return wrapper
+        else:
+            # Used as @trace without parentheses
+            return self._invoke(self.func, args, kwargs)
+
+    def __get__(self, instance, owner):
+        """Supports binding to instance methods."""
+        if self.func is None:
+            return self
+        return functools.partial(self.__call__, instance)
+
+    def _invoke(self, func: Callable, args: tuple, kwargs: dict) -> Any:
+        collector = get_active_collector()
+        call_stack = _get_call_stack()
+        
+        parent_id = call_stack[-1] if call_stack else None
+        depth = len(call_stack)
+        
+        module = getattr(func, "__module__", "") or ""
+        qualname = getattr(func, "__qualname__", func.__name__)
+        func_name = getattr(func, "__name__", "function")
+        
+        try:
+            file_path = inspect.getfile(func)
+            line_no = inspect.getsourcelines(func)[1]
+        except Exception:
+            file_path = "unknown"
+            line_no = 0
+            
+        args_data, kwargs_data = _capture_function_args(func, args, kwargs)
+        
+        record = collector.add_call(
+            parent_id=parent_id,
+            depth=depth,
+            module=module,
+            qualname=qualname,
+            func_name=func_name,
+            file_path=file_path,
+            line_no=line_no,
+            args_data=args_data,
+            kwargs_data=kwargs_data,
+        )
+        
+        call_stack.append(record.call_id)
+        
+        try:
+            result = func(*args, **kwargs)
+            record.complete(return_val=result)
+            return result
+        except BaseException as exc:
+            record.complete(exception=exc)
+            raise
+        finally:
+            call_stack.pop()
+            if self.show_on_exit:
+                global _report_scheduled
+                if not _report_scheduled:
+                    _report_scheduled = True
+                    atexit.register(_generate_atexit_report, self.report_path)
+
+
+def trace_class(cls: Type) -> Type:
+    """Class decorator to apply @trace to all callable methods in a class."""
+    for attr_name, attr_val in list(cls.__dict__.items()):
+        if attr_name.startswith("__") and attr_name.endswith("__"):
+            continue
+            
+        if inspect.isfunction(attr_val) or inspect.ismethod(attr_val):
+            setattr(cls, attr_name, trace(attr_val))
+        elif isinstance(attr_val, classmethod):
+            original_fn = attr_val.__func__
+            setattr(cls, attr_name, classmethod(trace(original_fn)))
+        elif isinstance(attr_val, staticmethod):
+            original_fn = attr_val.__func__
+            setattr(cls, attr_name, staticmethod(trace(original_fn)))
+            
+    return cls
+
+
+class TraceSession:
+    """Context manager for recording execution blocks."""
+    
+    def __init__(self, report_path: str = "methodgraph_report.html", auto_open: bool = False):
+        self.report_path = report_path
+        self.auto_open = auto_open
+        self.collector: Optional[ExecutionTraceCollector] = None
+
+    def __enter__(self):
+        self.collector = reset_active_collector()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self.collector:
+            summary = self.collector.build_summary()
+            saved_file = render_and_save(summary, self.report_path)
+            if self.auto_open:
+                open_in_browser(saved_file)
+
+
+class SystemTracer:
+    """sys.settrace hook for dynamic tracing of scripts without decorators."""
+    
+    def __init__(self, include_stdlib: bool = False):
+        self.include_stdlib = include_stdlib
+        self.collector = get_active_collector()
+        self.frame_to_record: Dict[int, Any] = {}
+        self.py_stdlib_dir = os.path.dirname(os.path.dirname(inspect.__file__)).lower()
+
+    def _should_trace_file(self, file_path: str) -> bool:
+        if not file_path or file_path.startswith("<"):
+            return False
+        fp_lower = os.path.abspath(file_path).lower()
+        
+        # Prevent tracing methodgraph's own internal source files
+        tracer_dir = os.path.dirname(os.path.abspath(__file__)).lower()
+        if fp_lower.startswith(tracer_dir):
+            return False
+
+        if not self.include_stdlib:
+            if "site-packages" in fp_lower or "dist-packages" in fp_lower:
+                return False
+            if fp_lower.startswith(self.py_stdlib_dir):
+                return False
+        return True
+
+    def trace_dispatch(self, frame, event, arg):
+        code = frame.f_code
+        file_path = code.co_filename
+        
+        if not self._should_trace_file(file_path):
+            return self.trace_dispatch
+
+        frame_id = id(frame)
+        call_stack = _get_call_stack()
+
+        if event == "call":
+            func_name = code.co_name
+            module = frame.f_globals.get("__name__", "")
+            qualname = func_name
+            line_no = code.co_firstlineno
+            
+            # Extract local arguments from frame
+            args_data = []
+            kwargs_data = {}
+            argcount = code.co_argcount + code.co_kwonlyargcount
+            var_names = code.co_varnames
+            
+            for i in range(argcount):
+                if i < len(var_names):
+                    var_name = var_names[i]
+                    val = frame.f_locals.get(var_name)
+                    if var_name in ("self", "cls"):
+                        args_data.append({"name": var_name, "val_info": safe_serialize_val(val, max_depth=1)})
+                    else:
+                        kwargs_data[var_name] = safe_serialize_val(val)
+                        
+            parent_id = call_stack[-1] if call_stack else None
+            depth = len(call_stack)
+            
+            record = self.collector.add_call(
+                parent_id=parent_id,
+                depth=depth,
+                module=module,
+                qualname=qualname,
+                func_name=func_name,
+                file_path=file_path,
+                line_no=line_no,
+                args_data=args_data,
+                kwargs_data=kwargs_data,
+            )
+            
+            self.frame_to_record[frame_id] = record
+            call_stack.append(record.call_id)
+            
+        elif event == "return":
+            record = self.frame_to_record.pop(frame_id, None)
+            if record:
+                record.complete(return_val=arg)
+                if call_stack and call_stack[-1] == record.call_id:
+                    call_stack.pop()
+
+        elif event == "exception":
+            record = self.frame_to_record.get(frame_id)
+            if record and isinstance(arg[1], BaseException):
+                record.complete(exception=arg[1])
+
+        return self.trace_dispatch

methodgraph-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+methodgraph/__init__.py,sha256=xlR9DNAITQ4pEg7WpMEoy-c03fqgspxFU7YTG_pzolc,871
+methodgraph/cli.py,sha256=OvZOPxuq6v2J4JTQ78v0zDhXH_DWLCMeNkz2DI192zc,3241
+methodgraph/collector.py,sha256=v8K1h_fgV2BcRnmJ89KQelUv14k9Jm0K5p_dCLplCKU,12246
+methodgraph/renderer.py,sha256=r_iFicA_hHXkzC9SLyoH3fPM2OTmEAsTYKGSyAm-EOU,1539
+methodgraph/server.py,sha256=wo00ZfaCvTmL2tlUvnvWAkLdxbKVH6uiDfQAJGMKIuc,1096
+methodgraph/tracer.py,sha256=YhYXXRLb-Y9jzzQNGCUC9bvrvpPl0I7CVfKqfGLJTyM,10710
+methodgraph/templates/report.html,sha256=WsckjiJw29Idkp2-5jZXw-AkPVABXFkfKBx7W2tbOS8,88402
+methodgraph-0.1.0.dist-info/licenses/LICENSE,sha256=wfJJ1UL-WsyIlxt2aTqCOIvRIBO4Qf_OLMZkOs6kRSw,1048
+methodgraph-0.1.0.dist-info/METADATA,sha256=zfWOz_aLwLlUi8dMKM1obcgcEDBQEceQ-_0NEWket4g,4978
+methodgraph-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+methodgraph-0.1.0.dist-info/entry_points.txt,sha256=7x-v0Xna1UqlasiF3YgHps7MJc0HNqb0TpsOXCyHaMM,53
+methodgraph-0.1.0.dist-info/top_level.txt,sha256=gi84YkdFhN2ckhnBgE6l1gY3Fv9s3rM91W1nbpcG3EM,12
+methodgraph-0.1.0.dist-info/RECORD,,

methodgraph-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

methodgraph-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+methodgraph = methodgraph.cli:main

methodgraph-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+methodgraph