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