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