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