What does `python -m pdb script.py` do when the script dies with an uncaught exception?

### What the launcher actually does `python -m pdb script.py` executes `script.py` under the control of `pdb`, the standard library's debugger. Arguments after the script name are passed to the script, so `python -m pdb bidder.py --dry-run` gives the script its own `--dry-run`. Since 3.7 you can debug a module instead of a file with `python -m pdb -m package.module`, and `-c CMD` runs a pdb command before execution starts, which is how `-c continue` turns the debugger from *interactive from line one* into a *crash trap*. By default the launcher stops at the first statement of the script and gives you a prompt. That is the pre-failure use of the debugger. The behaviour that makes the launcher interesting for debugging a crash is what happens at the other end. ### Post-mortem entry Normally an exception that no `except` clause handles unwinds every frame, the interpreter prints the traceback to standard error, and the process exits with a non-zero status. The frames are gone by the time you read the traceback, so the only state you have is what the traceback text happened to print. Under `python -m pdb`, the debugger is the outermost caller, so it sees the exception before the process can die. It prints the traceback, prints `Uncaught exception. Entering post mortem debugging`, and opens a prompt. Crucially the prompt is *not* at the top of the program: pdb walks to the innermost frame recorded in the exception's traceback - the frame where the `raise` (or the failing operation) happened - and puts you there. The line marker shows the offending source line. That means the local variables of the raising function are still reachable. If a list index blew up, you can print the list and the index; if a lookup failed, you can print the key and the container. This is the whole value proposition of post-mortem work: you debug the failure you already have rather than adding a breakpoint and re-running, hoping the failure reproduces. ```console $ python -m pdb -c continue bidder.py IndexError: list index out of range Uncaught exception. Entering post mortem debugging Running 'cont' or 'step' will restart the program > /srv/bidder.py(2)settle() -> return order[2] (Pdb) p order ['impression', 'click'] ``` ### The frames are dead The single most important property of post-mortem mode, and the one candidates get wrong, is that the stack you are standing in has already unwound. The traceback holds references to the frame objects, which is why their names are still readable, but the interpreter is no longer executing them. You therefore cannot step forward from the raise, cannot 'fix' a variable and continue, and cannot see what the next line would have done. `up` and `down` move your view along the captured chain of frames; that is navigation, not execution. Because there is nothing to resume, pdb repurposes the resume commands: typing `continue` or `step` in post-mortem mode **restarts the program from the beginning** under the same debugger session, which is what the banner is warning you about. State such as breakpoints survives the restart, so the normal workflow is: crash, inspect the raising frame, set a breakpoint slightly earlier, then restart and watch the failure develop. `q` leaves the debugger. ### Reading the traceback pdb prints Since 3.11 (PEP 657) tracebacks carry column information, so the traceback printed just before the post-mortem prompt underlines the exact subexpression that failed - useful when a line contains several subscripts or calls and the exception type alone does not say which one blew up. ### What the snapshot cannot tell you Inspection is limited to what the frames actually hold at the instant of the raise. A local that had not been assigned yet simply is not there; a name that was rebound shows only its last value; an iterator that was partially consumed shows its exhausted state, not the items it yielded. Comprehensions and generator expressions run in frames of their own, so a failure inside one lands you in a frame whose only names are the loop variable and the iterable. Post-mortem answers 'what was true when it broke', never 'how did it get that way' - which is why the standard workflow is to inspect the wreck, form a hypothesis about an earlier moment, set a breakpoint there, and let `continue` restart the program to test it. ### When this is the wrong tool The launcher requires a terminal and a script you can start yourself. It does not help with a process that is already running (that is what an attach mechanism is for), and it does not help with a batch job on a scheduler where nobody is watching the tty - a debugger prompt there simply hangs until something kills it. For those, the same post-mortem idea is applied from inside the program instead: catch the exception, and either hand its traceback to the debugger explicitly or serialize the frames' state for later reading.