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