mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-19 21:34:46 +00:00
74 lines
2.5 KiB
Markdown
74 lines
2.5 KiB
Markdown
---
|
|
name: python-debugpy
|
|
description: Debug Python with pdb, breakpoint(), post-mortem inspection, and debugpy remote attach.
|
|
metadata: { "openclaw": { "requires": { "bins": ["python3"] } } }
|
|
---
|
|
|
|
# Python Debugpy
|
|
|
|
Use when Python code needs interactive debugging: hidden locals, confusing state mutation, failing tests, subprocesses, long-running services, or remote/headless attach.
|
|
|
|
Pick the smallest debugger that reaches the bad frame.
|
|
|
|
## Choose
|
|
|
|
- `breakpoint()`: local code, source edits ok, fastest path.
|
|
- `python3 -m pdb`: no source edit, launch from the beginning.
|
|
- `python3 -m pdb -c continue`: stop at an unhandled exception.
|
|
- `debugpy`: remote/headless process, DAP client, already-running PID, or service startup race.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
python3 -m pdb path/to/script.py arg1
|
|
python3 -m pdb -c continue path/to/script.py
|
|
python3 -c "import debugpy" || python3 -m pip install debugpy
|
|
python3 -m debugpy --listen 127.0.0.1:5678 --wait-for-client path/to/script.py
|
|
python3 -m debugpy --listen 127.0.0.1:5678 --wait-for-client -m package.module
|
|
python3 -m debugpy --listen 127.0.0.1:5678 --pid <pid>
|
|
```
|
|
|
|
For source-edit attach:
|
|
|
|
```py
|
|
import debugpy
|
|
|
|
debugpy.listen(("127.0.0.1", 5678))
|
|
debugpy.wait_for_client()
|
|
debugpy.breakpoint()
|
|
```
|
|
|
|
For post-mortem:
|
|
|
|
```py
|
|
import pdb, sys
|
|
|
|
try:
|
|
run()
|
|
except Exception:
|
|
pdb.post_mortem(sys.exc_info()[2])
|
|
raise
|
|
```
|
|
|
|
## pdb
|
|
|
|
- Flow: `n`, `s`, `r`, `c`, `q`.
|
|
- Stack/source: `w`, `u`, `d`, `a`, `l`, `ll`.
|
|
- Values: `p expr`, `pp expr`, `display expr`.
|
|
- Breakpoints: `b file.py:42`, `b func`, `b file.py:42, condition`, `cl <num>`.
|
|
- Mutate/evaluate: `!statement`; full REPL: `interact`.
|
|
|
|
## Rules
|
|
|
|
- Reproduce with the smallest command/test first.
|
|
- Disable parallel test workers for pdb; interactive stdin usually breaks inside worker pools.
|
|
- Keep `debugpy` in the active env; do not add it as a project dependency unless the project already wants it.
|
|
- Bind debug servers to `127.0.0.1`; do not expose `0.0.0.0` unless isolated or tunnelled.
|
|
- Use unique ports for parallel sessions.
|
|
- Treat `debugpy --pid` as injection; avoid security-sensitive or production targets unless explicitly approved.
|
|
- If PID attach fails on Linux, check ptrace/container privileges before changing the target.
|
|
- Cleanup before commit: `rg -n 'breakpoint\\(|pdb\\.set_trace|debugpy\\.' --type py`.
|
|
- Rerun the normal project test/gate without the debugger.
|
|
- `PYTHONBREAKPOINT=0` disables `breakpoint()`.
|
|
- If a process is stuck after debugger detach, confirm it is not still paused at a breakpoint.
|