Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 1 | The Python Debugger |
| 2 | =================== |
| 3 | |
| 4 | To use the debugger in its simplest form: |
| 5 | |
Guido van Rossum | 136a112 | 1998-07-20 23:22:51 +0000 | [diff] [blame] | 6 | >>> import pdb |
| 7 | >>> pdb.run('<a statement>') |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 8 | |
| 9 | The debugger's prompt is '(Pdb) '. This will stop in the first |
| 10 | function call in <a statement>. |
| 11 | |
Guido van Rossum | 3577113 | 1992-09-08 11:59:04 +0000 | [diff] [blame] | 12 | Alternatively, if a statement terminated with an unhandled exception, |
| 13 | you can use pdb's post-mortem facility to inspect the contents of the |
| 14 | traceback: |
| 15 | |
Guido van Rossum | 136a112 | 1998-07-20 23:22:51 +0000 | [diff] [blame] | 16 | >>> <a statement> |
| 17 | <exception traceback> |
| 18 | >>> import pdb |
| 19 | >>> pdb.pm() |
Guido van Rossum | 3577113 | 1992-09-08 11:59:04 +0000 | [diff] [blame] | 20 | |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 21 | The commands recognized by the debugger are listed in the next |
| 22 | section. Most can be abbreviated as indicated; e.g., h(elp) means |
| 23 | that 'help' can be typed as 'h' or 'help' (but not as 'he' or 'hel', |
| 24 | nor as 'H' or 'Help' or 'HELP'). Optional arguments are enclosed in |
| 25 | square brackets. |
| 26 | |
| 27 | A blank line repeats the previous command literally. (Except for |
| 28 | 'list', where it lists the next 11 lines.) |
| 29 | |
| 30 | Commands that the debugger doesn't recognize are assumed to be Python |
| 31 | statements and are executed in the context of the program being |
| 32 | debugged. Python statements can also be prefixed with an exclamation |
| 33 | point ('!'). This is a powerful way to inspect the program being |
| 34 | debugged; it is even possible to change variables. When an exception |
| 35 | occurs in such a statement, the exception name is printed but the |
| 36 | debugger's state is not changed. |
| 37 | |
| 38 | The debugger is not directly programmable; but it is implemented as a |
| 39 | class from which you can derive your own debugger class, so you can |
| 40 | make as fancy as you like. |
| 41 | |
| 42 | |
| 43 | Debugger commands |
| 44 | ================= |
| 45 | |
| 46 | h(elp) |
Guido van Rossum | f60e8e8 | 1998-07-20 23:21:21 +0000 | [diff] [blame] | 47 | Without argument, print the list of available commands. |
| 48 | With a command name as argument, print help about that command |
| 49 | "help pdb" pipes the full documentation file to the $PAGER |
| 50 | "help exec" gives help on the ! command |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 51 | |
| 52 | w(here) |
Guido van Rossum | 136a112 | 1998-07-20 23:22:51 +0000 | [diff] [blame] | 53 | Print a stack trace, with the most recent frame at the bottom. |
| 54 | An arrow indicates the "current frame", which determines the |
| 55 | context of most commands. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 56 | |
| 57 | d(own) |
Guido van Rossum | 136a112 | 1998-07-20 23:22:51 +0000 | [diff] [blame] | 58 | Move the current frame one level down in the stack trace |
| 59 | (to an older frame). |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 60 | |
| 61 | u(p) |
Guido van Rossum | 136a112 | 1998-07-20 23:22:51 +0000 | [diff] [blame] | 62 | Move the current frame one level up in the stack trace |
| 63 | (to a newer frame). |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 64 | |
Guido van Rossum | f60e8e8 | 1998-07-20 23:21:21 +0000 | [diff] [blame] | 65 | b(reak) ([file:]lineno | function) [, "condition"] |
| 66 | With a line number argument, set a break there in the current |
| 67 | file. With a function name, set a break at the entry of that |
| 68 | function. Without argument, list all breaks. If a second |
| 69 | argument is present, it is a string specifying an expression |
| 70 | which must evaluate to true before the breakpoint is honored. |
| 71 | |
| 72 | The line number may be prefixed with a filename and a colon, |
| 73 | to specify a breakpoint in another file (probably one that |
| 74 | hasn't been loaded yet). The file is searched on sys.path. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 75 | |
| 76 | cl(ear) [lineno] |
Guido van Rossum | 136a112 | 1998-07-20 23:22:51 +0000 | [diff] [blame] | 77 | With a line number argument, clear that break in the current file. |
| 78 | Without argument, clear all breaks (but first ask confirmation). |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 79 | |
Guido van Rossum | f60e8e8 | 1998-07-20 23:21:21 +0000 | [diff] [blame] | 80 | The line number may be prefixed with a filename and a colon, |
| 81 | to specify a breakpoint in another file (probably one that |
| 82 | hasn't been loaded yet). The file is searched on sys.path. |
| 83 | |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 84 | s(tep) |
Guido van Rossum | 136a112 | 1998-07-20 23:22:51 +0000 | [diff] [blame] | 85 | Execute the current line, stop at the first possible occasion |
| 86 | (either in a function that is called or in the current function). |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 87 | |
| 88 | n(ext) |
Guido van Rossum | 136a112 | 1998-07-20 23:22:51 +0000 | [diff] [blame] | 89 | Continue execution until the next line in the current function |
| 90 | is reached or it returns. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 91 | |
| 92 | r(eturn) |
Guido van Rossum | 136a112 | 1998-07-20 23:22:51 +0000 | [diff] [blame] | 93 | Continue execution until the current function returns. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 94 | |
| 95 | c(ont(inue)) |
Guido van Rossum | 136a112 | 1998-07-20 23:22:51 +0000 | [diff] [blame] | 96 | Continue execution, only stop when a breakpoint is encountered. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 97 | |
| 98 | l(ist) [first [,last]] |
Guido van Rossum | 136a112 | 1998-07-20 23:22:51 +0000 | [diff] [blame] | 99 | List source code for the current file. |
| 100 | Without arguments, list 11 lines around the current line |
| 101 | or continue the previous listing. |
| 102 | With one argument, list 11 lines starting at that line. |
| 103 | With two arguments, list the given range; |
| 104 | if the second argument is less than the first, it is a count. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 105 | |
| 106 | a(rgs) |
Guido van Rossum | 136a112 | 1998-07-20 23:22:51 +0000 | [diff] [blame] | 107 | Print the argument list of the current function. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 108 | |
| 109 | p expression |
Guido van Rossum | 136a112 | 1998-07-20 23:22:51 +0000 | [diff] [blame] | 110 | Print the value of the expression. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 111 | |
| 112 | (!) statement |
Guido van Rossum | 136a112 | 1998-07-20 23:22:51 +0000 | [diff] [blame] | 113 | Execute the (one-line) statement in the context of |
| 114 | the current stack frame. |
| 115 | The exclamation point can be omitted unless the first word |
| 116 | of the statement resembles a debugger command. |
| 117 | To assign to a global variable you must always prefix the |
| 118 | command with a 'global' command, e.g.: |
| 119 | (Pdb) global list_options; list_options = ['-l'] |
| 120 | (Pdb) |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 121 | |
| 122 | q(uit) |
Guido van Rossum | 136a112 | 1998-07-20 23:22:51 +0000 | [diff] [blame] | 123 | Quit from the debugger. |
| 124 | The program being executed is aborted. |