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