1. Debugging for humans
seapie comes with a user experience focused on discoverability: helpful error messages and built-in help you can reach from anywhere
2. Debug by describing what you want
All debuggers let you step. seapie lets Python expressions walk without magic syntax: ”stop when myfunc returns None, and call stack contains myhelper”
>>> !walk (_event_ == "return") and (_return_ is None) and ("myhelper" in _callstack_)
3. REPL-first by design >>>
Checking a variable is print(myvar) changing it is myvar = None. Debugging !commands work in the REPL and inspecting state is just python:
>>> _magic_
{'_line_': 8,
'_source_': ' return round(total_with_tax, 2)',
'_path_': '/home/hirsimak/seapie/test/demo.py',
'_return_': 35.64,
'_exception_': None,
'_event_': 'return',
'_callstack_': ['<module>', 'checkout']}
>>>myscript.py
print("script says hello!")
import seapie; seapie.breakpoint() # execution pauses here, you get >>>
do_stuff(myvariable)terminal
user@system:~/$ python myscript.py
script says hello!
🔗 Attaching seapie
seapie 4.0.0 (Python 3.13.3) [GCC 13.3.0] on linux
Type "!help" for seapie help
>>>terminal
>>> print(locals())
{'x': 1, 'myvariable': None}
>>>
>>> myvariable = x
>>>
>>> _magic_.keys()
dict_keys(['_line_', '_source_', '_path_', '_return_', '_exception_', '_event_', '_callstack_'])
>>>
>>> _line_, _source_
(18, ' while True:')
>>>
>>> !bad-command
💀 Unknown command !bad-command
⚡ !command quicklist (example: >>> !location)
!(h)elp Show help
!(l)ocation Show source code around currently executing line
!(t)raceback Show callstack with current frame highlighted
!(f)rame Move up and down in callstack
!(k)eep Constantly show any Python expression at the top of the terminal
!(s)tep Step through code execution
!(e)vent Step until a specific event type
!(u)ntil Step until a target like linenumber or file
... ( cut for brevity in readme ) ...
>>>Seapie doesn’t lock you into the prompt - you can step forward, jump around, or
resume normal execution whenever you feel done exploring. If you’re ever curious
what’s possible, !help is always there, inside the shell.
(For the curious: a snapshot of the built-in help lives in help_dump.txt.)
Click to expand
seapie is short for 'Scope Escaping Arbitrary Python Injection Executor'.
If you need license other than Unlicense, contact me ɯoɔ˙lᴉɐɯƃ (ʇɐ) snʞɹɐɯ˙ᴉʞɐɯᴉsɹᴉɥ.
seapie$ pip install -e .
Remember: increment __version__ in __init__.pyRemember: .pypirc file is needed.seapie$ python -m build --wheelseapie$ rm -rf build/ && rm -rf src/seapie.egg-info/seapie$ python -m twine check dist/*seapie$ python -m twine upload dist/*seapie$ rm -rf dist/
- Seapie is essentially singleton; only one thread can be debugged at a time.
- Remote debugging support could be added in the future. Python 3.14 looks promising.
Overall, pdb is ok but it felt rough for the novice I once was. pdb asks you to learn a small debugger language on top of Python and interaction with your code requires a separate 'mode'. In my opinion the correct specification for debugger user experience is that 'it works like i imagine it should work' and seapie tries to achieve that.
- add
export PS1='$ 'to bashrc, comment out spam fromneofetchand such - resize terminal to about 81x15 characters. Check with
stty size. $ cd seapie/test$ clear$ asciinema rec --quiet demo.cast$ batcat buggy.py$ python buggy.py$ print(_source_)$ items$ items.remove("bad input value")$ items$ !continue- separate terminal:
$ pkill -f asciinema - back in first terminal: ctrl+D
$ asciinema play demo.cast$ asciinema-agg demo.cast demo.gif --font-family "DejaVu Sans Mono" --font-size 20