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.

