Finally, a Debugger That Remembers What Your Variables Were

You know the drill. Your function runs, something breaks, and by the time you've added a print statement or fired up pdb, the values you actually cared about are gone. You step through the code, but you're stepping through lines, not through the logic you wrote. birdseye takes a different approach: it records the values of expressions during a function call and lets you inspect them after the function has already finished.

What It Does

birdseye is a Python debugger that captures the values of expressions inside a function call and lets you view them afterward. You install it with pip, add an @eye decorator to a function, and run your code however you normally would. When you want to see what happened, you open the results in your browser.

The key architectural choice here is that birdseye doesn't ask you to run your code in a special way. It works whether you're running a script, firing off a test, or executing a notebook cell. The decorator is the only change you need to make. It supports Python 3.8 and above.

Rather than the traditional step-through-lines model, birdseye organizes results by function calls, grouped into files and ordered by time. This means you get a chronological view of what happened across your program, not just a single stack frame.

Why It's Cool

You navigate loops, not lines. This is the feature that stands out most. Instead of stepping through each iteration of a loop one at a time, you can move back and forth through iterations and watch how the values of selected expressions change. If you've ever debugged a loop with twenty iterations and wished you could just scrub through them like a timeline, this is that.

Exceptions don't disappear. When an expression raises an exception — even if it's caught and suppressed somewhere down the line — birdseye highlights it. That's genuinely useful, because suppressed exceptions are exactly the kind of thing that makes you question your sanity at 2 AM.

Data structures are explorable but not overwhelming. You can expand concrete data structures and objects to see their contents, but lengths and depths are limited. This is a smart design decision. A debugger that dumps a 50,000-element list into your browser isn't helping anyone. The limits keep the interface usable.

It fits into tools you already use. There's integration with some common tools for a smoother experience, according to the documentation. That means you don't have to abandon your existing workflow to get the benefit.

You can try it without installing anything. The project is available on futurecoder, where you can enter code in an editor and click a birdseye button to run it. No imports, no decorators, no setup. That's a low-friction way to see whether the approach clicks with you before committing to it in your own projects.

How to Try It

Getting started is about as simple as it gets:

1. Install the package:

   pip install birdseye
   

2. Add the @eye decorator to the function you want to inspect:

   from birdseye import eye
   
   @eye
   def your_function():
       # your code here
   

3. Run your code the way you normally would — script, test suite, whatever.

4. View the results in your browser.

If you'd rather not install anything yet, head over to futurecoder and try it in the browser first. The full documentation lives at birdseye.readthedocs.io, and there's a dedicated page on tool integrations if you want to wire it into your existing setup.

The repository is at github.com/alexmojaki/birdseye.

Final Thoughts

birdseye solves a specific problem well: understanding what happened inside a function after it's already returned. It's not trying to replace pdb or your IDE's debugger — it's filling a gap those tools leave open. If you spend a lot of time debugging loops, tracking down suppressed exceptions, or trying to figure out why a function produced the output it did, this is worth trying. The fact that you can test it in a browser before installing anything makes the barrier to entry essentially zero. For anyone doing iterative development in Python, it's a practical addition to the toolbox.

Follow @githubprojects for more developer tools and open source projects.