Merge pull request #8 from AnshKumarTripathi/feature/issue-3-return-exception-events

feat: Add return and exception event tracing

Author: Agent-Hellboy

README.md

@@ -11,6 +11,8 @@ A Python debugging library for detailed code execution tracing. This library pro
 
 - **Line-by-line execution tracing**: See exactly which lines are being executed
 - **Function/method call tracing**: Trace only function and method calls without line details
+- **Return event tracing**: Track function return values and completion
+- **Exception event tracing**: Monitor exception raising and handling
 - **Variable value inspection**: View the values of variables at each execution step
 - **Module filtering**: Trace only specific modules or all modules
 - **Context manager support**: Use with `with` statements for automatic cleanup
@@ -119,20 +121,87 @@ This will output:
 ```
 __main__:15: my_function()
     args: x=10, y=20
+__main__:17: my_function() -> 30
+```
+
+### Return Event Tracing
+
+```python
+from spewer import SpewContext
+
+# Trace function calls and returns
+with SpewContext(functions_only=True, show_values=True, trace_returns=True):
+    def calculate(x, y):
+        return x * y + 10
+
+    result = calculate(5, 3)
+```
+
+This will output:
+```
+__main__:15: calculate()
+    args: x=5, y=3
+__main__:16: calculate() -> 25
+```
+
+### Exception Event Tracing
+
+```python
+from spewer import SpewContext
+
+# Trace function calls and exceptions
+with SpewContext(functions_only=True, show_values=True, trace_exceptions=True):
+    def risky_function(x, y):
+        if y == 0:
+            raise ValueError("Cannot divide by zero")
+        return x / y
+
+    try:
+        result = risky_function(10, 0)
+    except ValueError as e:
+        print(f"Caught: {e}")
+```
+
+This will output:
+```
+__main__:15: risky_function()
+    args: x=10, y=0
+__main__:16: risky_function() -> ValueError('Cannot divide by zero')
+```
+
+### Disable Specific Event Types
+
+```python
+from spewer import SpewContext
+
+# Only trace function calls, not returns or exceptions
+with SpewContext(functions_only=True, trace_returns=False, trace_exceptions=False):
+    def my_function():
+        return 42
+
+    result = my_function()
+```
+
+This will output:
+```
+__main__:15: my_function()
+# No return event traced
 ```
 
 ## API Reference
 
 ### Functions
 
-#### `spew(trace_names=None, show_values=False, functions_only=False)`
+#### `spew(trace_names=None, show_values=False, functions_only=False, trace_returns=False, trace_exceptions=False)`
 
 Install a trace hook which writes detailed logs about code execution.
 
 **Parameters:**
 - `trace_names` (Optional[List[str]]): List of module names to trace. If None, traces all modules.
-- `show_values` (bool): Whether to show variable values during tracing.
-- `functions_only` (bool): Whether to trace only function/method calls instead of line-by-line execution.
+- `show_values` (bool): Whether to show variable values during tracing. Default: False.
+- `functions_only` (bool): Whether to trace only function/method calls instead of line-by-line execution. Default: False.
+- `trace_returns` (bool): Whether to trace function return events. Default: False.
+- `trace_exceptions` (bool): Whether to trace exception events. Default: False.
 
 #### `unspew()`
 
@@ -142,23 +211,27 @@ Remove the trace hook installed by `spew()`.
 
 
 
-#### `SpewContext(trace_names=None, show_values=False, functions_only=False)`
+#### `SpewContext(trace_names=None, show_values=False, functions_only=False, trace_returns=False, trace_exceptions=False)`
 
 Context manager for automatic spew/unspew operations.
 
 **Parameters:**
 - `trace_names` (Optional[List[str]]): List of module names to trace. If None, traces all modules.
-- `show_values` (bool): Whether to show variable values during tracing.
-- `functions_only` (bool): Whether to trace only function/method calls instead of line-by-line execution.
+- `show_values` (bool): Whether to show variable values during tracing. Default: False.
+- `functions_only` (bool): Whether to trace only function/method calls instead of line-by-line execution. Default: False.
+- `trace_returns` (bool): Whether to trace function return events. Default: False.
+- `trace_exceptions` (bool): Whether to trace exception events. Default: False.
 
-#### `SpewConfig(trace_names=None, show_values=True, functions_only=False)`
+#### `SpewConfig(trace_names=None, show_values=True, functions_only=False, trace_returns=False, trace_exceptions=False)`
 
 Configuration class for spewer debugging. Provides validation and centralized configuration management.
 
 **Parameters:**
 - `trace_names` (Optional[List[str]]): List of module names to trace. If None, traces all modules.
-- `show_values` (bool): Whether to show variable values during tracing.
-- `functions_only` (bool): Whether to trace only function/method calls instead of line-by-line execution.
+- `show_values` (bool): Whether to show variable values during tracing. Default: True.
+- `functions_only` (bool): Whether to trace only function/method calls instead of line-by-line execution. Default: False.
+- `trace_returns` (bool): Whether to trace function return events. Default: False.
+- `trace_exceptions` (bool): Whether to trace exception events. Default: False.
 
 #### `TraceHook(config)`
 
@@ -169,6 +242,8 @@ Core trace hook implementation. This is the low-level class that handles the act
 
 ## Example Output
 
+### Line-by-Line Tracing
+
 When tracing with `show_values=True`, you'll see output like:
 
 ```
@@ -182,6 +257,20 @@ __main__:18: print(f"Result: {result}")
     result=30
 ```
 
+### Function-Only Tracing with Returns and Exceptions
+
+When tracing with `functions_only=True, show_values=True, trace_returns=True, trace_exceptions=True`:
+
+```
+__main__:15: calculate()
+    args: x=10, y=5
+__main__:16: calculate() -> 15
+
+__main__:20: risky_function()
+    args: x=10, y=0
+__main__:22: risky_function() -> ValueError('division by zero')
+```
+
 ## Notes
 
 - The library uses Python's `sys.settrace()` which can impact performance

spewer/config.py

@@ -13,6 +13,8 @@ class SpewConfig:
     trace_names: Optional[list[str]] = None
     show_values: bool = True
     functions_only: bool = False
+    trace_returns: bool = False
+    trace_exceptions: bool = False
 
     def __post_init__(self):
         """Validate configuration after initialization."""
@@ -27,3 +29,11 @@ def __post_init__(self):
         if not isinstance(self.functions_only, bool):
             msg = "functions_only must be a boolean"
             raise TypeError(msg)
+
+        if not isinstance(self.trace_returns, bool):
+            msg = "trace_returns must be a boolean"
+            raise TypeError(msg)
+
+        if not isinstance(self.trace_exceptions, bool):
+            msg = "trace_exceptions must be a boolean"
+            raise TypeError(msg)

spewer/spewer.py

@@ -13,12 +13,16 @@ def spew(
     trace_names: Optional[list[str]] = None,
     show_values: bool = False,
     functions_only: bool = False,
+    trace_returns: bool = False,
+    trace_exceptions: bool = False,
 ) -> None:
     """Install a trace hook for detailed code execution logging."""
     config = SpewConfig(
         trace_names=trace_names,
         show_values=show_values,
         functions_only=functions_only,
+        trace_returns=trace_returns,
+        trace_exceptions=trace_exceptions,
     )
     hook = TraceHook(config)
 
@@ -43,18 +47,24 @@ def __init__(
         trace_names: Optional[list[str]] = None,
         show_values: bool = False,
         functions_only: bool = False,
+        trace_returns: bool = False,
+        trace_exceptions: bool = False,
     ):
         self.config = SpewConfig(
             trace_names=trace_names,
             show_values=show_values,
             functions_only=functions_only,
+            trace_returns=trace_returns,
+            trace_exceptions=trace_exceptions,
         )
 
     def __enter__(self):
         spew(
             self.config.trace_names,
             self.config.show_values,
             self.config.functions_only,
+            self.config.trace_returns,
+            self.config.trace_exceptions,
         )
         return self
 

spewer/trace.py

@@ -26,6 +26,10 @@ def __call__(self, frame: Any, event: str, arg: Any) -> TraceHook:
             self._handle_function_call(frame, event, arg)
         elif not self.config.functions_only and event == "line":
             self._handle_line_execution(frame)
+        elif event == "return" and self.config.trace_returns:
+            self._handle_line_return(frame, arg)
+        elif event == "exception" and self.config.trace_exceptions:
+            self._handle_line_exception(frame, arg)
 
         return self
 
@@ -118,3 +122,105 @@ def _show_variable_values(self, frame: Any, line: str) -> None:
 
         if details:
             print(f"\t{' '.join(details)}")
+
+    def _handle_function_return(self, frame: Any, arg: Any) -> None:
+        """Handle function return events."""
+        lineno = frame.f_lineno
+        func_name = frame.f_code.co_name
+
+        # Get filename and handle compiled files
+        if "__file__" in frame.f_globals:
+            filename = frame.f_globals["__file__"]
+            if filename.endswith((".pyc", ".pyo")):
+                filename = filename[:-1]
+            name = frame.f_globals["__name__"]
+        else:
+            name = "[unknown]"
+            filename = "[unknown]"
+
+        # Check if we should trace this module
+        if self.config.trace_names is None or name in self.config.trace_names:
+            if self.config.show_values:
+                print(f"{name}:{lineno}: {func_name}() -> {arg!r}")
+            else:
+                print(f"{name}:{lineno}: {func_name}() -> <return>")
+
+    def _handle_function_exception(self, frame: Any, arg: Any) -> None:
+        """Handle function exception events."""
+        lineno = frame.f_lineno
+        func_name = frame.f_code.co_name
+
+        # Get filename and handle compiled files
+        if "__file__" in frame.f_globals:
+            filename = frame.f_globals["__file__"]
+            if filename.endswith((".pyc", ".pyo")):
+                filename = filename[:-1]
+            name = frame.f_globals["__name__"]
+        else:
+            name = "[unknown]"
+            filename = "[unknown]"
+
+        # Check if we should trace this module
+        if self.config.trace_names is None or name in self.config.trace_names:
+            if self.config.show_values:
+                exc_type, exc_value, _ = arg
+                print(
+                    f"{name}:{lineno}: {func_name}() -> {exc_type.__name__}({exc_value!r})"
+                )
+            else:
+                print(f"{name}:{lineno}: {func_name}() -> <exception>")
+
+    def _handle_line_return(self, frame: Any, arg: Any) -> None:
+        """Handle line return events."""
+        lineno = frame.f_lineno
+
+        # Get filename and handle compiled files
+        if "__file__" in frame.f_globals:
+            filename = frame.f_globals["__file__"]
+            if filename.endswith((".pyc", ".pyo")):
+                filename = filename[:-1]
+            name = frame.f_globals["__name__"]
+            line = linecache.getline(filename, lineno)
+        else:
+            name = "[unknown]"
+            try:
+                src = inspect.getsourcelines(frame)
+                line = src[lineno]
+            except OSError:
+                line = f"Unknown code named [{frame.f_code.co_name}]. VM instruction #{frame.f_lasti}"
+
+        # Check if we should trace this module
+        if self.config.trace_names is None or name in self.config.trace_names:
+            if self.config.show_values:
+                print(f"{name}:{lineno}: {line.rstrip()} -> {arg!r}")
+            else:
+                print(f"{name}:{lineno}: {line.rstrip()} -> <return>")
+
+    def _handle_line_exception(self, frame: Any, arg: Any) -> None:
+        """Handle line exception events."""
+        lineno = frame.f_lineno
+
+        # Get filename and handle compiled files
+        if "__file__" in frame.f_globals:
+            filename = frame.f_globals["__file__"]
+            if filename.endswith((".pyc", ".pyo")):
+                filename = filename[:-1]
+            name = frame.f_globals["__name__"]
+            line = linecache.getline(filename, lineno)
+        else:
+            name = "[unknown]"
+            try:
+                src = inspect.getsourcelines(frame)
+                line = src[lineno]
+            except OSError:
+                line = f"Unknown code named [{frame.f_code.co_name}]. VM instruction #{frame.f_lasti}"
+
+        # Check if we should trace this module
+        if self.config.trace_names is None or name in self.config.trace_names:
+            if self.config.show_values:
+                exc_type, exc_value, _ = arg
+                print(
+                    f"{name}:{lineno}: {line.rstrip()} -> {exc_type.__name__}({exc_value!r})"
+                )
+            else:
+                print(f"{name}:{lineno}: {line.rstrip()} -> <exception>")