textual-debugger 0.1.0__tar.gz → 0.1.2__tar.gz

{textual_debugger-0.1.0 → textual_debugger-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: textual-debugger
-Version: 0.1.0
+Version: 0.1.2
 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:
@@ -130,6 +130,8 @@ as open source.
 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
 
@@ -162,14 +164,16 @@ tdb my_program.py
 # debug with arguments
 tdb my_program.py arg1 arg2
 
-# add breakpoints at lines 20 and 35 of `my_program.py` and line 14 of `module.py`
+# add breakpoints at lines 20 and 35 of `my_program.py` and line 14
+# of `module.py` (when -k is given, --no-stop-on-entry is set and the
+# program runs to the first breakpoint)
 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_program.py
 
 # step into, or stop at tracebacks in library code
-tdb --no-just-my-code /path/to/venv/bin/python my_program.py
+tdb --no-just-my-code --python /path/to/venv/bin/python my_program.py
 
 # run until first breakpoint or exit
 tdb --no-stop-on-entry my_program.py
@@ -240,7 +244,7 @@ A cursor line (blue) tracks your position; the current execution line is highlig
 | Key | Menu |
 |-----|------|
 | `Alt+F` | File (open a different script to debug) |
-| `Alt+C` | Configure (Color Theme, Keybindings) |
+| `Alt+C` | Configure (Color Theme, Keybindings, Step Mode) |
 | `Alt+T` | Threads |
 | `Alt+P` | Processes |
 | `Alt+A` | Async Tasks |
@@ -275,13 +279,15 @@ those for gdb/pdb, with some aliases and extras thrown in for convenience.
 
 | Key | Action |
 |-----|--------|
-| `n` | Step over (next line) |
+| `n` | Step over (next statement) |
 | `s` | Step into function call |
 | `o` / `f` / `r` | Step out of current function (also aliased as "finish" and "return") |
 | `c` | Continue execution |
 | `p` | Pause a running program |
 | `t` | Run to cursor position |
 | `u` / `d` | Navigate stack up (caller) / down (callee) |
+| `j` / `k` | Move cursor down / up (with count: `5j`, `10k`) |
+| `G` | Go to last line (with count: `42G` jumps to line 42) |
 | `R` | Restart the debug session |
 | `Ctrl+Q` | Quit |
 
@@ -290,6 +296,23 @@ those for gdb/pdb, with some aliases and extras thrown in for convenience.
 normally and stops at the return point. A true gdb-style immediate-return (skipping
 remaining code in the function without executing side effects) is not supported by DAP/debugpy.
 
+**Step granularity (statement vs. line):** by default, `n` (step over) and `s` (step into)
+treat a multi-line source statement as a single step. For example, stepping over
+
+```python
+results = await asyncio.gather(
+    fetch(1, 2),
+    fetch(2, 1),
+    fetch(3, 3),
+)
+print(results)   # next stop lands here, not on each sub-line above
+```
+
+lands on `print(results)`, not on each interior sub-line of the `gather` call. Switch to
+**Line** mode (Configure > Step Mode) to get debugpy's native per-line behavior, which
+stops on each physical line — useful for inspecting how a complex expression is built up.
+The choice is saved to `~/.config/tdb/config.json`.
+
 ### Breakpoints
 
 Click the gutter in the Code View to toggle a breakpoint, or press `b` in Debug mode.
@@ -701,8 +724,8 @@ usage: tdb [-h] [-v/--version] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
 | Flag | Description |
 |------|-------------|
 | `-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) |
+| `-k`, `--breakpoint FILE:LINE|LINE` | Set a breakpoint (may be repeated). Passing `-k` implies `--no-stop-on-entry` so the program runs straight to the first breakpoint. |
+| `--no-stop-on-entry` | Do not pause at the first line (default: stop on entry; automatic when `-k` is given) |
 | `--cwd DIR` | Working directory for the debuggee |
 | `--python PATH` | Python interpreter for the debuggee |
 | `--no-just-my-code` | Step into stdlib/site-packages code instead of skipping it
@@ -724,12 +747,25 @@ On Windows, it uses `%APPDATA%\tdb\`.
 
 | File | Contents |
 |------|----------|
-| `config.json` | User preferences (keybinding scheme) |
+| `config.json` | User preferences (keybinding scheme, color theme, step mode) |
 | `breakpoints.json` | Breakpoints from previous sessions, keyed by project directory |
 
 Breakpoints are saved on exit and restored when debugging a program in the same
 directory. Each project's breakpoints are independent.
 
+**Step mode** (`step_mode` in `config.json`) controls how `n` (step over) and `s` (step
+into) handle multi-line source statements:
+
+| Value | Behavior |
+|-------|----------|
+| `"statement"` (default) | A multi-line statement (e.g. a `gather(...)` call spanning five lines) is one step. The debugger keeps issuing DAP steps until execution leaves the statement, then stops on the next logical line. |
+| `"line"` | debugpy's native per-line behavior — stops on every physical line, including each interior sub-line of a multi-line expression. |
+
+Change it from the menu (**Configure > Step Mode**); the choice is saved immediately and
+applies to all future sessions. Breakpoint hits, exceptions, and pauses always interrupt
+a statement step, so a breakpoint set on a sub-line of a multi-line expression still
+fires as expected.
+
 ## Tech Stack
 
 - [textual](https://github.com/Textualize/textual) : TUI framework

{textual_debugger-0.1.0/src/tdb → textual_debugger-0.1.2}/README.md

@@ -65,6 +65,8 @@ as open source.
 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
 
@@ -97,14 +99,16 @@ tdb my_program.py
 # debug with arguments
 tdb my_program.py arg1 arg2
 
-# add breakpoints at lines 20 and 35 of `my_program.py` and line 14 of `module.py`
+# add breakpoints at lines 20 and 35 of `my_program.py` and line 14
+# of `module.py` (when -k is given, --no-stop-on-entry is set and the
+# program runs to the first breakpoint)
 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_program.py
 
 # step into, or stop at tracebacks in library code
-tdb --no-just-my-code /path/to/venv/bin/python my_program.py
+tdb --no-just-my-code --python /path/to/venv/bin/python my_program.py
 
 # run until first breakpoint or exit
 tdb --no-stop-on-entry my_program.py
@@ -175,7 +179,7 @@ A cursor line (blue) tracks your position; the current execution line is highlig
 | Key | Menu |
 |-----|------|
 | `Alt+F` | File (open a different script to debug) |
-| `Alt+C` | Configure (Color Theme, Keybindings) |
+| `Alt+C` | Configure (Color Theme, Keybindings, Step Mode) |
 | `Alt+T` | Threads |
 | `Alt+P` | Processes |
 | `Alt+A` | Async Tasks |
@@ -210,13 +214,15 @@ those for gdb/pdb, with some aliases and extras thrown in for convenience.
 
 | Key | Action |
 |-----|--------|
-| `n` | Step over (next line) |
+| `n` | Step over (next statement) |
 | `s` | Step into function call |
 | `o` / `f` / `r` | Step out of current function (also aliased as "finish" and "return") |
 | `c` | Continue execution |
 | `p` | Pause a running program |
 | `t` | Run to cursor position |
 | `u` / `d` | Navigate stack up (caller) / down (callee) |
+| `j` / `k` | Move cursor down / up (with count: `5j`, `10k`) |
+| `G` | Go to last line (with count: `42G` jumps to line 42) |
 | `R` | Restart the debug session |
 | `Ctrl+Q` | Quit |
 
@@ -225,6 +231,23 @@ those for gdb/pdb, with some aliases and extras thrown in for convenience.
 normally and stops at the return point. A true gdb-style immediate-return (skipping
 remaining code in the function without executing side effects) is not supported by DAP/debugpy.
 
+**Step granularity (statement vs. line):** by default, `n` (step over) and `s` (step into)
+treat a multi-line source statement as a single step. For example, stepping over
+
+```python
+results = await asyncio.gather(
+    fetch(1, 2),
+    fetch(2, 1),
+    fetch(3, 3),
+)
+print(results)   # next stop lands here, not on each sub-line above
+```
+
+lands on `print(results)`, not on each interior sub-line of the `gather` call. Switch to
+**Line** mode (Configure > Step Mode) to get debugpy's native per-line behavior, which
+stops on each physical line — useful for inspecting how a complex expression is built up.
+The choice is saved to `~/.config/tdb/config.json`.
+
 ### Breakpoints
 
 Click the gutter in the Code View to toggle a breakpoint, or press `b` in Debug mode.
@@ -636,8 +659,8 @@ usage: tdb [-h] [-v/--version] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
 | Flag | Description |
 |------|-------------|
 | `-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) |
+| `-k`, `--breakpoint FILE:LINE|LINE` | Set a breakpoint (may be repeated). Passing `-k` implies `--no-stop-on-entry` so the program runs straight to the first breakpoint. |
+| `--no-stop-on-entry` | Do not pause at the first line (default: stop on entry; automatic when `-k` is given) |
 | `--cwd DIR` | Working directory for the debuggee |
 | `--python PATH` | Python interpreter for the debuggee |
 | `--no-just-my-code` | Step into stdlib/site-packages code instead of skipping it
@@ -659,12 +682,25 @@ On Windows, it uses `%APPDATA%\tdb\`.
 
 | File | Contents |
 |------|----------|
-| `config.json` | User preferences (keybinding scheme) |
+| `config.json` | User preferences (keybinding scheme, color theme, step mode) |
 | `breakpoints.json` | Breakpoints from previous sessions, keyed by project directory |
 
 Breakpoints are saved on exit and restored when debugging a program in the same
 directory. Each project's breakpoints are independent.
 
+**Step mode** (`step_mode` in `config.json`) controls how `n` (step over) and `s` (step
+into) handle multi-line source statements:
+
+| Value | Behavior |
+|-------|----------|
+| `"statement"` (default) | A multi-line statement (e.g. a `gather(...)` call spanning five lines) is one step. The debugger keeps issuing DAP steps until execution leaves the statement, then stops on the next logical line. |
+| `"line"` | debugpy's native per-line behavior — stops on every physical line, including each interior sub-line of a multi-line expression. |
+
+Change it from the menu (**Configure > Step Mode**); the choice is saved immediately and
+applies to all future sessions. Breakpoint hits, exceptions, and pauses always interrupt
+a statement step, so a breakpoint set on a sub-line of a multi-line expression still
+fires as expected.
+
 ## Tech Stack
 
 - [textual](https://github.com/Textualize/textual) : TUI framework

{textual_debugger-0.1.0 → textual_debugger-0.1.2/src/tdb}/README.md

@@ -65,6 +65,8 @@ as open source.
 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
 
@@ -97,14 +99,16 @@ tdb my_program.py
 # debug with arguments
 tdb my_program.py arg1 arg2
 
-# add breakpoints at lines 20 and 35 of `my_program.py` and line 14 of `module.py`
+# add breakpoints at lines 20 and 35 of `my_program.py` and line 14
+# of `module.py` (when -k is given, --no-stop-on-entry is set and the
+# program runs to the first breakpoint)
 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_program.py
 
 # step into, or stop at tracebacks in library code
-tdb --no-just-my-code /path/to/venv/bin/python my_program.py
+tdb --no-just-my-code --python /path/to/venv/bin/python my_program.py
 
 # run until first breakpoint or exit
 tdb --no-stop-on-entry my_program.py
@@ -175,7 +179,7 @@ A cursor line (blue) tracks your position; the current execution line is highlig
 | Key | Menu |
 |-----|------|
 | `Alt+F` | File (open a different script to debug) |
-| `Alt+C` | Configure (Color Theme, Keybindings) |
+| `Alt+C` | Configure (Color Theme, Keybindings, Step Mode) |
 | `Alt+T` | Threads |
 | `Alt+P` | Processes |
 | `Alt+A` | Async Tasks |
@@ -210,13 +214,15 @@ those for gdb/pdb, with some aliases and extras thrown in for convenience.
 
 | Key | Action |
 |-----|--------|
-| `n` | Step over (next line) |
+| `n` | Step over (next statement) |
 | `s` | Step into function call |
 | `o` / `f` / `r` | Step out of current function (also aliased as "finish" and "return") |
 | `c` | Continue execution |
 | `p` | Pause a running program |
 | `t` | Run to cursor position |
 | `u` / `d` | Navigate stack up (caller) / down (callee) |
+| `j` / `k` | Move cursor down / up (with count: `5j`, `10k`) |
+| `G` | Go to last line (with count: `42G` jumps to line 42) |
 | `R` | Restart the debug session |
 | `Ctrl+Q` | Quit |
 
@@ -225,6 +231,23 @@ those for gdb/pdb, with some aliases and extras thrown in for convenience.
 normally and stops at the return point. A true gdb-style immediate-return (skipping
 remaining code in the function without executing side effects) is not supported by DAP/debugpy.
 
+**Step granularity (statement vs. line):** by default, `n` (step over) and `s` (step into)
+treat a multi-line source statement as a single step. For example, stepping over
+
+```python
+results = await asyncio.gather(
+    fetch(1, 2),
+    fetch(2, 1),
+    fetch(3, 3),
+)
+print(results)   # next stop lands here, not on each sub-line above
+```
+
+lands on `print(results)`, not on each interior sub-line of the `gather` call. Switch to
+**Line** mode (Configure > Step Mode) to get debugpy's native per-line behavior, which
+stops on each physical line — useful for inspecting how a complex expression is built up.
+The choice is saved to `~/.config/tdb/config.json`.
+
 ### Breakpoints
 
 Click the gutter in the Code View to toggle a breakpoint, or press `b` in Debug mode.
@@ -636,8 +659,8 @@ usage: tdb [-h] [-v/--version] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
 | Flag | Description |
 |------|-------------|
 | `-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) |
+| `-k`, `--breakpoint FILE:LINE|LINE` | Set a breakpoint (may be repeated). Passing `-k` implies `--no-stop-on-entry` so the program runs straight to the first breakpoint. |
+| `--no-stop-on-entry` | Do not pause at the first line (default: stop on entry; automatic when `-k` is given) |
 | `--cwd DIR` | Working directory for the debuggee |
 | `--python PATH` | Python interpreter for the debuggee |
 | `--no-just-my-code` | Step into stdlib/site-packages code instead of skipping it
@@ -659,12 +682,25 @@ On Windows, it uses `%APPDATA%\tdb\`.
 
 | File | Contents |
 |------|----------|
-| `config.json` | User preferences (keybinding scheme) |
+| `config.json` | User preferences (keybinding scheme, color theme, step mode) |
 | `breakpoints.json` | Breakpoints from previous sessions, keyed by project directory |
 
 Breakpoints are saved on exit and restored when debugging a program in the same
 directory. Each project's breakpoints are independent.
 
+**Step mode** (`step_mode` in `config.json`) controls how `n` (step over) and `s` (step
+into) handle multi-line source statements:
+
+| Value | Behavior |
+|-------|----------|
+| `"statement"` (default) | A multi-line statement (e.g. a `gather(...)` call spanning five lines) is one step. The debugger keeps issuing DAP steps until execution leaves the statement, then stops on the next logical line. |
+| `"line"` | debugpy's native per-line behavior — stops on every physical line, including each interior sub-line of a multi-line expression. |
+
+Change it from the menu (**Configure > Step Mode**); the choice is saved immediately and
+applies to all future sessions. Breakpoint hits, exceptions, and pauses always interrupt
+a statement step, so a breakpoint set on a sub-line of a multi-line expression still
+fires as expected.
+
 ## Tech Stack
 
 - [textual](https://github.com/Textualize/textual) : TUI framework

{textual_debugger-0.1.0 → textual_debugger-0.1.2}/src/tdb/__init__.py

@@ -1,6 +1,6 @@
 from tdb.breakpoint_hook import breakpoint
 from tdb.post_mortem import exception_hook
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 
 __all__ = ["breakpoint", "exception_hook"]

textual_debugger-0.1.2/src/tdb/_timeouts.py

@@ -0,0 +1,59 @@
+"""Centralized timeout constants (seconds).
+
+Reasoning per constant lives beside its value so the "why this number?"
+question doesn't require reading commit history or guessing. Group by
+subsystem; alphabetize within group.
+
+Bare integers/floats for wall-clock seconds. Always pass to
+`asyncio.wait_for(..., timeout=X)` (or equivalent). Don't multiply
+these together to derive new timeouts — add a new named constant.
+"""
+
+from __future__ import annotations
+
+
+# --- DAP protocol round-trips --------------------------------------------
+# debugpy is normally fast (single-digit ms) but some requests block on the
+# debuggee's main thread (e.g. evaluate during a long sync call). 30s gives
+# headroom for those without hanging a user-typed step forever.
+DAP_REQUEST = 30.0
+"""Default per-request timeout for `DAPClient._send`."""
+
+# Child-process DAPClient disconnect runs in parallel with the parent's
+# `disconnect(terminate=True)`. debugpy cascades termination from the
+# parent, so the per-child handshake is cleanup, not load-bearing — keep
+# it short so multi-process quit doesn't pile up 8 × 30s waits.
+DAP_DISCONNECT_CHILD = 1.0
+"""Wait for one child DAP session to acknowledge disconnect."""
+
+# Parent disconnect is also bounded. The parent's `disconnect` is what
+# actually kills the debuggee in non-remote-attach mode, so we wait a
+# bit longer than children — but still capped to keep quit snappy.
+DAP_DISCONNECT_PARENT = 2.0
+"""Wait for the parent DAP session to acknowledge disconnect."""
+
+# Time to wait for debugpy to emit `initialized` after launch/attach.
+# Cold debugpy start (no compiled cache, large dependency graph) can
+# take ~1-3s on modest machines; 10s is comfortable padding.
+DAP_INITIALIZED = 10.0
+"""Wait for `initialized` event after launch / attach."""
+
+# Time to wait for a `stopped` event after launch with `stop_on_entry=True`.
+# Same shape as DAP_INITIALIZED — we just need debugpy to reach line 1.
+DAP_STOP_ON_ENTRY = 10.0
+"""Wait for the first `stopped` event when stop_on_entry is set."""
+
+# Child-process attach handshake: after a `debugpyAttach` reverse event,
+# the child opens its DAP socket and we connect + initialize. 30s allows
+# for slow forkserver starts on Linux (Python 3.14 default).
+DAP_CHILD_ATTACH = 30.0
+"""End-to-end timeout for connecting + initializing a child DAP session."""
+
+
+# --- RPC handler waits ---------------------------------------------------
+# Step / continue can run a long tail in multi-process programs: after
+# releasing all breakpoint hits, the remainder of the script may run for
+# many seconds before `terminated` arrives. 30s wasn't enough; 10 min is
+# arbitrary-but-comfortable for typical interactive sessions.
+RPC_STEP_WAIT = 600.0
+"""How long the RPC `_step_action` blocks awaiting the next stop."""