traceflow-py 1.2.0__py3-none-any.whl

traceflow/__init__.py

@@ -0,0 +1,22 @@
+"""
+TraceFlow — A lightweight Python decorator for visually tracing function execution.
+
+Usage:
+    from traceflow import watch
+
+    @watch()
+    def my_function(x):
+        return x * 2
+
+Global controls:
+    import traceflow
+    traceflow.disable()
+    traceflow.enable()
+    traceflow.is_enabled()
+"""
+
+from traceflow.core import watch, enable, disable, is_enabled
+
+__version__ = "1.2.0"
+__author__ = "Aarav Agarwal"
+__all__ = ["watch", "enable", "disable", "is_enabled"]

traceflow/core.py

@@ -0,0 +1,227 @@
+"""
+Core implementation of the TraceFlow @watch decorator.
+
+This module contains all tracing logic: call tree rendering, timing,
+variable state tracking, truncation, exception handling, and async support.
+"""
+
+import functools
+import contextvars
+import inspect
+import time as _time
+import sys as _sys
+
+# ── Global State ────────────────────────────────────────────────
+
+_depth = contextvars.ContextVar('depth', default=0)
+_enabled = True
+
+
+def enable():
+    """Enable all tracing globally."""
+    global _enabled
+    _enabled = True
+
+
+def disable():
+    """Disable all tracing globally. Decorated functions still execute normally."""
+    global _enabled
+    _enabled = False
+
+
+def is_enabled():
+    """Return whether tracing is currently enabled."""
+    return _enabled
+
+
+# ── Decorator ───────────────────────────────────────────────────
+
+def watch(func=None, *, track_time=True, truncate_len=50, max_depth=None, export_path=None, track_vars=False):
+    """
+    Decorator that traces function calls, producing an indented call tree.
+
+    Args:
+        track_time (bool): Append execution time to each return line. Default True.
+        truncate_len (int): Max characters for argument/return repr. 0 or None to disable.
+        max_depth (int): Stop tracing beyond this call depth. None for unlimited.
+        export_path (str): Write trace output to this file instead of stdout.
+        track_vars (bool): Log local variable assignments inside the function (sync only).
+
+    Returns:
+        The decorated function (sync or async wrapper).
+
+    Example::
+
+        @watch(track_time=True)
+        def fibonacci(n):
+            if n <= 1:
+                return n
+            return fibonacci(n - 1) + fibonacci(n - 2)
+
+        fibonacci(3)
+        # fibonacci(3)
+        # ├── fibonacci(2)
+        # │   ├── fibonacci(1)
+        # │   │   └── return 1 [0.0003s]
+        # │   ├── fibonacci(0)
+        # │   │   └── return 0 [0.0000s]
+        # │   └── return 1 [0.0006s]
+        # ├── fibonacci(1)
+        # │   └── return 1 [0.0000s]
+        # └── return 2 [0.0008s]
+    """
+    if func is None:
+        return functools.partial(watch, track_time=track_time, truncate_len=truncate_len,
+                                 max_depth=max_depth, export_path=export_path, track_vars=track_vars)
+
+    # ── Helpers ─────────────────────────────────────────────────
+
+    def _get_repr(val):
+        """Return a repr string for *val*, truncated to *truncate_len* characters."""
+        s = repr(val)
+        if truncate_len and len(s) > truncate_len:
+            s = s[:truncate_len - 3] + "..."
+        return s
+
+    def _log(msg):
+        """Print to console or append to file."""
+        if export_path:
+            try:
+                with open(export_path, "a", encoding="utf-8") as f:
+                    f.write(msg + "\n")
+            except Exception:
+                pass
+        else:
+            print(msg)
+
+    def _prefix(depth):
+        """Build the tree prefix for a child node at the given depth."""
+        if depth == 0:
+            return ""
+        return "│   " * (depth - 1) + "├── "
+
+    def _continuation(depth):
+        """Build the continuation (vertical lines) for content at the given depth."""
+        return "│   " * depth
+
+    # ── Trace entry / exit ──────────────────────────────────────
+
+    def _trace_call(args, kwargs, depth):
+        """Print the function call line and return start_time."""
+        pos_args = [_get_repr(a) for a in args]
+        kw_args = [f"{k}={_get_repr(v)}" for k, v in kwargs.items()]
+        all_args = ", ".join(pos_args + kw_args)
+        call_str = f"{func.__name__}({all_args})"
+        _log(f"{_prefix(depth)}{call_str}")
+        return _time.perf_counter() if track_time else None
+
+    def _trace_return(depth, start_time, result=None, exc=None):
+        """Print the return/exception line as the last child of the call."""
+        elapsed = f" [{_time.perf_counter() - start_time:.4f}s]" if (track_time and start_time) else ""
+        ret_prefix = _continuation(depth) + "└── "
+        if exc is not None:
+            _log(f"{ret_prefix}{type(exc).__name__}: {str(exc)}{elapsed}")
+        else:
+            _log(f"{ret_prefix}return {_get_repr(result)}{elapsed}")
+
+    # ── Variable state tracking (sys.settrace) ──────────────────
+
+    def _make_var_tracer(depth):
+        """Create a sys.settrace local tracer for variable state tracking."""
+        var_prefix = _continuation(depth) + "│   "
+        prev_locals = [None]  # None = first snapshot not yet captured
+        target_code = func.__code__
+
+        def local_tracer(frame, event, arg):
+            if event == 'line':
+                current = {}
+                for k, v in frame.f_locals.items():
+                    if k.startswith('_'):
+                        continue
+                    try:
+                        current[k] = _get_repr(v)
+                    except Exception:
+                        current[k] = '<repr error>'
+
+                if prev_locals[0] is None:
+                    # First line event — capture parameters as baseline, don't log them
+                    prev_locals[0] = current
+                else:
+                    for k, v in current.items():
+                        if k not in prev_locals[0] or prev_locals[0][k] != v:
+                            _log(f"{var_prefix}· {k} = {v}")
+                    prev_locals[0] = current
+            return local_tracer
+
+        def global_tracer(frame, event, arg):
+            if event == 'call' and frame.f_code is target_code:
+                return local_tracer
+            return None
+
+        return global_tracer
+
+    # ── Wrapper selection ───────────────────────────────────────
+
+    if inspect.iscoroutinefunction(func):
+        @functools.wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            if not _enabled:
+                return await func(*args, **kwargs)
+
+            depth = _depth.get()
+            if max_depth is not None and depth >= max_depth:
+                token = _depth.set(depth + 1)
+                try:
+                    return await func(*args, **kwargs)
+                finally:
+                    _depth.reset(token)
+
+            start_time = _trace_call(args, kwargs, depth)
+            token = _depth.set(depth + 1)
+            # track_vars not supported for async (sys.settrace is thread-level)
+            try:
+                result = await func(*args, **kwargs)
+                _depth.reset(token)
+                _trace_return(depth, start_time, result=result)
+                return result
+            except Exception as e:
+                _depth.reset(token)
+                _trace_return(depth, start_time, exc=e)
+                raise
+        return async_wrapper
+    else:
+        @functools.wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            if not _enabled:
+                return func(*args, **kwargs)
+
+            depth = _depth.get()
+            if max_depth is not None and depth >= max_depth:
+                token = _depth.set(depth + 1)
+                try:
+                    return func(*args, **kwargs)
+                finally:
+                    _depth.reset(token)
+
+            start_time = _trace_call(args, kwargs, depth)
+            token = _depth.set(depth + 1)
+
+            if track_vars:
+                old_trace = _sys.gettrace()
+                _sys.settrace(_make_var_tracer(depth))
+
+            try:
+                result = func(*args, **kwargs)
+            except Exception as e:
+                if track_vars:
+                    _sys.settrace(old_trace)
+                _depth.reset(token)
+                _trace_return(depth, start_time, exc=e)
+                raise
+            else:
+                if track_vars:
+                    _sys.settrace(old_trace)
+                _depth.reset(token)
+                _trace_return(depth, start_time, result=result)
+                return result
+        return sync_wrapper

traceflow_py-1.2.0.dist-info/METADATA

@@ -0,0 +1,409 @@
+Metadata-Version: 2.4
+Name: traceflow-py
+Version: 1.2.0
+Summary: A lightweight decorator for visually tracing Python function calls with indented call trees, timing, variable tracking, and async support.
+Author: Aarav Agarwal
+License: All Rights Reserved
+Project-URL: Homepage, https://github.com/Firestar3/TraceFlow
+Project-URL: Repository, https://github.com/Firestar3/TraceFlow
+Project-URL: Bug Tracker, https://github.com/Firestar3/TraceFlow/issues
+Keywords: tracing,debugging,decorator,call-tree,profiling,recursion,async,logging
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# TraceFlow
+
+**TraceFlow** is a lightweight, zero-dependency Python decorator library for visually tracing function execution. It renders beautiful, indented call trees directly to your console — making debugging recursive, nested, and async code effortless.
+
+```
+fibonacci(3)
+├── fibonacci(2)
+│   ├── fibonacci(1)
+│   │   └── return 1 [0.0003s]
+│   ├── fibonacci(0)
+│   │   └── return 0 [0.0000s]
+│   └── return 1 [0.0006s]
+├── fibonacci(1)
+│   └── return 1 [0.0000s]
+└── return 2 [0.0008s]
+```
+
+---
+
+## Features
+
+| Feature | Description |
+|---|---|
+| 🌳 **Call Trees** | Nested, indented tree visualization for every function call |
+| ⏱️ **Execution Time** | Per-call timing with `[0.0042s]` annotations |
+| 📐 **Truncation** | Smart character-limit truncation for large arguments and returns |
+| 💥 **Exception Tracing** | Captures and renders exceptions inline in the call tree |
+| 🔁 **Async Support** | Safely traces `async`/`await` functions and `asyncio.gather` |
+| 🔒 **Depth Limiting** | Cap tracing depth with `max_depth` to reduce noise |
+| 📁 **File Export** | Redirect trace output to a file instead of the console |
+| 🔇 **Global Toggle** | `traceflow.disable()` / `traceflow.enable()` to control all tracing at runtime |
+| 🔬 **Variable Tracking** | `track_vars=True` to log every local variable assignment inside a function |
+
+---
+
+## Installation
+
+```bash
+# Clone the repo
+git clone https://github.com/Firestar3/TraceFlow.git
+cd TraceFlow
+
+# Install locally
+pip install .
+```
+
+Or simply drop the `traceflow/` folder into your project — no dependencies required.
+
+---
+
+## Quick Start
+
+```python
+from traceflow import watch
+
+@watch()
+def fibonacci(n):
+    if n <= 1:
+        return n
+    return fibonacci(n - 1) + fibonacci(n - 2)
+
+fibonacci(3)
+```
+
+**Output:**
+```
+fibonacci(3)
+├── fibonacci(2)
+│   ├── fibonacci(1)
+│   │   └── return 1 [0.0003s]
+│   ├── fibonacci(0)
+│   │   └── return 0 [0.0000s]
+│   └── return 1 [0.0006s]
+├── fibonacci(1)
+│   └── return 1 [0.0000s]
+└── return 2 [0.0008s]
+```
+
+---
+
+## Feature Guide
+
+### 1. Execution Time Tracking
+
+Every traced call automatically measures wall-clock time.
+
+```python
+from traceflow import watch
+import time
+
+@watch(track_time=True)
+def slow_add(a, b):
+    time.sleep(0.05)
+    return a + b
+
+slow_add(10, 20)
+```
+
+```
+slow_add(10, 20)
+└── return 30 [0.0502s]
+```
+
+Set `track_time=False` to disable timing:
+
+```python
+@watch(track_time=False)
+def add(a, b):
+    return a + b
+
+add(1, 2)
+```
+
+```
+add(1, 2)
+└── return 3
+```
+
+---
+
+### 2. Argument & Return Truncation
+
+Prevent massive data structures from flooding your console with `truncate_len`.
+
+```python
+@watch(truncate_len=30)
+def process(data):
+    return [x * 2 for x in data]
+
+process(list(range(50)))
+```
+
+```
+process([0, 1, 2, 3, 4, 5, 6, 7, 8,...)
+└── return [0, 2, 4, 6, 8, 10, 12, 14,... [0.0000s]
+```
+
+The character limit applies to both arguments and return values. Set `truncate_len=None` or `truncate_len=0` to disable truncation entirely.
+
+---
+
+### 3. Exception Tracing
+
+Exceptions are captured, rendered in the tree, and re-raised — so your error handling works normally while you get full visibility.
+
+```python
+@watch()
+def divide(a, b):
+    return a / b
+
+@watch()
+def safe_math(x, y):
+    return divide(x, y)
+
+try:
+    safe_math(10, 0)
+except ZeroDivisionError:
+    pass
+```
+
+```
+safe_math(10, 0)
+├── divide(10, 0)
+│   └── ZeroDivisionError: division by zero [0.0000s]
+└── ZeroDivisionError: division by zero [0.0000s]
+```
+
+The exception propagates through each level of the call tree, showing exactly where it originated and how it bubbled up.
+
+---
+
+### 4. Max Depth Limiting
+
+Reduce noise in deeply recursive functions by capping the trace depth.
+
+```python
+@watch(max_depth=2)
+def deep_fib(n):
+    if n <= 1:
+        return n
+    return deep_fib(n - 1) + deep_fib(n - 2)
+
+deep_fib(4)
+```
+
+```
+deep_fib(4)
+├── deep_fib(3)
+│   └── return 2 [0.0000s]
+├── deep_fib(2)
+│   └── return 1 [0.0000s]
+└── return 3 [0.0000s]
+```
+
+Calls beyond `max_depth` still execute normally — they just aren't traced.
+
+---
+
+### 5. Async Function Support
+
+TraceFlow natively supports `async` functions. Concurrent tasks from `asyncio.gather` are traced cleanly.
+
+```python
+import asyncio
+from traceflow import watch
+
+@watch()
+async def fetch_data(id):
+    await asyncio.sleep(0.01)
+    return f"data_{id}"
+
+@watch()
+async def fetch_all():
+    return await asyncio.gather(fetch_data(1), fetch_data(2), fetch_data(3))
+
+asyncio.run(fetch_all())
+```
+
+```
+fetch_all()
+├── fetch_data(1)
+│   └── return 'data_1' [0.0123s]
+├── fetch_data(2)
+│   └── return 'data_2' [0.0123s]
+├── fetch_data(3)
+│   └── return 'data_3' [0.0123s]
+└── return ['data_1', 'data_2', 'data_3'] [0.0126s]
+```
+
+---
+
+### 6. File Export
+
+Redirect all trace output to a text file instead of the console.
+
+```python
+@watch(export_path="trace_output.txt")
+def fibonacci(n):
+    if n <= 1:
+        return n
+    return fibonacci(n - 1) + fibonacci(n - 2)
+
+fibonacci(3)
+# -> Trace written to trace_output.txt
+```
+
+The file is appended to, so multiple runs accumulate in the same file.
+
+---
+
+### 7. Global Enable / Disable
+
+Turn all tracing on or off at runtime without removing decorators. Functions still execute normally when tracing is disabled — only the output is suppressed.
+
+```python
+import traceflow
+from traceflow import watch
+
+@watch()
+def add(a, b):
+    return a + b
+
+add(1, 2)           # Trace is printed
+
+traceflow.disable()
+add(3, 4)           # No trace output, but returns 7 normally
+
+traceflow.enable()
+add(5, 6)           # Trace resumes
+```
+
+```
+add(1, 2)
+└── return 3 [0.0000s]
+
+add(5, 6)
+└── return 11 [0.0000s]
+```
+
+Also available: `traceflow.is_enabled()` to check current state.
+
+---
+
+### 8. Variable State Tracking
+
+See exactly how local variables change inside a function, line by line. Parameters are captured as a baseline and not logged (they're already visible in the call signature).
+
+```python
+@watch(track_vars=True)
+def compute(x, y):
+    total = x + y
+    doubled = total * 2
+    message = f"Result: {doubled}"
+    return doubled
+
+compute(5, 3)
+```
+
+```
+compute(5, 3)
+│   · total = 8
+│   · doubled = 16
+│   · message = 'Result: 16'
+└── return 16 [0.0002s]
+```
+
+Variable tracking inside a loop:
+
+```python
+@watch(track_vars=True)
+def sum_list(items):
+    total = 0
+    for val in items:
+        total += val
+    return total
+
+sum_list([10, 20, 30])
+```
+
+```
+sum_list([10, 20, 30])
+│   · total = 0
+│   · val = 10
+│   · total = 10
+│   · val = 20
+│   · total = 30
+│   · val = 30
+│   · total = 60
+└── return 60 [0.0001s]
+```
+
+> **Note:** Variable tracking uses `sys.settrace` and is only available for synchronous functions. It adds overhead and is best used for targeted debugging, not production code.
+
+---
+
+### 9. Keyword Arguments
+
+TraceFlow displays both positional and keyword arguments.
+
+```python
+@watch()
+def greet(name, greeting="Hello", punctuation="!"):
+    return f"{greeting}, {name}{punctuation}"
+
+greet("Aarav", greeting="Hey", punctuation="!!")
+```
+
+```
+greet('Aarav', greeting='Hey', punctuation='!!')
+└── return 'Hey, Aarav!!' [0.0000s]
+```
+
+---
+
+## Configuration Reference
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `track_time` | `bool` | `True` | Append `[0.0042s]` execution time to each return line |
+| `truncate_len` | `int` | `50` | Max characters for argument/return repr. `0` or `None` to disable |
+| `max_depth` | `int` | `None` | Stop tracing beyond this call depth. `None` for unlimited |
+| `export_path` | `str` | `None` | Write trace to a file instead of stdout |
+| `track_vars` | `bool` | `False` | Log local variable assignments inside the function (sync only) |
+
+### Global Functions
+
+| Function | Description |
+|---|---|
+| `traceflow.enable()` | Enable all tracing (default state) |
+| `traceflow.disable()` | Disable all tracing — decorated functions still run normally |
+| `traceflow.is_enabled()` | Returns `True` if tracing is currently active |
+
+---
+
+## Author
+
+**Aarav Agarwal**
+
+## License
+
+All Rights Reserved.

traceflow_py-1.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+traceflow/__init__.py,sha256=rdrpNy3Ha-bXsK77HX3BfKYX-puf24PR5cnUrBrRtD4,476
+traceflow/core.py,sha256=yttjGSbLDl_NPcXNuN651ePfmVM2G-57oOqExPSaMrM,8546
+traceflow_py-1.2.0.dist-info/licenses/LICENSE,sha256=XD4Y9VNyR0ZiCXGbFwyV0JmVnsxGb6m88KVOyK-Ah-c,470
+traceflow_py-1.2.0.dist-info/METADATA,sha256=njO7m0_g8YQVSm-yj-x7P_S4oLJ8ie7ifPGwlPEAVtM,10053
+traceflow_py-1.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+traceflow_py-1.2.0.dist-info/top_level.txt,sha256=SqOQaaNe15Fx2bMjjT4p-KNgKl2MqxAQVJT5ocAXjZo,10
+traceflow_py-1.2.0.dist-info/RECORD,,

traceflow_py-1.2.0.dist-info/WHEEL

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

traceflow_py-1.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,11 @@
+All Rights Reserved
+
+Copyright (c) 2025 Aarav Agarwal
+
+This software and associated documentation files (the "Software") may not be
+copied, modified, merged, published, distributed, sublicensed, or sold without
+the express written permission of the copyright holder.
+
+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.

traceflow_py-1.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+traceflow