# ipdab
A [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) (DAP) for the Python [pdb](https://docs.python.org/3/library/pdb.html) and [ipdb](https://ipython.readthedocs.io/en/stable/api/generated/IPython.terminal.debugger.html#module-IPython.terminal.debugger) debuggers.
[Debugpy](https://github.com/microsoft/debugpy) is the reference implementation of a DAP for Python.
The DAP allow your IDE to communicate with the debugger in a standardised way.
The good, old Python debuggers `pdb` and `ipdb` debugger were considered incompatible with the DAP as you control the debugger from the terminal, and not from your IDE.
The aim of `ipdab` is to implement the DAP to these debuggers to the extent possible, and get create a debugging experience that some would consider to have the best of both world:
- You control the debugger from the terminal
- Your IDE is able to track the debugger, e.g., by indicating the current line with an arrow.
# How it works
In addition to starting the `pdb` or `ipdb` debugger, `ipdab` starts server whenever you use `set_trace`.
Any IDE that supports the DAP can connect to this server to track progress of the debugger, retrieve variable values,
retrieve the stack trace etc.
Note that it's not possible to control the debugger from your IDE. This is a technical limitation of the `pdb` and `ipdb` debugger.
They give control to the user every time you see a command prompt. At such a point, the DAP server cannot inject any commands
as it doesn't control the terminal in which the debugger runs. Controlling the debugger should be done from the terminal itself.
# Installation
```bash
pip install ipdab
```
Or, clone the [repository](https://github.com/mvds314/ipdab.git) and install with:
```bash
pip install -e .
```
# Usage
Just like `ipdb`, use `ipdab` in the code you want to debug:
```python
print("Hello, world!")
print("Starting ipdab...")
import ipdab
ipdab.set_trace()
print("This will be debugged.")
```
Now, connect your IDE to the DAP server started by `ipdab`.
## Neovim
In Neovim, this could work by adding an extry entry to your `dap.adapters` and `dap.configurations`:
```lua
local dap = require "dap"
-- Custom DAP adapter for ipdb
dap.adapters.ipdb = {
type = "server",
host = "127.0.0.1",
port = 9000,
}
-- Attach config — does not launch, just connects
dap.configurations.python = dap.configurations.python or {}
table.insert(dap.configurations.python, {
name = "Attach to ipdb",
type = "ipdb",
request = "launch", -- <-- important to say launch here!
program = "${file}",
justMyCode = false,
cwd = vim.fn.getcwd(),
})
```
Then, start your Python script any way you want, e,g., with `python your_script.py` or `ipython -i your_script.py`.
When the execution hits the `ipdab.set_trace()` line, the DAP server will start and you can connect to it from Neovim with `:lua require'dap'.continue()`.
## VS Code
Should work similar to Neovim, not tested yet.
# TODO
- [ ] Test on slower hardware
- [ ] It seems that dapuit is timing out
- [ ] Try to start it with fewer windows
- [ ] Cleanup the repo
- [ ] Create a Neovim plugin
- [ ] Write a blog post about debugging
- [ ] Connect pdb backend in addition to ipdb backend
- [ ] Fix compatiblity with ipython 9.1.0 and higher, entering the debugger seems to break
- [ ] Check how ipdab works with module reloads
- [ ] Consider post mortem support
Raw data
{
"_id": null,
"home_page": null,
"name": "ipdab",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "debugger, dap, ipdb, debug-adapter-protocol, python",
"author": "Martin van der Schans",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/e2/8b/211c30711e9188a75b007b2553adff41fd260ca47170d00d3e25c11e70b6/ipdab-25.8.4.tar.gz",
"platform": null,
"description": "# ipdab\n\nA [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) (DAP) for the Python [pdb](https://docs.python.org/3/library/pdb.html) and [ipdb](https://ipython.readthedocs.io/en/stable/api/generated/IPython.terminal.debugger.html#module-IPython.terminal.debugger) debuggers.\n[Debugpy](https://github.com/microsoft/debugpy) is the reference implementation of a DAP for Python.\nThe DAP allow your IDE to communicate with the debugger in a standardised way.\n\nThe good, old Python debuggers `pdb` and `ipdb` debugger were considered incompatible with the DAP as you control the debugger from the terminal, and not from your IDE.\nThe aim of `ipdab` is to implement the DAP to these debuggers to the extent possible, and get create a debugging experience that some would consider to have the best of both world:\n\n- You control the debugger from the terminal\n- Your IDE is able to track the debugger, e.g., by indicating the current line with an arrow.\n\n# How it works\n\nIn addition to starting the `pdb` or `ipdb` debugger, `ipdab` starts server whenever you use `set_trace`.\nAny IDE that supports the DAP can connect to this server to track progress of the debugger, retrieve variable values,\nretrieve the stack trace etc.\n\nNote that it's not possible to control the debugger from your IDE. This is a technical limitation of the `pdb` and `ipdb` debugger.\nThey give control to the user every time you see a command prompt. At such a point, the DAP server cannot inject any commands\nas it doesn't control the terminal in which the debugger runs. Controlling the debugger should be done from the terminal itself.\n\n# Installation\n\n```bash\npip install ipdab\n\n```\n\nOr, clone the [repository](https://github.com/mvds314/ipdab.git) and install with:\n\n```bash\npip install -e .\n```\n\n# Usage\n\nJust like `ipdb`, use `ipdab` in the code you want to debug:\n\n```python\nprint(\"Hello, world!\")\nprint(\"Starting ipdab...\")\n\nimport ipdab\n\nipdab.set_trace()\n\nprint(\"This will be debugged.\")\n```\n\nNow, connect your IDE to the DAP server started by `ipdab`.\n\n## Neovim\n\nIn Neovim, this could work by adding an extry entry to your `dap.adapters` and `dap.configurations`:\n\n```lua\nlocal dap = require \"dap\"\n\n-- Custom DAP adapter for ipdb\ndap.adapters.ipdb = {\n type = \"server\",\n host = \"127.0.0.1\",\n port = 9000,\n}\n\n-- Attach config \u2014 does not launch, just connects\ndap.configurations.python = dap.configurations.python or {}\ntable.insert(dap.configurations.python, {\n name = \"Attach to ipdb\",\n type = \"ipdb\",\n request = \"launch\", -- <-- important to say launch here!\n program = \"${file}\",\n justMyCode = false,\n cwd = vim.fn.getcwd(),\n})\n```\n\nThen, start your Python script any way you want, e,g., with `python your_script.py` or `ipython -i your_script.py`.\nWhen the execution hits the `ipdab.set_trace()` line, the DAP server will start and you can connect to it from Neovim with `:lua require'dap'.continue()`.\n\n## VS Code\n\nShould work similar to Neovim, not tested yet.\n\n# TODO\n\n- [ ] Test on slower hardware\n - [ ] It seems that dapuit is timing out\n - [ ] Try to start it with fewer windows\n- [ ] Cleanup the repo\n- [ ] Create a Neovim plugin\n- [ ] Write a blog post about debugging\n- [ ] Connect pdb backend in addition to ipdb backend\n\n- [ ] Fix compatiblity with ipython 9.1.0 and higher, entering the debugger seems to break\n- [ ] Check how ipdab works with module reloads\n- [ ] Consider post mortem support\n\n",
"bugtrack_url": null,
"license": null,
"summary": "The Debug Adapter Protocol (DAP) implementation for the ipdb debugger.",
"version": "25.8.4",
"project_urls": {
"repository": "https://github.com/mvds314/ipdab"
},
"split_keywords": [
"debugger",
" dap",
" ipdb",
" debug-adapter-protocol",
" python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d6c90876844e3e6aaad83962c3443d7b3d27d1c4920841fd75eb1fed6a132454",
"md5": "2272cdb8dad3e4a1cade244644491086",
"sha256": "9465f2b907b7594b270170f429f4d0f89344dd080b94de0b02e5223d1df8f647"
},
"downloads": -1,
"filename": "ipdab-25.8.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2272cdb8dad3e4a1cade244644491086",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 13178,
"upload_time": "2025-08-31T19:06:18",
"upload_time_iso_8601": "2025-08-31T19:06:18.844211Z",
"url": "https://files.pythonhosted.org/packages/d6/c9/0876844e3e6aaad83962c3443d7b3d27d1c4920841fd75eb1fed6a132454/ipdab-25.8.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e28b211c30711e9188a75b007b2553adff41fd260ca47170d00d3e25c11e70b6",
"md5": "5d5003df1203729e01389de57bfc3de7",
"sha256": "f65c810f5c803698bcc18b559ecd9dfb21866a0fce9a2b4f9b253e2b03cd91a7"
},
"downloads": -1,
"filename": "ipdab-25.8.4.tar.gz",
"has_sig": false,
"md5_digest": "5d5003df1203729e01389de57bfc3de7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 13536,
"upload_time": "2025-08-31T19:06:19",
"upload_time_iso_8601": "2025-08-31T19:06:19.931321Z",
"url": "https://files.pythonhosted.org/packages/e2/8b/211c30711e9188a75b007b2553adff41fd260ca47170d00d3e25c11e70b6/ipdab-25.8.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-31 19:06:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mvds314",
"github_project": "ipdab",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ipdab"
}
JSON
