methodgraph 0.1.0__py3-none-any.whl

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/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()
+

methodgraph/collector.py

@@ -0,0 +1,307 @@
+import inspect
+import sys
+import time
+import traceback
+from typing import Any, Dict, List, Optional, Union
+
+def safe_serialize_val(val: Any, max_depth: int = 3, max_length: int = 500) -> Dict[str, Any]:
+    """Safely converts any Python value into a serializable summary with type and string representation."""
+    type_name = type(val).__name__
+    
+    if val is None:
+        return {"type": "NoneType", "value": "None"}
+    if isinstance(val, (int, float, bool)):
+        return {"type": type_name, "value": str(val)}
+    if isinstance(val, str):
+        val_str = repr(val)
+        if len(val_str) > max_length:
+            val_str = val_str[:max_length] + " ... [truncated]"
+        return {"type": type_name, "value": val_str}
+        
+    try:
+        if max_depth <= 0:
+            return {"type": type_name, "value": f"<{type_name} instance>"}
+            
+        if isinstance(val, (list, tuple, set)):
+            items_summary = [safe_serialize_val(x, max_depth - 1, max_length // 2) for x in list(val)[:10]]
+            suffix = f" ... ({len(val)} items total)" if len(val) > 10 else ""
+            return {
+                "type": f"{type_name}[{len(val)}]",
+                "value": str([item["value"] for item in items_summary]) + suffix,
+                "items": items_summary
+            }
+        elif isinstance(val, dict):
+            items_summary = {
+                str(k): safe_serialize_val(v, max_depth - 1, max_length // 2)
+                for k, v in list(val.items())[:10]
+            }
+            suffix = f" ... ({len(val)} keys total)" if len(val) > 10 else ""
+            return {
+                "type": f"dict[{len(val)}]",
+                "value": str({k: v["value"] for k, v in items_summary.items()}) + suffix,
+                "items": items_summary
+            }
+    except Exception as e:
+        pass
+        
+    try:
+        val_repr = repr(val)
+    except Exception:
+        val_repr = f"<{type_name} object at {hex(id(val))}>"
+        
+    if len(val_repr) > max_length:
+        val_repr = val_repr[:max_length] + " ... [truncated]"
+        
+    return {"type": type_name, "value": val_repr}
+
+
+class CallRecord:
+    """Represents a single method execution event."""
+    
+    def __init__(
+        self,
+        call_id: int,
+        parent_id: Optional[int],
+        depth: int,
+        module: str,
+        qualname: str,
+        func_name: str,
+        file_path: str,
+        line_no: int,
+        args_data: List[Dict[str, Any]],
+        kwargs_data: Dict[str, Dict[str, Any]],
+        start_time: float,
+    ):
+        self.call_id = call_id
+        self.parent_id = parent_id
+        self.depth = depth
+        self.module = module
+        self.qualname = qualname
+        self.func_name = func_name
+        self.file_path = file_path
+        self.line_no = line_no
+        self.args_data = args_data
+        self.kwargs_data = kwargs_data
+        self.start_time = start_time
+        
+        self.end_time: Optional[float] = None
+        self.duration_ms: Optional[float] = None
+        self.return_val: Optional[Dict[str, Any]] = None
+        self.exception: Optional[Dict[str, Any]] = None
+        self.children: List['CallRecord'] = []
+
+    def complete(self, return_val: Any = None, exception: Optional[BaseException] = None):
+        self.end_time = time.perf_counter()
+        self.duration_ms = round((self.end_time - self.start_time) * 1000, 4)
+        
+        if exception is not None:
+            self.exception = {
+                "type": type(exception).__name__,
+                "message": str(exception),
+                "traceback": "".join(traceback.format_exception(type(exception), exception, exception.__traceback__))
+            }
+        else:
+            self.return_val = safe_serialize_val(return_val)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "call_id": self.call_id,
+            "parent_id": self.parent_id,
+            "depth": self.depth,
+            "module": self.module,
+            "qualname": self.qualname,
+            "func_name": self.func_name,
+            "file_path": self.file_path,
+            "line_no": self.line_no,
+            "args_data": self.args_data,
+            "kwargs_data": self.kwargs_data,
+            "start_time": round(self.start_time, 6),
+            "end_time": round(self.end_time, 6) if self.end_time else None,
+            "duration_ms": self.duration_ms,
+            "return_val": self.return_val,
+            "exception": self.exception,
+            "children": [c.to_dict() for c in self.children],
+        }
+
+
+class ExecutionTraceCollector:
+    """Collects and organizes records into trees and graph networks."""
+    
+    def __init__(self):
+        self.records: Dict[int, CallRecord] = {}
+        self.root_records: List[CallRecord] = []
+        self._next_id = 1
+
+    def generate_id(self) -> int:
+        cid = self._next_id
+        self._next_id += 1
+        return cid
+
+    def add_call(
+        self,
+        parent_id: Optional[int],
+        depth: int,
+        module: str,
+        qualname: str,
+        func_name: str,
+        file_path: str,
+        line_no: int,
+        args_data: List[Dict[str, Any]],
+        kwargs_data: Dict[str, Dict[str, Any]],
+    ) -> CallRecord:
+        call_id = self.generate_id()
+        record = CallRecord(
+            call_id=call_id,
+            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,
+            start_time=time.perf_counter(),
+        )
+        
+        self.records[call_id] = record
+        if parent_id and parent_id in self.records:
+            self.records[parent_id].children.append(record)
+        else:
+            self.root_records.append(record)
+            
+        return record
+
+    def build_summary(self) -> Dict[str, Any]:
+        """Builds graph nodes, edges, statistics, execution steps, and tree hierarchy."""
+        all_records_list = [r.to_dict() for r in sorted(self.records.values(), key=lambda x: x.start_time)]
+        tree = [r.to_dict() for r in self.root_records]
+        
+        # Build DAG nodes & edges
+        nodes_dict: Dict[str, Dict[str, Any]] = {}
+        edges_dict: Dict[str, Dict[str, Any]] = {}
+
+        min_start = min((r.start_time for r in self.records.values()), default=0.0)
+        max_end = max(((r.end_time or r.start_time) for r in self.records.values()), default=0.0)
+        total_session_ms = round((max_end - min_start) * 1000, 4) if max_end > min_start else 0.0
+
+        for r in self.records.values():
+            func_key = f"{r.module}.{r.qualname}" if r.module else r.qualname
+            if func_key not in nodes_dict:
+                nodes_dict[func_key] = {
+                    "id": func_key,
+                    "label": r.qualname,
+                    "module": r.module,
+                    "func_name": r.func_name,
+                    "file_path": r.file_path,
+                    "line_no": r.line_no,
+                    "count": 0,
+                    "total_duration_ms": 0.0,
+                    "max_duration_ms": 0.0,
+                    "min_duration_ms": float("inf"),
+                    "exceptions_count": 0,
+                    "latest_call_id": r.call_id,
+                    "sample_args": r.args_data,
+                    "sample_kwargs": r.kwargs_data,
+                    "sample_return": r.return_val,
+                    "sample_exception": r.exception,
+                }
+            
+            node = nodes_dict[func_key]
+            node["count"] += 1
+            node["latest_call_id"] = r.call_id
+            dur = r.duration_ms or 0.0
+            node["total_duration_ms"] += dur
+            if dur > node["max_duration_ms"]:
+                node["max_duration_ms"] = dur
+            if dur < node["min_duration_ms"]:
+                node["min_duration_ms"] = dur
+            if r.exception:
+                node["exceptions_count"] += 1
+
+        # Group records by parent_id to build Flow Graph edges later
+        from collections import defaultdict
+        children_by_parent = defaultdict(list)
+        for r in self.records.values():
+            children_by_parent[r.parent_id].append(r)
+            
+        for parent_id, children in children_by_parent.items():
+            # Sort children chronologically by start time
+            children.sort(key=lambda x: x.start_time)
+            
+            # 1. Connect Parent to First Child
+            if parent_id and parent_id in self.records:
+                parent_record = self.records[parent_id]
+                parent_key = f"{parent_record.module}.{parent_record.qualname}" if parent_record.module else parent_record.qualname
+                first_child = children[0]
+                fc_key = f"{first_child.module}.{first_child.qualname}" if first_child.module else first_child.qualname
+                
+                edge_key = f"{parent_key} -> {fc_key}"
+                if edge_key not in edges_dict:
+                    edges_dict[edge_key] = {"source": parent_key, "target": fc_key, "count": 0}
+                edges_dict[edge_key]["count"] += 1
+
+            # 2. Connect Siblings Sequentially (Flow Edges)
+            for i in range(len(children) - 1):
+                curr_c = children[i]
+                next_c = children[i + 1]
+                curr_key = f"{curr_c.module}.{curr_c.qualname}" if curr_c.module else curr_c.qualname
+                next_key = f"{next_c.module}.{next_c.qualname}" if next_c.module else next_c.qualname
+                
+                edge_key = f"{curr_key} -> {next_key}"
+                if edge_key not in edges_dict:
+                    edges_dict[edge_key] = {"source": curr_key, "target": next_key, "count": 0}
+                edges_dict[edge_key]["count"] += 1
+
+        for node in nodes_dict.values():
+            node["avg_duration_ms"] = round(node["total_duration_ms"] / node["count"], 4) if node["count"] else 0.0
+            node["total_duration_ms"] = round(node["total_duration_ms"], 4)
+            if node["min_duration_ms"] == float("inf"):
+                node["min_duration_ms"] = 0.0
+
+        # Build chronological execution steps
+        steps = []
+        for idx, r in enumerate(all_records_list, start=1):
+            parent_key = None
+            if r["parent_id"] and r["parent_id"] in self.records:
+                pr = self.records[r["parent_id"]]
+                parent_key = f"{pr.module}.{pr.qualname}" if pr.module else pr.qualname
+
+            func_key = f"{r['module']}.{r['qualname']}" if r["module"] else r["qualname"]
+            steps.append({
+                "step_idx": idx,
+                "call_id": r["call_id"],
+                "node_id": func_key,
+                "parent_node_id": parent_key,
+                "qualname": r["qualname"],
+                "func_name": r["func_name"],
+                "module": r["module"],
+                "depth": r["depth"],
+                "duration_ms": r["duration_ms"],
+                "args_data": r["args_data"],
+                "kwargs_data": r["kwargs_data"],
+                "return_val": r["return_val"],
+                "exception": r["exception"],
+                "file_path": r["file_path"],
+                "line_no": r["line_no"],
+            })
+
+        # Identify roots and leaves
+        all_sources = {e["source"] for e in edges_dict.values()}
+        all_targets = {e["target"] for e in edges_dict.values()}
+        root_nodes = [nid for nid in nodes_dict.keys() if nid not in all_targets]
+        leaf_nodes = [nid for nid in nodes_dict.keys() if nid not in all_sources]
+
+        return {
+            "total_calls": len(self.records),
+            "total_session_ms": total_session_ms,
+            "tree": tree,
+            "flat_records": all_records_list,
+            "steps": steps,
+            "graph": {
+                "nodes": list(nodes_dict.values()),
+                "edges": list(edges_dict.values()),
+                "root_nodes": root_nodes if root_nodes else list(nodes_dict.keys())[:1],
+                "leaf_nodes": leaf_nodes if leaf_nodes else list(nodes_dict.keys())[-1:],
+            }
+        }

methodgraph/renderer.py

@@ -0,0 +1,42 @@
+import json
+import os
+import sys
+import webbrowser
+from typing import Dict, Any
+
+def render_and_save(summary_data: Dict[str, Any], output_path: str = "methodgraph_report.html") -> str:
+    """Renders the HTML report template with execution summary JSON data."""
+    template_dir = os.path.join(os.path.dirname(__file__), "templates")
+    template_path = os.path.join(template_dir, "report.html")
+    
+    if not os.path.exists(template_path):
+        raise FileNotFoundError(f"Template file missing: {template_path}")
+        
+    with open(template_path, "r", encoding="utf-8") as f:
+        template_content = f.read()
+
+    # Convert summary data to JSON
+    json_str = json.dumps(summary_data, default=str, indent=2)
+    rendered_html = template_content.replace("__DATA_PLACEHOLDER__", json_str)
+    
+    abs_output_path = os.path.abspath(output_path)
+    output_dir = os.path.dirname(abs_output_path)
+    if output_dir and not os.path.exists(output_dir):
+        os.makedirs(output_dir, exist_ok=True)
+        
+    with open(abs_output_path, "w", encoding="utf-8") as f:
+        f.write(rendered_html)
+        
+    return abs_output_path
+
+
+def open_in_browser(html_path: str):
+    """Opens the generated HTML report in the user's default browser."""
+    abs_path = os.path.abspath(html_path)
+    if os.path.exists(abs_path):
+        url = f"file://{abs_path}"
+        print(f"[methodgraph] Opening graphical report: {abs_path}")
+        webbrowser.open(url)
+    else:
+        print(f"[methodgraph] Report file not found: {abs_path}")
+

methodgraph/server.py

@@ -0,0 +1,33 @@
+import http.server
+import os
+import socketserver
+import webbrowser
+
+def serve_report(html_path: str, port: int = 8080, open_browser: bool = True):
+    """Starts a local HTTP server serving the graphical report."""
+    abs_path = os.path.abspath(html_path)
+    if not os.path.exists(abs_path):
+        print(f"[methodgraph] Error: Report path '{abs_path}' does not exist.")
+        return
+
+    directory = os.path.dirname(abs_path)
+    filename = os.path.basename(abs_path)
+
+    os.chdir(directory)
+
+    class CustomHandler(http.server.SimpleHTTPRequestHandler):
+        def do_GET(self):
+            if self.path == "/" or self.path == "":
+                self.path = f"/{filename}"
+            return super().do_GET()
+
+    with socketserver.TCPServer(("", port), CustomHandler) as httpd:
+        url = f"http://localhost:{port}/"
+        print(f"[methodgraph] Serving graphical trace viewer at {url}")
+        if open_browser:
+            webbrowser.open(url)
+        try:
+            httpd.serve_forever()
+        except KeyboardInterrupt:
+            print("\n[methodgraph] Server stopped.")
+