ReStructuredText | 353 lines | 263 code | 90 blank | 0 comment | 0 complexity | 77eea77bf6641a519205e02c38b319fc MD5 | raw file
1 2.. _debugger: 3 4:mod:`pdb` --- The Python Debugger 5================================== 6 7.. module:: pdb 8 :synopsis: The Python debugger for interactive interpreters. 9 10 11.. index:: single: debugging 12 13The module :mod:`pdb` defines an interactive source code debugger for Python 14programs. It supports setting (conditional) breakpoints and single stepping at 15the source line level, inspection of stack frames, source code listing, and 16evaluation of arbitrary Python code in the context of any stack frame. It also 17supports post-mortem debugging and can be called under program control. 18 19.. index:: 20 single: Pdb (class in pdb) 21 module: bdb 22 module: cmd 23 24The debugger is extensible --- it is actually defined as the class :class:`Pdb`. 25This is currently undocumented but easily understood by reading the source. The 26extension interface uses the modules :mod:`bdb` (undocumented) and :mod:`cmd`. 27 28The debugger's prompt is ``(Pdb)``. Typical usage to run a program under control 29of the debugger is:: 30 31 >>> import pdb 32 >>> import mymodule 33 >>> pdb.run('mymodule.test()') 34 > <string>(0)?() 35 (Pdb) continue 36 > <string>(1)?() 37 (Pdb) continue 38 NameError: 'spam' 39 > <string>(1)?() 40 (Pdb) 41 42:file:`pdb.py` can also be invoked as a script to debug other scripts. For 43example:: 44 45 python -m pdb myscript.py 46 47When invoked as a script, pdb will automatically enter post-mortem debugging if 48the program being debugged exits abnormally. After post-mortem debugging (or 49after normal exit of the program), pdb will restart the program. Automatic 50restarting preserves pdb's state (such as breakpoints) and in most cases is more 51useful than quitting the debugger upon program's exit. 52 53.. versionadded:: 2.4 54 Restarting post-mortem behavior added. 55 56Typical usage to inspect a crashed program is:: 57 58 >>> import pdb 59 >>> import mymodule 60 >>> mymodule.test() 61 Traceback (most recent call last): 62 File "<stdin>", line 1, in ? 63 File "./mymodule.py", line 4, in test 64 test2() 65 File "./mymodule.py", line 3, in test2 66 print spam 67 NameError: spam 68 >>> pdb.pm() 69 > ./mymodule.py(3)test2() 70 -> print spam 71 (Pdb) 72 73The module defines the following functions; each enters the debugger in a 74slightly different way: 75 76 77.. function:: run(statement[, globals[, locals]]) 78 79 Execute the *statement* (given as a string) under debugger control. The 80 debugger prompt appears before any code is executed; you can set breakpoints and 81 type ``continue``, or you can step through the statement using ``step`` or 82 ``next`` (all these commands are explained below). The optional *globals* and 83 *locals* arguments specify the environment in which the code is executed; by 84 default the dictionary of the module :mod:`__main__` is used. (See the 85 explanation of the :keyword:`exec` statement or the :func:`eval` built-in 86 function.) 87 88 89.. function:: runeval(expression[, globals[, locals]]) 90 91 Evaluate the *expression* (given as a string) under debugger control. When 92 :func:`runeval` returns, it returns the value of the expression. Otherwise this 93 function is similar to :func:`run`. 94 95 96.. function:: runcall(function[, argument, ...]) 97 98 Call the *function* (a function or method object, not a string) with the given 99 arguments. When :func:`runcall` returns, it returns whatever the function call 100 returned. The debugger prompt appears as soon as the function is entered. 101 102 103.. function:: set_trace() 104 105 Enter the debugger at the calling stack frame. This is useful to hard-code a 106 breakpoint at a given point in a program, even if the code is not otherwise 107 being debugged (e.g. when an assertion fails). 108 109 110.. function:: post_mortem([traceback]) 111 112 Enter post-mortem debugging of the given *traceback* object. If no 113 *traceback* is given, it uses the one of the exception that is currently 114 being handled (an exception must be being handled if the default is to be 115 used). 116 117 118.. function:: pm() 119 120 Enter post-mortem debugging of the traceback found in ``sys.last_traceback``. 121 122 123.. _debugger-commands: 124 125Debugger Commands 126================= 127 128The debugger recognizes the following commands. Most commands can be 129abbreviated to one or two letters; e.g. ``h(elp)`` means that either ``h`` or 130``help`` can be used to enter the help command (but not ``he`` or ``hel``, nor 131``H`` or ``Help`` or ``HELP``). Arguments to commands must be separated by 132whitespace (spaces or tabs). Optional arguments are enclosed in square brackets 133(````) in the command syntax; the square brackets must not be typed. 134Alternatives in the command syntax are separated by a vertical bar (``|``). 135 136Entering a blank line repeats the last command entered. Exception: if the last 137command was a ``list`` command, the next 11 lines are listed. 138 139Commands that the debugger doesn't recognize are assumed to be Python statements 140and are executed in the context of the program being debugged. Python 141statements can also be prefixed with an exclamation point (``!``). This is a 142powerful way to inspect the program being debugged; it is even possible to 143change a variable or call a function. When an exception occurs in such a 144statement, the exception name is printed but the debugger's state is not 145changed. 146 147Multiple commands may be entered on a single line, separated by ``;;``. (A 148single ``;`` is not used as it is the separator for multiple commands in a line 149that is passed to the Python parser.) No intelligence is applied to separating 150the commands; the input is split at the first ``;;`` pair, even if it is in the 151middle of a quoted string. 152 153The debugger supports aliases. Aliases can have parameters which allows one a 154certain level of adaptability to the context under examination. 155 156.. index:: 157 pair: .pdbrc; file 158 triple: debugger; configuration; file 159 160If a file :file:`.pdbrc` exists in the user's home directory or in the current 161directory, it is read in and executed as if it had been typed at the debugger 162prompt. This is particularly useful for aliases. If both files exist, the one 163in the home directory is read first and aliases defined there can be overridden 164by the local file. 165 166h(elp) [*command*] 167 Without argument, print the list of available commands. With a *command* as 168 argument, print help about that command. ``help pdb`` displays the full 169 documentation file; if the environment variable :envvar:`PAGER` is defined, the 170 file is piped through that command instead. Since the *command* argument must 171 be an identifier, ``help exec`` must be entered to get help on the ``!`` 172 command. 173 174w(here) 175 Print a stack trace, with the most recent frame at the bottom. An arrow 176 indicates the current frame, which determines the context of most commands. 177 178d(own) 179 Move the current frame one level down in the stack trace (to a newer frame). 180 181u(p) 182 Move the current frame one level up in the stack trace (to an older frame). 183 184b(reak) [[*filename*:]\ *lineno* | *function*\ [, *condition*]] 185 With a *lineno* argument, set a break there in the current file. With a 186 *function* argument, set a break at the first executable statement within that 187 function. The line number may be prefixed with a filename and a colon, to 188 specify a breakpoint in another file (probably one that hasn't been loaded yet). 189 The file is searched on ``sys.path``. Note that each breakpoint is assigned a 190 number to which all the other breakpoint commands refer. 191 192 If a second argument is present, it is an expression which must evaluate to true 193 before the breakpoint is honored. 194 195 Without argument, list all breaks, including for each breakpoint, the number of 196 times that breakpoint has been hit, the current ignore count, and the associated 197 condition if any. 198 199tbreak [[*filename*:]\ *lineno* | *function*\ [, *condition*]] 200 Temporary breakpoint, which is removed automatically when it is first hit. The 201 arguments are the same as break. 202 203cl(ear) [*bpnumber* [*bpnumber ...*]] 204 With a space separated list of breakpoint numbers, clear those breakpoints. 205 Without argument, clear all breaks (but first ask confirmation). 206 207disable [*bpnumber* [*bpnumber ...*]] 208 Disables the breakpoints given as a space separated list of breakpoint numbers. 209 Disabling a breakpoint means it cannot cause the program to stop execution, but 210 unlike clearing a breakpoint, it remains in the list of breakpoints and can be 211 (re-)enabled. 212 213enable [*bpnumber* [*bpnumber ...*]] 214 Enables the breakpoints specified. 215 216ignore *bpnumber* [*count*] 217 Sets the ignore count for the given breakpoint number. If count is omitted, the 218 ignore count is set to 0. A breakpoint becomes active when the ignore count is 219 zero. When non-zero, the count is decremented each time the breakpoint is 220 reached and the breakpoint is not disabled and any associated condition 221 evaluates to true. 222 223condition *bpnumber* [*condition*] 224 Condition is an expression which must evaluate to true before the breakpoint is 225 honored. If condition is absent, any existing condition is removed; i.e., the 226 breakpoint is made unconditional. 227 228commands [*bpnumber*] 229 Specify a list of commands for breakpoint number *bpnumber*. The commands 230 themselves appear on the following lines. Type a line containing just 'end' to 231 terminate the commands. An example:: 232 233 (Pdb) commands 1 234 (com) print some_variable 235 (com) end 236 (Pdb) 237 238 To remove all commands from a breakpoint, type commands and follow it 239 immediately with end; that is, give no commands. 240 241 With no *bpnumber* argument, commands refers to the last breakpoint set. 242 243 You can use breakpoint commands to start your program up again. Simply use the 244 continue command, or step, or any other command that resumes execution. 245 246 Specifying any command resuming execution (currently continue, step, next, 247 return, jump, quit and their abbreviations) terminates the command list (as if 248 that command was immediately followed by end). This is because any time you 249 resume execution (even with a simple next or step), you may encounter another 250 breakpoint--which could have its own command list, leading to ambiguities about 251 which list to execute. 252 253 If you use the 'silent' command in the command list, the usual message about 254 stopping at a breakpoint is not printed. This may be desirable for breakpoints 255 that are to print a specific message and then continue. If none of the other 256 commands print anything, you see no sign that the breakpoint was reached. 257 258 .. versionadded:: 2.5 259 260s(tep) 261 Execute the current line, stop at the first possible occasion (either in a 262 function that is called or on the next line in the current function). 263 264n(ext) 265 Continue execution until the next line in the current function is reached or it 266 returns. (The difference between ``next`` and ``step`` is that ``step`` stops 267 inside a called function, while ``next`` executes called functions at (nearly) 268 full speed, only stopping at the next line in the current function.) 269 270unt(il) 271 Continue execution until the line with the line number greater than the 272 current one is reached or when returning from current frame. 273 274 .. versionadded:: 2.6 275 276r(eturn) 277 Continue execution until the current function returns. 278 279c(ont(inue)) 280 Continue execution, only stop when a breakpoint is encountered. 281 282j(ump) *lineno* 283 Set the next line that will be executed. Only available in the bottom-most 284 frame. This lets you jump back and execute code again, or jump forward to skip 285 code that you don't want to run. 286 287 It should be noted that not all jumps are allowed --- for instance it is not 288 possible to jump into the middle of a :keyword:`for` loop or out of a 289 :keyword:`finally` clause. 290 291l(ist) [*first*\ [, *last*]] 292 List source code for the current file. Without arguments, list 11 lines around 293 the current line or continue the previous listing. With one argument, list 11 294 lines around at that line. With two arguments, list the given range; if the 295 second argument is less than the first, it is interpreted as a count. 296 297a(rgs) 298 Print the argument list of the current function. 299 300p *expression* 301 Evaluate the *expression* in the current context and print its value. 302 303 .. note:: 304 305 ``print`` can also be used, but is not a debugger command --- this executes the 306 Python :keyword:`print` statement. 307 308pp *expression* 309 Like the ``p`` command, except the value of the expression is pretty-printed 310 using the :mod:`pprint` module. 311 312alias [*name* [command]] 313 Creates an alias called *name* that executes *command*. The command must *not* 314 be enclosed in quotes. Replaceable parameters can be indicated by ``%1``, 315 ``%2``, and so on, while ``%*`` is replaced by all the parameters. If no 316 command is given, the current alias for *name* is shown. If no arguments are 317 given, all aliases are listed. 318 319 Aliases may be nested and can contain anything that can be legally typed at the 320 pdb prompt. Note that internal pdb commands *can* be overridden by aliases. 321 Such a command is then hidden until the alias is removed. Aliasing is 322 recursively applied to the first word of the command line; all other words in 323 the line are left alone. 324 325 As an example, here are two useful aliases (especially when placed in the 326 :file:`.pdbrc` file):: 327 328 #Print instance variables (usage "pi classInst") 329 alias pi for k in %1.__dict__.keys(): print "%1.",k,"=",%1.__dict__[k] 330 #Print instance variables in self 331 alias ps pi self 332 333unalias *name* 334 Deletes the specified alias. 335 336[!]\ *statement* 337 Execute the (one-line) *statement* in the context of the current stack frame. 338 The exclamation point can be omitted unless the first word of the statement 339 resembles a debugger command. To set a global variable, you can prefix the 340 assignment command with a ``global`` command on the same line, e.g.:: 341 342 (Pdb) global list_options; list_options = ['-l'] 343 (Pdb) 344 345run [*args* ...] 346 Restart the debugged python program. If an argument is supplied, it is split 347 with "shlex" and the result is used as the new sys.argv. History, breakpoints, 348 actions and debugger options are preserved. "restart" is an alias for "run". 349 350 .. versionadded:: 2.6 351 352q(uit) 353 Quit from the debugger. The program being executed is aborted.