textual-debugger 0.0.4__tar.gz → 0.1.1__tar.gz

{textual_debugger-0.0.4 → textual_debugger-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: textual-debugger
-Version: 0.0.4
+Version: 0.1.1
 Summary: A TUI Python debugger based on textual and debugpy
 Author-email: Al Danial <al.danial@gmail.com>
 License: textual-debugger is licensed to you under the MIT/X Consortium license:
@@ -63,7 +63,7 @@ Requires-Dist: ruff; extra == "dev"
 Requires-Dist: ipython; extra == "dev"
 Dynamic: license-file
 
-# `textual-debugger` version 0.0.4 2026-05-10
+# `textual-debugger`
 
 `textual-debugger` (the package) provides `tdb` (the command-line tool and module),
 a full-featured terminal-based Python debugger.
@@ -97,7 +97,7 @@ automated, headless debugging workflows and AI-assisted debugging
 built with `textual`, `prompt-toolkit`, `urwid`, `curses`, `rich`, and so on
 
 - comes with a post-mortem exception hook that can be installed in Python programs
-to have the debugger pop open automatically at the first uncaught exception
+to have `tdb` pop open automatically at the first uncaught exception
 
 - can be entirely keyboard-driven
 making it suitable for operation in non-graphical environments (mouse support is
@@ -119,6 +119,20 @@ as open source.
 [Claude for Open Source](https://claude.com/contact-sales/claude-for-oss) program.
 `tdb` was made almost entirely with Claude Code.
 
+## Gallery
+<p align="center">
+  <img src="https://github.com/AlDanial/tdb/blob/main/gallery/async_breakpoint.png" alt="at breakpoint" width="300">
+  <img src="https://github.com/AlDanial/tdb/blob/main/gallery/async_task_graph.png" alt="task graph" width="300">
+  <img src="https://github.com/AlDanial/tdb/blob/main/gallery/multiprocessing_process_3.png" alt="multiple processes" width="300">
+  <img src="https://github.com/AlDanial/tdb/blob/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
@@ -134,7 +148,7 @@ uv pip install textual-debugger
 or run it without installing:
 
 ```
-uvx --from textual-debugger tdb
+uvx --from textual-debugger tdb  my_program.py
 ```
 
 
@@ -145,38 +159,38 @@ uvx --from textual-debugger tdb
 tdb --doc
 
 # debug a script (stops at first line by default)
-tdb my_script.py
+tdb my_program.py
 
 # debug with arguments
-tdb my_script.py arg1 arg2
+tdb my_program.py arg1 arg2
 
-# add breakpoints at lines 20 and 35 of `my_script.py` and line 14 of `module.py`
-tdb -k 20 -k 35 -k module.py:14 my_script.py arg1 arg2
+# add breakpoints at lines 20 and 35 of `my_program.py` and line 14 of `module.py`
+tdb -k 20 -k 35 -k module.py:14 my_program.py arg1 arg2
 
 # use a specific virtualenv
-tdb --python /path/to/venv/bin/python my_script.py
+tdb --python /path/to/venv/bin/python my_program.py
 
 # step into, or stop at tracebacks in library code
-tdb --no-just-my-code /path/to/venv/bin/python my_script.py
+tdb --no-just-my-code /path/to/venv/bin/python my_program.py
 
 # run until first breakpoint or exit
-tdb --no-stop-on-entry my_script.py
+tdb --no-stop-on-entry my_program.py
 
 # run the debuggee in an external terminal
-tdb --terminal xterm my_script.py
+tdb --terminal xterm my_program.py
 
 # attach to a remote Python program that has a debugpy server on port 5678
-tdb -r remotehost:5678 my_script.py
+tdb -r remotehost:5678 my_program.py
 
-> prevent `argparse` confusion by separating `tdb` switches from
-> the debuggee switches by prefixing the debuggee with `--`.
-tdb --python /path/to/venv/bin/python -- my_script.py -k 17 --max 23.3
+# prevent `argparse` confusion by separating `tdb` switches from
+# the debuggee switches by prefixing the debuggee with `--`
+tdb --python /path/to/venv/bin/python -- my_program.py -k 17 --max 23.3
 ```
 
-Or use the module entry point:
+Alternatively, use the module entry point:
 
 ```bash
-python -m tdb my_script.py
+python -m tdb my_program.py
 ```
 
 ## Layout
@@ -198,29 +212,18 @@ python -m tdb my_script.py
 └───────────────────────────────────────────────────────┘
 ```
 
+The status bar shows the current execution state (running, paused,
+breakpoint hit) and location.
+The footer shows the most relevant keybindings for the current mode.
+
 ## Features
 
 ### Navigation and Keybindings
 
+
 The Code View shows syntax-highlighted Python source with line numbers.
 A cursor line (blue) tracks your position; the current execution line is highlighted in gold.
 
-**Navigation (vim-style by default):**
-
-| Key | Action |
-|-----|--------|
-| `j` / `k` | Move cursor down / up |
-| `5j`, `10k` | Move N lines with count prefix |
-| `g` | Go to line (with count: `42g` jumps to line 42) |
-| `G` | Go to end of file |
-| `[` / `]` | Jump to previous / next paragraph boundary |
-| `/` | Search forward |
-| `?` | Search backward |
-| `n` / `N` | Next / previous search result |
-| `PageUp` / `PageDown` | Scroll by page |
-
-Switch between Navigation and Debug modes with `Escape`.
-
 **View focus shortcuts (global):**
 
 | Key | View |
@@ -245,6 +248,24 @@ Switch between Navigation and Debug modes with `Escape`.
 | `Alt+A` | Async Tasks |
 | `Alt+H` | Help (Documentation, About) |
 
+**Navigation (vim-style by default):**
+
+By default the Code View is in Debug mode.  Hit `Escape` to switch to Navigate mode
+In Navigate mode, you can move around the file with the following keys:
+
+| Key | Action |
+|-----|--------|
+| `j` / `k` | Move cursor down / up |
+| `5j`, `10k` | Move N lines down / up with count prefix |
+| `G` | Go to end of file (with count: `42G` jumps to line 42)|
+| `[` / `]` | Jump to previous / next paragraph boundary |
+| `/` | Search forward |
+| `?` | Search backward |
+| `n` / `N` | Next / previous search result |
+| `PageUp` / `PageDown` | Scroll by page |
+
+Switch from Navigate back to Debug mode with `Escape`.
+
 > **Note:** Many terminals send the byte sequence `ESC+f` for `Alt+F`, which Textual's
 ANSI parser rewrites to `Ctrl+Right` (the readline "forward-word" convention).
 `tdb` binds both so `Alt+F` works as expected regardless.
@@ -293,8 +314,7 @@ Breakpoints persist across session restarts.
 
 The Variable View shows a tree of scopes (Locals, Globals) with all variables in the current
 frame. Expand nodes to drill into complex objects.  Children are loaded lazily on demand.
-
-Format: `name (type) = value`
+Variable values can be changed in the Evaluate Console.
 
 ### Call Stack
 
@@ -321,11 +341,17 @@ A REPL at the bottom-left evaluates expressions in the current scope:
 (a, *p) : Join two or more pathname components...
 ```
 
+Variable values set here are reflected in the running code.
+
 ### Console Output
 
 The Console View captures stdout (normal text) and stderr (red text) from the debuggee
 in real time.
 
+If your program prints a lot, or prompts for input, or uses colors or
+terminal control codes, consider running it in an external terminal
+with `--terminal` for the best experience.
+
 ### Crash Detection
 
 When the debuggee raises an unhandled exception, `tdb`:
@@ -373,7 +399,9 @@ memoization.
 
 ### Live Breakpoint Hook
 
-For the `pdb.set_trace()` use case--pausing at a specific line to inspect, then
+`tdb` has an improved implemenation of the standard `breakpoint()` function (or equivalently,
+`pdb.set_trace()`) used to pause at a specific line to inspect, then
+here=
 continuing--use `tdb.breakpoint()`:
 
 ```python
@@ -519,7 +547,7 @@ print("tdb is attached!")
 
 When the debuggee runs and hits the `debugpy.wait_for_client()` line, it starts a
 debugpy server listening on port 5678.
-Attach `tdb` to it with the `-r` / `--remote-attach` switch, specifying the host and port.
+Attach `tdb` to it with the `-r` switch, specifying the host and port.
 If the debuggee is on the same machine, you can omit the host or use `localhost`.
 This example assumes the debuggee runs on 192.168.1.10 and listens on port 5678:
 
@@ -529,7 +557,7 @@ tdb -r 5678   # to localhost
 tdb -r 192.168.1.10:5678
 
 # With breakpoints:
-tdb -r 5678 -k my_script.py:42
+tdb -r 5678 -k my_program.py:42
 ```
 
 All debugging features (breakpoints, stepping, variable inspection, threads, processes,
@@ -538,7 +566,7 @@ source file when the program stops.
 
 ### External Terminal Support
 
-Some Python programs, notably text user interfaces, make heavy use of terminal control
+Some Python programs, notably text user interfaces, use terminal control
 codes and require direct access to the terminal to function properly. 
 Such programs can be debugged with `tdb` by having it launch the debuggee in
 a separate terminal:
@@ -557,9 +585,9 @@ This feature only works in graphical environments where external terminals are a
 ### Keybinding Schemes
 
 ```bash
-tdb --keybindings vim my_script.py    # default
-tdb --keybindings emacs my_script.py
-tdb --keybindings default my_script.py
+tdb --keybindings vim my_program.py    # default
+tdb --keybindings emacs my_program.py
+tdb --keybindings default my_program.py
 ```
 
 The keybinding choice is saved to `~/.config/tdb/config.json` and remembered for subsequent
@@ -573,7 +601,7 @@ debugging, CI pipelines, or AI-assisted debugging workflows.
 ### Headless Mode (no TUI)
 
 ```bash
-python -m tdb --headless my_script.py &
+python -m tdb --headless my_program.py &
 ```
 
 The server listens on `http://127.0.0.1:8150/rpc` (change with `--server-port`).
@@ -581,7 +609,7 @@ The server listens on `http://127.0.0.1:8150/rpc` (change with `--server-port`).
 ### Dual Mode (TUI + server)
 
 ```bash
-tdb --server my_script.py
+tdb --server my_program.py
 ```
 
 Both the interactive TUI and the JSON-RPC server run simultaneously.
@@ -674,7 +702,7 @@ usage: tdb [-h] [-v/--version] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
 
 | Flag | Description |
 |------|-------------|
-| `-r`, `--remote-attach HOST:PORT` | Attach to a remote debugpy server |
+| `-r HOST:PORT` | Attach to a remote debugpy server |
 | `-k`, `--breakpoint FILE:LINE|LINE` | Set a breakpoint (may be repeated) |
 | `--no-stop-on-entry` | Do not pause at the first line (default: stop on entry) |
 | `--cwd DIR` | Working directory for the debuggee |

{textual_debugger-0.0.4/src/tdb → textual_debugger-0.1.1}/README.md

@@ -1,4 +1,4 @@
-# `textual-debugger` version 0.0.4 2026-05-10
+# `textual-debugger`
 
 `textual-debugger` (the package) provides `tdb` (the command-line tool and module),
 a full-featured terminal-based Python debugger.
@@ -32,7 +32,7 @@ automated, headless debugging workflows and AI-assisted debugging
 built with `textual`, `prompt-toolkit`, `urwid`, `curses`, `rich`, and so on
 
 - comes with a post-mortem exception hook that can be installed in Python programs
-to have the debugger pop open automatically at the first uncaught exception
+to have `tdb` pop open automatically at the first uncaught exception
 
 - can be entirely keyboard-driven
 making it suitable for operation in non-graphical environments (mouse support is
@@ -54,6 +54,20 @@ as open source.
 [Claude for Open Source](https://claude.com/contact-sales/claude-for-oss) program.
 `tdb` was made almost entirely with Claude Code.
 
+## Gallery
+<p align="center">
+  <img src="https://github.com/AlDanial/tdb/blob/main/gallery/async_breakpoint.png" alt="at breakpoint" width="300">
+  <img src="https://github.com/AlDanial/tdb/blob/main/gallery/async_task_graph.png" alt="task graph" width="300">
+  <img src="https://github.com/AlDanial/tdb/blob/main/gallery/multiprocessing_process_3.png" alt="multiple processes" width="300">
+  <img src="https://github.com/AlDanial/tdb/blob/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
@@ -69,7 +83,7 @@ uv pip install textual-debugger
 or run it without installing:
 
 ```
-uvx --from textual-debugger tdb
+uvx --from textual-debugger tdb  my_program.py
 ```
 
 
@@ -80,38 +94,38 @@ uvx --from textual-debugger tdb
 tdb --doc
 
 # debug a script (stops at first line by default)
-tdb my_script.py
+tdb my_program.py
 
 # debug with arguments
-tdb my_script.py arg1 arg2
+tdb my_program.py arg1 arg2
 
-# add breakpoints at lines 20 and 35 of `my_script.py` and line 14 of `module.py`
-tdb -k 20 -k 35 -k module.py:14 my_script.py arg1 arg2
+# add breakpoints at lines 20 and 35 of `my_program.py` and line 14 of `module.py`
+tdb -k 20 -k 35 -k module.py:14 my_program.py arg1 arg2
 
 # use a specific virtualenv
-tdb --python /path/to/venv/bin/python my_script.py
+tdb --python /path/to/venv/bin/python my_program.py
 
 # step into, or stop at tracebacks in library code
-tdb --no-just-my-code /path/to/venv/bin/python my_script.py
+tdb --no-just-my-code /path/to/venv/bin/python my_program.py
 
 # run until first breakpoint or exit
-tdb --no-stop-on-entry my_script.py
+tdb --no-stop-on-entry my_program.py
 
 # run the debuggee in an external terminal
-tdb --terminal xterm my_script.py
+tdb --terminal xterm my_program.py
 
 # attach to a remote Python program that has a debugpy server on port 5678
-tdb -r remotehost:5678 my_script.py
+tdb -r remotehost:5678 my_program.py
 
-> prevent `argparse` confusion by separating `tdb` switches from
-> the debuggee switches by prefixing the debuggee with `--`.
-tdb --python /path/to/venv/bin/python -- my_script.py -k 17 --max 23.3
+# prevent `argparse` confusion by separating `tdb` switches from
+# the debuggee switches by prefixing the debuggee with `--`
+tdb --python /path/to/venv/bin/python -- my_program.py -k 17 --max 23.3
 ```
 
-Or use the module entry point:
+Alternatively, use the module entry point:
 
 ```bash
-python -m tdb my_script.py
+python -m tdb my_program.py
 ```
 
 ## Layout
@@ -133,29 +147,18 @@ python -m tdb my_script.py
 └───────────────────────────────────────────────────────┘
 ```
 
+The status bar shows the current execution state (running, paused,
+breakpoint hit) and location.
+The footer shows the most relevant keybindings for the current mode.
+
 ## Features
 
 ### Navigation and Keybindings
 
+
 The Code View shows syntax-highlighted Python source with line numbers.
 A cursor line (blue) tracks your position; the current execution line is highlighted in gold.
 
-**Navigation (vim-style by default):**
-
-| Key | Action |
-|-----|--------|
-| `j` / `k` | Move cursor down / up |
-| `5j`, `10k` | Move N lines with count prefix |
-| `g` | Go to line (with count: `42g` jumps to line 42) |
-| `G` | Go to end of file |
-| `[` / `]` | Jump to previous / next paragraph boundary |
-| `/` | Search forward |
-| `?` | Search backward |
-| `n` / `N` | Next / previous search result |
-| `PageUp` / `PageDown` | Scroll by page |
-
-Switch between Navigation and Debug modes with `Escape`.
-
 **View focus shortcuts (global):**
 
 | Key | View |
@@ -180,6 +183,24 @@ Switch between Navigation and Debug modes with `Escape`.
 | `Alt+A` | Async Tasks |
 | `Alt+H` | Help (Documentation, About) |
 
+**Navigation (vim-style by default):**
+
+By default the Code View is in Debug mode.  Hit `Escape` to switch to Navigate mode
+In Navigate mode, you can move around the file with the following keys:
+
+| Key | Action |
+|-----|--------|
+| `j` / `k` | Move cursor down / up |
+| `5j`, `10k` | Move N lines down / up with count prefix |
+| `G` | Go to end of file (with count: `42G` jumps to line 42)|
+| `[` / `]` | Jump to previous / next paragraph boundary |
+| `/` | Search forward |
+| `?` | Search backward |
+| `n` / `N` | Next / previous search result |
+| `PageUp` / `PageDown` | Scroll by page |
+
+Switch from Navigate back to Debug mode with `Escape`.
+
 > **Note:** Many terminals send the byte sequence `ESC+f` for `Alt+F`, which Textual's
 ANSI parser rewrites to `Ctrl+Right` (the readline "forward-word" convention).
 `tdb` binds both so `Alt+F` works as expected regardless.
@@ -228,8 +249,7 @@ Breakpoints persist across session restarts.
 
 The Variable View shows a tree of scopes (Locals, Globals) with all variables in the current
 frame. Expand nodes to drill into complex objects.  Children are loaded lazily on demand.
-
-Format: `name (type) = value`
+Variable values can be changed in the Evaluate Console.
 
 ### Call Stack
 
@@ -256,11 +276,17 @@ A REPL at the bottom-left evaluates expressions in the current scope:
 (a, *p) : Join two or more pathname components...
 ```
 
+Variable values set here are reflected in the running code.
+
 ### Console Output
 
 The Console View captures stdout (normal text) and stderr (red text) from the debuggee
 in real time.
 
+If your program prints a lot, or prompts for input, or uses colors or
+terminal control codes, consider running it in an external terminal
+with `--terminal` for the best experience.
+
 ### Crash Detection
 
 When the debuggee raises an unhandled exception, `tdb`:
@@ -308,7 +334,9 @@ memoization.
 
 ### Live Breakpoint Hook
 
-For the `pdb.set_trace()` use case--pausing at a specific line to inspect, then
+`tdb` has an improved implemenation of the standard `breakpoint()` function (or equivalently,
+`pdb.set_trace()`) used to pause at a specific line to inspect, then
+here=
 continuing--use `tdb.breakpoint()`:
 
 ```python
@@ -454,7 +482,7 @@ print("tdb is attached!")
 
 When the debuggee runs and hits the `debugpy.wait_for_client()` line, it starts a
 debugpy server listening on port 5678.
-Attach `tdb` to it with the `-r` / `--remote-attach` switch, specifying the host and port.
+Attach `tdb` to it with the `-r` switch, specifying the host and port.
 If the debuggee is on the same machine, you can omit the host or use `localhost`.
 This example assumes the debuggee runs on 192.168.1.10 and listens on port 5678:
 
@@ -464,7 +492,7 @@ tdb -r 5678   # to localhost
 tdb -r 192.168.1.10:5678
 
 # With breakpoints:
-tdb -r 5678 -k my_script.py:42
+tdb -r 5678 -k my_program.py:42
 ```
 
 All debugging features (breakpoints, stepping, variable inspection, threads, processes,
@@ -473,7 +501,7 @@ source file when the program stops.
 
 ### External Terminal Support
 
-Some Python programs, notably text user interfaces, make heavy use of terminal control
+Some Python programs, notably text user interfaces, use terminal control
 codes and require direct access to the terminal to function properly. 
 Such programs can be debugged with `tdb` by having it launch the debuggee in
 a separate terminal:
@@ -492,9 +520,9 @@ This feature only works in graphical environments where external terminals are a
 ### Keybinding Schemes
 
 ```bash
-tdb --keybindings vim my_script.py    # default
-tdb --keybindings emacs my_script.py
-tdb --keybindings default my_script.py
+tdb --keybindings vim my_program.py    # default
+tdb --keybindings emacs my_program.py
+tdb --keybindings default my_program.py
 ```
 
 The keybinding choice is saved to `~/.config/tdb/config.json` and remembered for subsequent
@@ -508,7 +536,7 @@ debugging, CI pipelines, or AI-assisted debugging workflows.
 ### Headless Mode (no TUI)
 
 ```bash
-python -m tdb --headless my_script.py &
+python -m tdb --headless my_program.py &
 ```
 
 The server listens on `http://127.0.0.1:8150/rpc` (change with `--server-port`).
@@ -516,7 +544,7 @@ The server listens on `http://127.0.0.1:8150/rpc` (change with `--server-port`).
 ### Dual Mode (TUI + server)
 
 ```bash
-tdb --server my_script.py
+tdb --server my_program.py
 ```
 
 Both the interactive TUI and the JSON-RPC server run simultaneously.
@@ -609,7 +637,7 @@ usage: tdb [-h] [-v/--version] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
 
 | Flag | Description |
 |------|-------------|
-| `-r`, `--remote-attach HOST:PORT` | Attach to a remote debugpy server |
+| `-r HOST:PORT` | Attach to a remote debugpy server |
 | `-k`, `--breakpoint FILE:LINE|LINE` | Set a breakpoint (may be repeated) |
 | `--no-stop-on-entry` | Do not pause at the first line (default: stop on entry) |
 | `--cwd DIR` | Working directory for the debuggee |