This is a Python debugger which records the value of expressions in a function call and lets you easily view them after the function exits. For example:
Rather than stepping through lines, move back and forth through loop iterations and see how the values of selected expressions change:
See which expressions raise exceptions, even if they're suppressed:
Expand concrete data structures and objects to see their contents. Lengths and depths are limited to avoid an overload of data.
Calls are organised into functions (which are organised into files) and organised by time, letting you see what happens at a glance:
pip install birdseye.
Usage and features
For a quick demonstration, copy this example and run it. Then continue from step 2 below.
To debug your own function, decorate it with
from birdseye import eye @eye def foo():
eye decorator must be applied before any other decorators, i.e. at the bottom of the list.
- Call the function.
python -m birdseyein a terminal to run the UI server. The command has a single optional argument which is the port number, default 7777.
- Open http://localhost:7777 in your browser.
- Click on:
- The name of the file containing your function
- The name of the function
- The most recent call to the function
When viewing a function call, you can:
- Hover over an expression to view its value at the bottom of the screen.
- Click on an expression to select it so that it stays in the inspection panel, allowing you to view several values simultaneously and expand objects and data structures. Click again to deselect.
- Hover over an item in the inspection panel and it will be highlighted in the code.
- Drag the bar at the top of the inspection panel to resize it vertically.
- Click on the arrows next to loops to step back and forth through iterations. Click on the number in the middle for a dropdown to jump straight to a particular iteration.
- If the function call you're viewing includes a function call that was also traced, the expression where the call happens will have an arrow () in the corner which you can click on to go to that function call. This doesn't work when calling generator functions.
Data is kept in a SQL database. You can configure this by setting the environment variable
BIRDSEYE_DB to a database URL used by SQLAlchemy. The default is
Performance, volume of data, and limitations
Every function call is recorded, and every nontrivial expression is traced. This means that:
- Programs are greatly slowed down, and you should be wary of tracing code that has many function calls or iterations. Function calls are not visible in the interface until they have been completed.
- A large amount of data may be collected for every function call, especially for functions with many loop iterations and large nested objects and data structures. This may be a problem for memory both when running the program and viewing results in your browser.
- To limit the amount of data saved, only a sample is stored. Specifically:
- The first and last 3 iterations of loops.
- The first and last 3 values of sequences such as lists.
- 10 items of mappings such as dictionaries.
- 6 values of sets.
- A limited version of the
repr()of values is used, provided by the cheap_repr package.
- Nested data structures and objects can only be expanded by up to 3 levels. Inside loops, this is decreased.
There is no API at the moment to collect more or less data. Suggestions are welcome as it's not obvious how to deal with the problem. But the idea of this tool is to be as quick and convenient as possible and to work for most cases. If in a particular situation you have to think carefully about how to use it, it may be better to use more conventional debugging methods.
Asynchronous code is not supported.
In IPython shells and notebooks,
shell.ast_transformers is ignored in decorated functions.
I'd love your help! Check out the wiki to get started.
How it works
The source file of a decorated function is parsed into the standard Python Abstract Syntax Tree. The tree is then modified so that every statement is wrapped in its own
with statement and every expression is wrapped in a function call. The modified tree is compiled and the resulting code object is used to directly construct a brand new function. This is why the
eye decorator must be applied first: it's not a wrapper like most decorators, so other decorators applied first would almost certainly either have no effect or bypass the tracing. The AST modifications notify the tracer both before and after every expression and statement. This functionality is generic, and in the future it will be extracted into its own package.