1.. _debugger: 2 3:mod:`pdb` --- The Python Debugger 4================================== 5 6.. module:: pdb 7 :synopsis: The Python debugger for interactive interpreters. 8 9**Source code:** :source:`Lib/pdb.py` 10 11.. index:: single: debugging 12 13-------------- 14 15The module :mod:`pdb` defines an interactive source code debugger for Python 16programs. It supports setting (conditional) breakpoints and single stepping at 17the source line level, inspection of stack frames, source code listing, and 18evaluation of arbitrary Python code in the context of any stack frame. It also 19supports post-mortem debugging and can be called under program control. 20 21.. index:: 22 single: Pdb (class in pdb) 23 module: bdb 24 module: cmd 25 26The debugger is extensible -- it is actually defined as the class :class:`Pdb`. 27This is currently undocumented but easily understood by reading the source. The 28extension interface uses the modules :mod:`bdb` and :mod:`cmd`. 29 30The debugger's prompt is ``(Pdb)``. Typical usage to run a program under control 31of the debugger is:: 32 33 >>> import pdb 34 >>> import mymodule 35 >>> pdb.run('mymodule.test()') 36 > <string>(0)?() 37 (Pdb) continue 38 > <string>(1)?() 39 (Pdb) continue 40 NameError: 'spam' 41 > <string>(1)?() 42 (Pdb) 43 44.. versionchanged:: 3.3 45 Tab-completion via the :mod:`readline` module is available for commands and 46 command arguments, e.g. the current global and local names are offered as 47 arguments of the ``p`` command. 48 49:file:`pdb.py` can also be invoked as a script to debug other scripts. For 50example:: 51 52 python3 -m pdb myscript.py 53 54When invoked as a script, pdb will automatically enter post-mortem debugging if 55the program being debugged exits abnormally. After post-mortem debugging (or 56after normal exit of the program), pdb will restart the program. Automatic 57restarting preserves pdb's state (such as breakpoints) and in most cases is more 58useful than quitting the debugger upon program's exit. 59 60.. versionadded:: 3.2 61 :file:`pdb.py` now accepts a ``-c`` option that executes commands as if given 62 in a :file:`.pdbrc` file, see :ref:`debugger-commands`. 63 64.. versionadded:: 3.7 65 :file:`pdb.py` now accepts a ``-m`` option that execute modules similar to the way 66 ``python3 -m`` does. As with a script, the debugger will pause execution just 67 before the first line of the module. 68 69 70The typical usage to break into the debugger from a running program is to 71insert :: 72 73 import pdb; pdb.set_trace() 74 75at the location you want to break into the debugger. You can then step through 76the code following this statement, and continue running without the debugger 77using the :pdbcmd:`continue` command. 78 79.. versionadded:: 3.7 80 The built-in :func:`breakpoint()`, when called with defaults, can be used 81 instead of ``import pdb; pdb.set_trace()``. 82 83The typical usage to inspect a crashed program is:: 84 85 >>> import pdb 86 >>> import mymodule 87 >>> mymodule.test() 88 Traceback (most recent call last): 89 File "<stdin>", line 1, in <module> 90 File "./mymodule.py", line 4, in test 91 test2() 92 File "./mymodule.py", line 3, in test2 93 print(spam) 94 NameError: spam 95 >>> pdb.pm() 96 > ./mymodule.py(3)test2() 97 -> print(spam) 98 (Pdb) 99 100 101The module defines the following functions; each enters the debugger in a 102slightly different way: 103 104.. function:: run(statement, globals=None, locals=None) 105 106 Execute the *statement* (given as a string or a code object) under debugger 107 control. The debugger prompt appears before any code is executed; you can 108 set breakpoints and type :pdbcmd:`continue`, or you can step through the 109 statement using :pdbcmd:`step` or :pdbcmd:`next` (all these commands are 110 explained below). The optional *globals* and *locals* arguments specify the 111 environment in which the code is executed; by default the dictionary of the 112 module :mod:`__main__` is used. (See the explanation of the built-in 113 :func:`exec` or :func:`eval` functions.) 114 115 116.. function:: runeval(expression, globals=None, locals=None) 117 118 Evaluate the *expression* (given as a string or a code object) under debugger 119 control. When :func:`runeval` returns, it returns the value of the 120 expression. Otherwise this function is similar to :func:`run`. 121 122 123.. function:: runcall(function, *args, **kwds) 124 125 Call the *function* (a function or method object, not a string) with the 126 given arguments. When :func:`runcall` returns, it returns whatever the 127 function call returned. The debugger prompt appears as soon as the function 128 is entered. 129 130 131.. function:: set_trace(*, header=None) 132 133 Enter the debugger at the calling stack frame. This is useful to hard-code 134 a breakpoint at a given point in a program, even if the code is not 135 otherwise being debugged (e.g. when an assertion fails). If given, 136 *header* is printed to the console just before debugging begins. 137 138 .. versionchanged:: 3.7 139 The keyword-only argument *header*. 140 141 142.. function:: post_mortem(traceback=None) 143 144 Enter post-mortem debugging of the given *traceback* object. If no 145 *traceback* is given, it uses the one of the exception that is currently 146 being handled (an exception must be being handled if the default is to be 147 used). 148 149 150.. function:: pm() 151 152 Enter post-mortem debugging of the traceback found in 153 :data:`sys.last_traceback`. 154 155 156The ``run*`` functions and :func:`set_trace` are aliases for instantiating the 157:class:`Pdb` class and calling the method of the same name. If you want to 158access further features, you have to do this yourself: 159 160.. class:: Pdb(completekey='tab', stdin=None, stdout=None, skip=None, \ 161 nosigint=False, readrc=True) 162 163 :class:`Pdb` is the debugger class. 164 165 The *completekey*, *stdin* and *stdout* arguments are passed to the 166 underlying :class:`cmd.Cmd` class; see the description there. 167 168 The *skip* argument, if given, must be an iterable of glob-style module name 169 patterns. The debugger will not step into frames that originate in a module 170 that matches one of these patterns. [1]_ 171 172 By default, Pdb sets a handler for the SIGINT signal (which is sent when the 173 user presses :kbd:`Ctrl-C` on the console) when you give a ``continue`` command. 174 This allows you to break into the debugger again by pressing :kbd:`Ctrl-C`. If you 175 want Pdb not to touch the SIGINT handler, set *nosigint* to true. 176 177 The *readrc* argument defaults to true and controls whether Pdb will load 178 .pdbrc files from the filesystem. 179 180 Example call to enable tracing with *skip*:: 181 182 import pdb; pdb.Pdb(skip=['django.*']).set_trace() 183 184 .. audit-event:: pdb.Pdb "" pdb.Pdb 185 186 .. versionadded:: 3.1 187 The *skip* argument. 188 189 .. versionadded:: 3.2 190 The *nosigint* argument. Previously, a SIGINT handler was never set by 191 Pdb. 192 193 .. versionchanged:: 3.6 194 The *readrc* argument. 195 196 .. method:: run(statement, globals=None, locals=None) 197 runeval(expression, globals=None, locals=None) 198 runcall(function, *args, **kwds) 199 set_trace() 200 201 See the documentation for the functions explained above. 202 203 204.. _debugger-commands: 205 206Debugger Commands 207----------------- 208 209The commands recognized by the debugger are listed below. Most commands can be 210abbreviated to one or two letters as indicated; e.g. ``h(elp)`` means that 211either ``h`` or ``help`` can be used to enter the help command (but not ``he`` 212or ``hel``, nor ``H`` or ``Help`` or ``HELP``). Arguments to commands must be 213separated by whitespace (spaces or tabs). Optional arguments are enclosed in 214square brackets (``[]``) in the command syntax; the square brackets must not be 215typed. Alternatives in the command syntax are separated by a vertical bar 216(``|``). 217 218Entering a blank line repeats the last command entered. Exception: if the last 219command was a :pdbcmd:`list` command, the next 11 lines are listed. 220 221Commands that the debugger doesn't recognize are assumed to be Python statements 222and are executed in the context of the program being debugged. Python 223statements can also be prefixed with an exclamation point (``!``). This is a 224powerful way to inspect the program being debugged; it is even possible to 225change a variable or call a function. When an exception occurs in such a 226statement, the exception name is printed but the debugger's state is not 227changed. 228 229The debugger supports :ref:`aliases <debugger-aliases>`. Aliases can have 230parameters which allows one a certain level of adaptability to the context under 231examination. 232 233Multiple commands may be entered on a single line, separated by ``;;``. (A 234single ``;`` is not used as it is the separator for multiple commands in a line 235that is passed to the Python parser.) No intelligence is applied to separating 236the commands; the input is split at the first ``;;`` pair, even if it is in the 237middle of a quoted string. 238 239.. index:: 240 pair: .pdbrc; file 241 triple: debugger; configuration; file 242 243If a file :file:`.pdbrc` exists in the user's home directory or in the current 244directory, it is read in and executed as if it had been typed at the debugger 245prompt. This is particularly useful for aliases. If both files exist, the one 246in the home directory is read first and aliases defined there can be overridden 247by the local file. 248 249.. versionchanged:: 3.2 250 :file:`.pdbrc` can now contain commands that continue debugging, such as 251 :pdbcmd:`continue` or :pdbcmd:`next`. Previously, these commands had no 252 effect. 253 254 255.. pdbcommand:: h(elp) [command] 256 257 Without argument, print the list of available commands. With a *command* as 258 argument, print help about that command. ``help pdb`` displays the full 259 documentation (the docstring of the :mod:`pdb` module). Since the *command* 260 argument must be an identifier, ``help exec`` must be entered to get help on 261 the ``!`` command. 262 263.. pdbcommand:: w(here) 264 265 Print a stack trace, with the most recent frame at the bottom. An arrow 266 indicates the current frame, which determines the context of most commands. 267 268.. pdbcommand:: d(own) [count] 269 270 Move the current frame *count* (default one) levels down in the stack trace 271 (to a newer frame). 272 273.. pdbcommand:: u(p) [count] 274 275 Move the current frame *count* (default one) levels up in the stack trace (to 276 an older frame). 277 278.. pdbcommand:: b(reak) [([filename:]lineno | function) [, condition]] 279 280 With a *lineno* argument, set a break there in the current file. With a 281 *function* argument, set a break at the first executable statement within 282 that function. The line number may be prefixed with a filename and a colon, 283 to specify a breakpoint in another file (probably one that hasn't been loaded 284 yet). The file is searched on :data:`sys.path`. Note that each breakpoint 285 is assigned a number to which all the other breakpoint commands refer. 286 287 If a second argument is present, it is an expression which must evaluate to 288 true before the breakpoint is honored. 289 290 Without argument, list all breaks, including for each breakpoint, the number 291 of times that breakpoint has been hit, the current ignore count, and the 292 associated condition if any. 293 294.. pdbcommand:: tbreak [([filename:]lineno | function) [, condition]] 295 296 Temporary breakpoint, which is removed automatically when it is first hit. 297 The arguments are the same as for :pdbcmd:`break`. 298 299.. pdbcommand:: cl(ear) [filename:lineno | bpnumber ...] 300 301 With a *filename:lineno* argument, clear all the breakpoints at this line. 302 With a space separated list of breakpoint numbers, clear those breakpoints. 303 Without argument, clear all breaks (but first ask confirmation). 304 305.. pdbcommand:: disable [bpnumber ...] 306 307 Disable the breakpoints given as a space separated list of breakpoint 308 numbers. Disabling a breakpoint means it cannot cause the program to stop 309 execution, but unlike clearing a breakpoint, it remains in the list of 310 breakpoints and can be (re-)enabled. 311 312.. pdbcommand:: enable [bpnumber ...] 313 314 Enable the breakpoints specified. 315 316.. pdbcommand:: ignore bpnumber [count] 317 318 Set the ignore count for the given breakpoint number. If count is omitted, 319 the ignore count is set to 0. A breakpoint becomes active when the ignore 320 count is zero. When non-zero, the count is decremented each time the 321 breakpoint is reached and the breakpoint is not disabled and any associated 322 condition evaluates to true. 323 324.. pdbcommand:: condition bpnumber [condition] 325 326 Set a new *condition* for the breakpoint, an expression which must evaluate 327 to true before the breakpoint is honored. If *condition* is absent, any 328 existing condition is removed; i.e., the breakpoint is made unconditional. 329 330.. pdbcommand:: commands [bpnumber] 331 332 Specify a list of commands for breakpoint number *bpnumber*. The commands 333 themselves appear on the following lines. Type a line containing just 334 ``end`` to terminate the commands. An example:: 335 336 (Pdb) commands 1 337 (com) p some_variable 338 (com) end 339 (Pdb) 340 341 To remove all commands from a breakpoint, type ``commands`` and follow it 342 immediately with ``end``; that is, give no commands. 343 344 With no *bpnumber* argument, ``commands`` refers to the last breakpoint set. 345 346 You can use breakpoint commands to start your program up again. Simply use 347 the :pdbcmd:`continue` command, or :pdbcmd:`step`, 348 or any other command that resumes execution. 349 350 Specifying any command resuming execution 351 (currently :pdbcmd:`continue`, :pdbcmd:`step`, :pdbcmd:`next`, 352 :pdbcmd:`return`, :pdbcmd:`jump`, :pdbcmd:`quit` and their abbreviations) 353 terminates the command list (as if 354 that command was immediately followed by end). This is because any time you 355 resume execution (even with a simple next or step), you may encounter another 356 breakpoint—which could have its own command list, leading to ambiguities about 357 which list to execute. 358 359 If you use the 'silent' command in the command list, the usual message about 360 stopping at a breakpoint is not printed. This may be desirable for breakpoints 361 that are to print a specific message and then continue. If none of the other 362 commands print anything, you see no sign that the breakpoint was reached. 363 364.. pdbcommand:: s(tep) 365 366 Execute the current line, stop at the first possible occasion (either in a 367 function that is called or on the next line in the current function). 368 369.. pdbcommand:: n(ext) 370 371 Continue execution until the next line in the current function is reached or 372 it returns. (The difference between :pdbcmd:`next` and :pdbcmd:`step` is 373 that :pdbcmd:`step` stops inside a called function, while :pdbcmd:`next` 374 executes called functions at (nearly) full speed, only stopping at the next 375 line in the current function.) 376 377.. pdbcommand:: unt(il) [lineno] 378 379 Without argument, continue execution until the line with a number greater 380 than the current one is reached. 381 382 With a line number, continue execution until a line with a number greater or 383 equal to that is reached. In both cases, also stop when the current frame 384 returns. 385 386 .. versionchanged:: 3.2 387 Allow giving an explicit line number. 388 389.. pdbcommand:: r(eturn) 390 391 Continue execution until the current function returns. 392 393.. pdbcommand:: c(ont(inue)) 394 395 Continue execution, only stop when a breakpoint is encountered. 396 397.. pdbcommand:: j(ump) lineno 398 399 Set the next line that will be executed. Only available in the bottom-most 400 frame. This lets you jump back and execute code again, or jump forward to 401 skip code that you don't want to run. 402 403 It should be noted that not all jumps are allowed -- for instance it is not 404 possible to jump into the middle of a :keyword:`for` loop or out of a 405 :keyword:`finally` clause. 406 407.. pdbcommand:: l(ist) [first[, last]] 408 409 List source code for the current file. Without arguments, list 11 lines 410 around the current line or continue the previous listing. With ``.`` as 411 argument, list 11 lines around the current line. With one argument, 412 list 11 lines around at that line. With two arguments, list the given range; 413 if the second argument is less than the first, it is interpreted as a count. 414 415 The current line in the current frame is indicated by ``->``. If an 416 exception is being debugged, the line where the exception was originally 417 raised or propagated is indicated by ``>>``, if it differs from the current 418 line. 419 420 .. versionadded:: 3.2 421 The ``>>`` marker. 422 423.. pdbcommand:: ll | longlist 424 425 List all source code for the current function or frame. Interesting lines 426 are marked as for :pdbcmd:`list`. 427 428 .. versionadded:: 3.2 429 430.. pdbcommand:: a(rgs) 431 432 Print the argument list of the current function. 433 434.. pdbcommand:: p expression 435 436 Evaluate the *expression* in the current context and print its value. 437 438 .. note:: 439 440 ``print()`` can also be used, but is not a debugger command --- this executes the 441 Python :func:`print` function. 442 443 444.. pdbcommand:: pp expression 445 446 Like the :pdbcmd:`p` command, except the value of the expression is 447 pretty-printed using the :mod:`pprint` module. 448 449.. pdbcommand:: whatis expression 450 451 Print the type of the *expression*. 452 453.. pdbcommand:: source expression 454 455 Try to get source code for the given object and display it. 456 457 .. versionadded:: 3.2 458 459.. pdbcommand:: display [expression] 460 461 Display the value of the expression if it changed, each time execution stops 462 in the current frame. 463 464 Without expression, list all display expressions for the current frame. 465 466 .. versionadded:: 3.2 467 468.. pdbcommand:: undisplay [expression] 469 470 Do not display the expression any more in the current frame. Without 471 expression, clear all display expressions for the current frame. 472 473 .. versionadded:: 3.2 474 475.. pdbcommand:: interact 476 477 Start an interactive interpreter (using the :mod:`code` module) whose global 478 namespace contains all the (global and local) names found in the current 479 scope. 480 481 .. versionadded:: 3.2 482 483.. _debugger-aliases: 484 485.. pdbcommand:: alias [name [command]] 486 487 Create an alias called *name* that executes *command*. The command must 488 *not* be enclosed in quotes. Replaceable parameters can be indicated by 489 ``%1``, ``%2``, and so on, while ``%*`` is replaced by all the parameters. 490 If no command is given, the current alias for *name* is shown. If no 491 arguments are given, all aliases are listed. 492 493 Aliases may be nested and can contain anything that can be legally typed at 494 the pdb prompt. Note that internal pdb commands *can* be overridden by 495 aliases. Such a command is then hidden until the alias is removed. Aliasing 496 is recursively applied to the first word of the command line; all other words 497 in the line are left alone. 498 499 As an example, here are two useful aliases (especially when placed in the 500 :file:`.pdbrc` file):: 501 502 # Print instance variables (usage "pi classInst") 503 alias pi for k in %1.__dict__.keys(): print("%1.",k,"=",%1.__dict__[k]) 504 # Print instance variables in self 505 alias ps pi self 506 507.. pdbcommand:: unalias name 508 509 Delete the specified alias. 510 511.. pdbcommand:: ! statement 512 513 Execute the (one-line) *statement* in the context of the current stack frame. 514 The exclamation point can be omitted unless the first word of the statement 515 resembles a debugger command. To set a global variable, you can prefix the 516 assignment command with a :keyword:`global` statement on the same line, 517 e.g.:: 518 519 (Pdb) global list_options; list_options = ['-l'] 520 (Pdb) 521 522.. pdbcommand:: run [args ...] 523 restart [args ...] 524 525 Restart the debugged Python program. If an argument is supplied, it is split 526 with :mod:`shlex` and the result is used as the new :data:`sys.argv`. 527 History, breakpoints, actions and debugger options are preserved. 528 :pdbcmd:`restart` is an alias for :pdbcmd:`run`. 529 530.. pdbcommand:: q(uit) 531 532 Quit from the debugger. The program being executed is aborted. 533 534.. pdbcommand:: debug code 535 536 Enter a recursive debugger that steps through the code 537 argument (which is an arbitrary expression or statement to be 538 executed in the current environment). 539 540.. pdbcommand:: retval 541 542 Print the return value for the last return of a function. 543 544.. rubric:: Footnotes 545 546.. [1] Whether a frame is considered to originate in a certain module 547 is determined by the ``__name__`` in the frame globals. 548