Metadata-Version: 2.4
Name: seapie
Version: 4.0.0
Summary: A Python debugger that drops you into a live >>> prompt at breakpoints
Author: Markus Hirsimäki
License: The Unlicense
Project-URL: homepage, https://github.com/hirsimaki-markus/seapie
Project-URL: issues, https://github.com/hirsimaki-markus/seapie/issues
Project-URL: license, https://choosealicense.com/licenses/unlicense/
Keywords: debugger,debug,debugging,breakpoint,pdb,repl,interactive,trace,stepping,seapie
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python
Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown

<div align="center">
    <h1>
        <br>
        🥧 seapie
    </h1>
    <a href="https://pypi.org/project/seapie/"><img src="https://img.shields.io/pepy/dt/seapie?color=brightgreen" alt="Downloads"/></a>
    &nbsp;
    <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.7_to_3.14+-blue?logo=python&logoColor=white" alt="Python"/></a>
    &nbsp;
    <a href="https://xkcd.com/353/"><img src="https://img.shields.io/badge/Dependencies-😎_None-blue" alt="No dependencies"/></a>
    &nbsp;
    <a href="https://choosealicense.com/licenses/unlicense/"><img src="https://img.shields.io/badge/Licence-The_Unlicence-blue" alt="Licence"/></a>
    &nbsp;
    <a href="https://en.wikipedia.org/wiki/Finland"><img src="https://img.shields.io/badge/Made_with_%E2%9D%A4%20in-Finland-blue" alt="Made in Finland"/></a>
    &nbsp;
    <br>
    <a href="https://pypi.org/project/seapie/"><img src="https://img.shields.io/pypi/v/seapie" alt="PyPI version"/></a>
    &nbsp;
    <a href="https://github.com/hirsimaki-markus/seapie/graphs/contributors"><img src="https://img.shields.io/github/contributors/hirsimaki-markus/seapie?color=2b9348&logo=github" alt="Contributors"/></a>
    &nbsp;
    <a href="https://github.com/hirsimaki-markus/seapie/stargazers"><img src="https://img.shields.io/github/stars/hirsimaki-markus/seapie" alt="Stars"/></a>
    &nbsp;
    <a href="https://github.com/hirsimaki-markus/seapie/network/members"><img src="https://img.shields.io/github/forks/hirsimaki-markus/seapie" alt="Forks"/></a>
    &nbsp;
    <a href="https://github.com/hirsimaki-markus/seapie/issues"><img src="https://img.shields.io/badge/Contributions-welcome-brightgreen" alt="Contributions welcome"/></a>
    <br>
    <br>
    A breakpoint should just mean <code>&gt;&gt;&gt;</code>
    <br>
    <br>
    <pre>pip install <a href="https://github.com/hirsimaki-markus/seapie">seapie</a></pre>
</div>

<div align="center">
    <img src="media/demo.gif" alt="seapie demo"/>
</div>

Seapie is a Python debugger that drops you into a live `>>>` prompt at `breakpoint()`.

Instead of learning a debugger command language, you get a real Python shell with time
paused — inspect state, experiment, and modify things freely. When you’re ready to move
on, you can step through execution and observe what happens next — still inside the
interpreter.
<br><br>

## Hands on example

<div><i>myscript.py</i></div>

```python
print("script says hello!")
import seapie; seapie.breakpoint()  # execution pauses here, you get >>>
do_stuff(myvariable)
```

<div><i>terminal</i></div>

```shell
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
>>>
```
<br>

## seapie.breakpoint() gives you `>>>`. Try it out

<div><i>terminal</i></div>

```python
>>> print(locals())
{'x': 1, 'myvariable': None}
>>>
>>> _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 this help message
    !(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
    !(w)alk           Step until arbitrary expression is True
    !(g)oto           Jump execution to a line in current frame
    !(c)ontinue       Completely detach debugger and resume normal execution
    !(v)erbose        Toggle verbose output from other commands
    !(p)retty         Toggle prettyprinting of the interpreter output
>>>
```
<br>

## Eventually, you’ll want time to move again

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`.)
<br>
<br>

## Misc / Notes

<details><summary>Click to expand</summary>

#### Origin of the name
seapie is short for 'Scope Escaping Arbitrary Python Injection Executor'.

#### Licensing
If you need license other than Unlicense, contact me ɯoɔ˙lᴉɐɯƃ (ʇɐ) snʞɹɐɯ˙ᴉʞɐɯᴉsɹᴉɥ.

#### Editable install
`seapie$ pip install -e .`

#### Build & publish
- `Remember: increment __version__ in __init__.py`
- `Remember: .pypirc file is needed.`
- `seapie$ python -m build --wheel`
- `seapie$ 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/`

#### Known limitations
- 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.

#### Why not pdb?
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.

#### How to re-record the demo gif
- add `export PS1='$ '` to bashrc, comment out spam from `neofetch` and 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`

</details>
