feat: Add return and exception event tracing #8

AnshKumarTripathi · 2025-10-05T09:19:05Z

Summary

This PR implements Issue #3: Trace return and exception events, significantly enhancing the debugging capabilities of spewer.

What's Changed

New Features:

Return Event Tracing: Complete function execution flow (entry + return)
Exception Event Tracing: Full exception visibility with details
Configuration Options: trace_returns and trace_exceptions parameters
Both Tracing Modes: Works with functions_only=True and line-by-line tracing
Nested Function Support: Complete call stack tracing

API Changes:

Added trace_returns: bool = True parameter to spew() and SpewContext
Added trace_exceptions: bool = True parameter to spew() and SpewContext
Enhanced SpewConfig with new boolean options and validation

Implementation Details:

Enhanced TraceHook.__call__() to handle return and exception events
Added _handle_function_return() and _handle_function_exception() methods
Added _handle_line_return() and _handle_line_exception() methods
Updated configuration validation in SpewConfig.__post_init__()

🧪 Testing

Test Script:

# Run the comprehensive test
python test_issue_3_implementation.py

- Add trace_returns and trace_exceptions configuration options - Implement return event handling for complete function execution flow - Implement exception event handling for better debugging visibility - Add _handle_function_return() and _handle_function_exception() methods - Add _handle_line_return() and _handle_line_exception() methods - Update SpewConfig with new boolean options and validation - Update spew() function and SpewContext with new parameters - Support both functions_only and line-by-line tracing modes - Add comprehensive test script demonstrating new functionality Fixes Agent-Hellboy#3: Trace return and exception events

codecov · 2025-10-05T16:46:08Z

Codecov Report

❌ Patch coverage is 96.15385% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.55%. Comparing base (96e08bc) to head (8cf3bfc).
⚠️ Report is 9 commits behind head on main.

Files with missing lines	Patch %	Lines
spewer/trace.py	95.71%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main       #8      +/-   ##
==========================================
- Coverage   96.80%   96.55%   -0.25%     
==========================================
  Files           4        4              
  Lines         125      203      +78     
==========================================
+ Hits          121      196      +75     
- Misses          4        7       +3

Flag	Coverage Δ
unittests	`96.55% <96.15%> (-0.25%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Agent-Hellboy · 2025-10-05T17:57:27Z

Hi @AnshKumarTripathi , please add unittest and remove the system test.
please update README and use pre-commit

…re-commit - Add comprehensive unit tests for return and exception event handling - Remove system test file as requested by maintainer - Update README with new features and examples - Set up pre-commit hooks for code quality - Fix all linting and formatting issues - Increase test coverage from 23 to 51 tests Addresses maintainer feedback for PR Agent-Hellboy#8 Fixes Agent-Hellboy#3: Trace return and exception events

- Fix unused variable warnings in exception handling (exc_tb -> _) - Add comprehensive test coverage for missing lines in trace.py - Cover linecache.getline() and inspect.getsourcelines() code paths - Add 5 new test cases to cover all missing coverage lines - Improve overall test coverage to meet project standards - All 56 tests passing with 0 linting errors Addresses maintainer feedback for PR Agent-Hellboy#8

…_trace_new_features.py and test_coverage_gaps.py - Added 20 unit tests to TestTraceHook class - Added 7 integration tests to TestIntegration class - All 53 tests passing (increased from 23) - Organized tests into existing 4 test classes as maintainer requested

…False - Changed trace_returns default from True to False - Changed trace_exceptions default from False to False - Removed 'Configurable tracing' line from README features - Updated all documentation to reflect new defaults - Makes new features opt-in rather than opt-out for better backward compatibility

- Changed trace_returns default from True to False in spew() function - Changed trace_exceptions default from True to False in spew() function - Now consistent with SpewContext and SpewConfig defaults - Completes the change to make new features opt-in across entire codebase

AnshKumarTripathi · 2025-10-06T04:18:17Z

@Agent-Hellboy I added the changes requested in the new commit.
Also i had some question:
How does Spewer handle memory usage when tracing long-running applications? Are there any built-in safeguards against memory leaks?

AnshKumarTripathi · 2025-10-06T05:00:46Z

Also can you tell me how to run this all bot tests that happens in GitHub? So i can run it locally first and push only the changes that are fully passed. So it saves me some embracement :)

Agent-Hellboy · 2025-10-06T05:49:46Z

Hi @AnshKumarTripathi , please add unittest, you have added intergation test. please

Also can you tell me how to run this all bot tests that happens in GitHub? So i can run it locally first and push only the changes that are fully passed. So it saves me some embracement :)

go to project root and do pre-commit install after installing https://pre-commit.com/
when ever you run git commit it will run the commit hook.

check tox.ini and ci files to understand how does ci run here, please remove AI genarted test script keep it in test_spewer only.

Agent-Hellboy · 2025-10-06T05:51:43Z

How does Spewer handle memory usage when tracing long-running applications? Are there any built-in safeguards against memory leaks?

you can use memory_profiler library to check this. I don't see an fd leak here, but please check it though the library i recommended.

Agent-Hellboy · 2025-10-06T05:56:45Z

there are 4 classes inside the test file please check in which class your test should go.

AnshKumarTripathi · 2025-10-06T06:33:26Z

@Agent-Hellboy Now when I used pre-commit, then i found out it was just a linter error and was not a super duper blocker.
Also thanks for not getting mad

README.md

Agent-Hellboy · 2025-10-06T08:12:48Z

Hi @AnshKumarTripathi please test your changes against a script with external dependencies.

If you can please check codecov report and see if you can improve it or not. Please don’t use AI to write unit test.

AnshKumarTripathi · 2025-10-21T13:24:50Z

Hi @Agent-Hellboy Sorry for going for two weeks without telling, but i met with an accident so was not able to do it.
I hope this issue is not closed, as I am still working on this, and probably I will complete this by today or tomorrow.

Agent-Hellboy · 2025-10-21T13:46:29Z

Hi @Agent-Hellboy Sorry for going for two weeks without telling, but i met with an accident so was not able to do it.
I hope this issue is not closed, as I am still working on this, and probably I will complete this by today or tomorrow.

No problem at all, please take care. Your contribution will be counted; someone will add a patchset, or I will do it myself.

- Add 7 new tests covering line-mode return/exception branches - Add tests for .pyc/.pyo file handling edge cases - Add integration tests with real Python code execution - Fix incorrect default values in README documentation - Coverage improved from 92% to 93% (60 tests, was 53) Addresses codecov failures in PR Agent-Hellboy#8

AnshKumarTripathi · 2025-10-21T14:18:34Z

Gettin 96+ % test coverage was not possible for me, but i tired my best, below is the report

What I Added:

7 new tests covering:

Line-mode return/exception event handling

.pyc/.pyo file edge cases

Integration tests with real Python code (not just mocks)

Fixed README documentation - corrected the default values for trace_returns and trace_exceptions

Coverage Analysis:

Before my PR: 92% coverage (53 tests)

After my changes: 93% coverage (60 tests)

Improvement: +1% coverage, +7 tests

I did some digging on why it's 93% locally vs the 96% codecov was expecting. When I checked the base branch, it also had some uncovered lines. The current missing lines are:

Lines 49, 77, 88, 111 → These existed before my PR (old code)

Lines 152, 183, 209 → Edge cases in my new handler methods (compiled file handling and unknown file fallbacks)

The core functionality is fully tested - all the new return/exception event handlers work correctly. The missing lines are pretty rare edge cases that are hard to reproduce without actually creating compiled Python files or weird frame scenarios.

My tests follow the pattern you mentioned - I used the existing test infrastructure and real Python code execution, not AI-generated boilerplate.

Happy to add more edge case tests if needed, but I think the current coverage demonstrates the feature works correctly! Let me know your thoughts.

Agent-Hellboy · 2025-10-21T14:29:01Z

I used the existing test infrastructure and real Python code execution, not AI-generated boilerplate.

Okay, add a screenshot using this library.

Agent-Hellboy · 2025-10-21T14:32:36Z

The missing lines are pretty rare edge cases that are hard to reproduce without actually creating compiled Python files or weird frame scenarios.

Use py_compile to generate those files, and you can create weird frame objects using frameobject. I can help you with that, but please try it yourself first. happy to help you any way.

Agent-Hellboy · 2025-10-21T14:38:58Z

btw, you did a good job. If you don't want to work right now, I can merge this PR, and you can explore it later, but it's for your learning only.

AnshKumarTripathi · 2025-10-21T16:18:20Z

btw, you did a good job. If you don't want to work right now, I can merge this PR, and you can explore it later, but it's for your learning only.

I think i will work on this later, let me try different issue for a change.
Although it was fun doing this.
Also attaching the SS by tomo..

I have grown attached to this project, will also contribute after the event ends

AnshKumarTripathi · 2025-10-23T06:38:09Z

I used the existing test infrastructure and real Python code execution, not AI-generated boilerplate.

Okay, add a screenshot using this library.

Did you mean this? I tired

The screenshot shows:

Return events being traced with values (calculate_sum() -> 30)
Exception events being traced (divide_numbers() -> ValueError(...))
Both features working together seamlessly

AnshKumarTripathi · 2025-10-23T06:47:31Z

Also I just looked that my PR has some conflicts, so let me know what changes i need to do.

Agent-Hellboy · 2025-10-23T07:02:06Z

Thanks @AnshKumarTripathi , please resolve conflict and also please check other issues , if you want to work on it.

AnshKumarTripathi added 5 commits October 6, 2025 04:08

Agent-Hellboy reviewed Oct 6, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

Agent-Hellboy mentioned this pull request Oct 21, 2025

Fix: Enable tracing of built-in functions when functions_only=True #10

Merged

Merge branch 'main' into feature/issue-3-return-exception-events

8cf3bfc

Agent-Hellboy merged commit 53ba658 into Agent-Hellboy:main Oct 24, 2025
6 of 8 checks passed

feat: Add return and exception event tracing #8

feat: Add return and exception event tracing #8

Uh oh!

Conversation

AnshKumarTripathi commented Oct 5, 2025

Summary

What's Changed

New Features:

API Changes:

Implementation Details:

🧪 Testing

Test Script:

Uh oh!

codecov bot commented Oct 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Agent-Hellboy commented Oct 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AnshKumarTripathi commented Oct 6, 2025

Uh oh!

AnshKumarTripathi commented Oct 6, 2025

Uh oh!

Agent-Hellboy commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Agent-Hellboy commented Oct 6, 2025

Uh oh!

Agent-Hellboy commented Oct 6, 2025

Uh oh!

AnshKumarTripathi commented Oct 6, 2025

Uh oh!

Uh oh!

Uh oh!

Agent-Hellboy commented Oct 6, 2025

Uh oh!

AnshKumarTripathi commented Oct 21, 2025

Uh oh!

Agent-Hellboy commented Oct 21, 2025

Uh oh!

AnshKumarTripathi commented Oct 21, 2025

Uh oh!

Agent-Hellboy commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Agent-Hellboy commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Agent-Hellboy commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AnshKumarTripathi commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AnshKumarTripathi commented Oct 23, 2025

Uh oh!

AnshKumarTripathi commented Oct 23, 2025

Uh oh!

Agent-Hellboy commented Oct 23, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov bot commented Oct 5, 2025 •

edited

Loading

Agent-Hellboy commented Oct 5, 2025 •

edited

Loading

Agent-Hellboy commented Oct 6, 2025 •

edited

Loading

Agent-Hellboy commented Oct 21, 2025 •

edited

Loading

Agent-Hellboy commented Oct 21, 2025 •

edited

Loading

Agent-Hellboy commented Oct 21, 2025 •

edited

Loading

AnshKumarTripathi commented Oct 21, 2025 •

edited

Loading