Metadata-Version: 2.4
Name: textual-debugger
Version: 0.3.0
Summary: A TUI debugger for Python, Perl, and other languages.  Based on textual.
Author-email: Al Danial <al.danial@gmail.com>
License: textual-debugger is licensed to you under the MIT/X Consortium license:
        
        Copyright (c) 2026 Albert Danial
        
        Permission is hereby granted, free of charge, to any person
        obtaining a copy of this software and associated documentation
        files (the "Software"), to deal in the Software without
        restriction, including without limitation the rights to use,
        copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the
        Software is furnished to do so, subject to the following
        conditions:
        
        The above copyright notice and this permission notice shall be
        included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
        OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
        NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
        HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
        WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
        FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
        OTHER DEALINGS IN THE SOFTWARE.
        
        
Project-URL: Homepage, https://github.com/AlDanial/tdb
Project-URL: Issues, https://github.com/AlDanial/tdb/issues
Project-URL: Source, https://github.com/AlDanial/tdb
Keywords: debugger,tui,textual,debugpy,debug,DAP
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=8.0.0
Requires-Dist: debugpy>=1.8.20
Requires-Dist: pygments>=2.17.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: prompt_toolkit<3.1,>=3.0.52
Provides-Extra: edit
Requires-Dist: textual[syntax]>=8.0.0; extra == "edit"
Provides-Extra: mcp
Requires-Dist: mcp<3.0.0,>=2.0.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: textual-debugger[mcp]; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: httpx; extra == "dev"
Requires-Dist: matplotlib; extra == "dev"
Requires-Dist: pyyaml; extra == "dev"
Requires-Dist: toml; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: ipython; extra == "dev"
Dynamic: license-file

# `textual-debugger`

`textual-debugger` (the package) provides `tdb` (the command-line tool and module),
a full-featured terminal-based debugger for Python and other languages
with a Debug Adapter Protocol (DAP) implementation.  In addition to Python,
`tdb` comes with built-in support for
- C, C++, Fortran (via `gdb` or `lldb-dap`)
- Rust (via `gdb` or `lldb-dap`, selected explicitly)
- Perl (via `perl -d`)
- Bash (via bash's own `DEBUG` trap; bash ≥ 4.4)
- Tcsh (via source instrumentation of a stock `tcsh`)
- Ruby (via the [debug gem](https://github.com/ruby/debug)'s `rdbg`; debug ≥ 1.9)
- OCaml (native via `lldb-dap`/`gdb`, bytecode via [ocamlearlybird](https://github.com/hackwaly/ocamlearlybird))
- Go (via [Delve](https://github.com/go-delve/delve)'s `dlv dap`)
- PowerShell 7 (via [PowerShell Editor Services](https://github.com/PowerShell/PowerShellEditorServices); Linux/macOS, Windows experimental)

**Documentation: https://textual-debugger.readthedocs.io/**
(also available offline with `tdb --doc`, or as plain text with `tdb --doc-text`)

- PyPI: https://pypi.org/project/textual-debugger/
- GitHub: https://github.com/AlDanial/tdb

MIT License.  Copyright 2026 by Al Danial.

## Highlights

- Debugs synchronous, asynchronous, multi-threaded, and multi-process Python,
  with inspectors for `asyncio` tasks (including a task wait graph), threads,
  and `multiprocessing` / `concurrent.futures` children
- Attach to a running Python (3.11+), C/C++, Go, Rust, or OCaml program
  by PID, with no preparation
- Remote attach to Python, Perl, Ruby, Rust, C/C++, and Go programs
- JSON-RPC server, MCP (v2) server, and a `SKILL.md` for headless and
  AI-assisted debugging
- Can run the debuggee in an external terminal to debug TUI applications
- Post-mortem exception hook and live breakpoint hooks (`tdb.breakpoint()` and
  its counterparts in Perl, Ruby, Go, C/C++/Fortran, Rust, and OCaml)
- `pytest --pdbcls=tdb.pytest_debugger:Debugger` integration
- Run mode (`--run`) to attach the TUI to a running job on Ctrl-C, and eval
  mode (`--eval`) to print expressions at chosen lines without the TUI
- Entirely keyboard-driven, with vim, emacs, and Notepad-style keybindings;
  mouse support in graphical environments

## Gallery

<p align="center">
  <img src="https://raw.githubusercontent.com/AlDanial/tdb/main/gallery/async_breakpoint.png" alt="at breakpoint" width="300">
  <img src="https://raw.githubusercontent.com/AlDanial/tdb/main/gallery/async_task_graph.png" alt="task graph" width="300">
  <img src="https://raw.githubusercontent.com/AlDanial/tdb/main/gallery/multiprocessing_process_3.png" alt="multiple processes" width="300">
  <img src="https://raw.githubusercontent.com/AlDanial/tdb/main/gallery/threading_list.png" alt="thread list" width="300">
</p>

Videos:
- [tdb basics](https://youtu.be/2_qf2WZDHuA) views, keybindings, breakpoints, stepping, variable modification, call stack
- [asyncio tasks](https://youtu.be/vM4tODuqMGg) inspect asyncio tasks and their wait graph; code mod to allow pause
- [threads and processes](https://youtu.be/J8LOARLs2oQ) inspect variables and call stacks in multiple threads and processes
- [external terminal](https://youtu.be/121aihjAQ8g) run the debuggee in a separate terminal--ideal for debugging TUI applications

## Installation

```bash
uv pip install textual-debugger        # or: pip install textual-debugger
uvx --from textual-debugger tdb my_program.py   # run without installing
pip install "textual-debugger[mcp]"    # add the optional MCP server
```

## Quick Start

```bash
tdb --doc                        # full documentation in a terminal Markdown viewer
tdb --info                       # versions and locations of tdb, its config, and every debugger it would use
tdb my_program.py arg1 arg2      # debug a Python program (stops at the first line)
tdb -k 20 -k module.py:14 my_program.py   # run to breakpoints
tdb -k module.py:27 --if "a > 7" my_program.py   # ... stopping only when a > 7
tdb ./myprog                     # debug a native executable built with -g
tdb script.pl                    # ... or a Perl, Bash, Tcsh, Ruby, PowerShell script
tdb -a 12345                     # attach to a running Python program by PID
tdb -r remotehost:5678           # attach to a remote debugpy server
```

See the [Quick Start](https://textual-debugger.readthedocs.io/quickstart/)
page for many more examples, and the
[CLI Reference](https://textual-debugger.readthedocs.io/reference/cli/)
for every option.

## Acknowledgments

`tdb` is built with Will McGugan's [textual](https://github.com/Textualize/textual)
and Microsoft's [debugpy](https://github.com/microsoft/debugpy), and was
inspired by Andreas Klöckner's [pudb](https://pypi.org/project/pudb/).
See [About](https://textual-debugger.readthedocs.io/about/) for the full
acknowledgments.
