diff options
Diffstat (limited to 'Doc/library/pdb.rst')
| -rw-r--r-- | Doc/library/pdb.rst | 409 |
1 files changed, 409 insertions, 0 deletions
diff --git a/Doc/library/pdb.rst b/Doc/library/pdb.rst new file mode 100644 index 0000000..804dd23 --- /dev/null +++ b/Doc/library/pdb.rst @@ -0,0 +1,409 @@ + +.. _debugger: + +******************* +The Python Debugger +******************* + +.. module:: pdb + :synopsis: The Python debugger for interactive interpreters. + + +.. index:: single: debugging + +The module :mod:`pdb` defines an interactive source code debugger for Python +programs. It supports setting (conditional) breakpoints and single stepping at +the source line level, inspection of stack frames, source code listing, and +evaluation of arbitrary Python code in the context of any stack frame. It also +supports post-mortem debugging and can be called under program control. + +.. index:: + single: Pdb (class in pdb) + module: bdb + module: cmd + +The debugger is extensible --- it is actually defined as the class :class:`Pdb`. +This is currently undocumented but easily understood by reading the source. The +extension interface uses the modules :mod:`bdb` (undocumented) and :mod:`cmd`. + +The debugger's prompt is ``(Pdb)``. Typical usage to run a program under control +of the debugger is:: + + >>> import pdb + >>> import mymodule + >>> pdb.run('mymodule.test()') + > <string>(0)?() + (Pdb) continue + > <string>(1)?() + (Pdb) continue + NameError: 'spam' + > <string>(1)?() + (Pdb) + +:file:`pdb.py` can also be invoked as a script to debug other scripts. For +example:: + + python -m pdb myscript.py + +When invoked as a script, pdb will automatically enter post-mortem debugging if +the program being debugged exits abnormally. After post-mortem debugging (or +after normal exit of the program), pdb will restart the program. Automatic +restarting preserves pdb's state (such as breakpoints) and in most cases is more +useful than quitting the debugger upon program's exit. + +.. versionadded:: 2.4 + Restarting post-mortem behavior added. + +Typical usage to inspect a crashed program is:: + + >>> import pdb + >>> import mymodule + >>> mymodule.test() + Traceback (most recent call last): + File "<stdin>", line 1, in ? + File "./mymodule.py", line 4, in test + test2() + File "./mymodule.py", line 3, in test2 + print spam + NameError: spam + >>> pdb.pm() + > ./mymodule.py(3)test2() + -> print spam + (Pdb) + +The module defines the following functions; each enters the debugger in a +slightly different way: + + +.. function:: run(statement[, globals[, locals]]) + + Execute the *statement* (given as a string) under debugger control. The + debugger prompt appears before any code is executed; you can set breakpoints and + type ``continue``, or you can step through the statement using ``step`` or + ``next`` (all these commands are explained below). The optional *globals* and + *locals* arguments specify the environment in which the code is executed; by + default the dictionary of the module :mod:`__main__` is used. (See the + explanation of the built-in :func:`exec` or :func:`eval` functions.) + + +.. function:: runeval(expression[, globals[, locals]]) + + Evaluate the *expression* (given as a string) under debugger control. When + :func:`runeval` returns, it returns the value of the expression. Otherwise this + function is similar to :func:`run`. + + +.. function:: runcall(function[, argument, ...]) + + Call the *function* (a function or method object, not a string) with the given + arguments. When :func:`runcall` returns, it returns whatever the function call + returned. The debugger prompt appears as soon as the function is entered. + + +.. function:: set_trace() + + Enter the debugger at the calling stack frame. This is useful to hard-code a + breakpoint at a given point in a program, even if the code is not otherwise + being debugged (e.g. when an assertion fails). + + +.. function:: post_mortem(traceback) + + Enter post-mortem debugging of the given *traceback* object. + + +.. function:: pm() + + Enter post-mortem debugging of the traceback found in ``sys.last_traceback``. + + +.. _debugger-commands: + +Debugger Commands +================= + +The debugger recognizes the following commands. Most commands can be +abbreviated to one or two letters; e.g. ``h(elp)`` means that either ``h`` or +``help`` can be used to enter the help command (but not ``he`` or ``hel``, nor +``H`` or ``Help`` or ``HELP``). Arguments to commands must be separated by +whitespace (spaces or tabs). Optional arguments are enclosed in square brackets +(``[]``) in the command syntax; the square brackets must not be typed. +Alternatives in the command syntax are separated by a vertical bar (``|``). + +Entering a blank line repeats the last command entered. Exception: if the last +command was a ``list`` command, the next 11 lines are listed. + +Commands that the debugger doesn't recognize are assumed to be Python statements +and are executed in the context of the program being debugged. Python +statements can also be prefixed with an exclamation point (``!``). This is a +powerful way to inspect the program being debugged; it is even possible to +change a variable or call a function. When an exception occurs in such a +statement, the exception name is printed but the debugger's state is not +changed. + +Multiple commands may be entered on a single line, separated by ``;;``. (A +single ``;`` is not used as it is the separator for multiple commands in a line +that is passed to the Python parser.) No intelligence is applied to separating +the commands; the input is split at the first ``;;`` pair, even if it is in the +middle of a quoted string. + +The debugger supports aliases. Aliases can have parameters which allows one a +certain level of adaptability to the context under examination. + +.. index:: + pair: .pdbrc; file + triple: debugger; configuration; file + +If a file :file:`.pdbrc` exists in the user's home directory or in the current +directory, it is read in and executed as if it had been typed at the debugger +prompt. This is particularly useful for aliases. If both files exist, the one +in the home directory is read first and aliases defined there can be overridden +by the local file. + +h(elp) [*command*] + Without argument, print the list of available commands. With a *command* as + argument, print help about that command. ``help pdb`` displays the full + documentation file; if the environment variable :envvar:`PAGER` is defined, the + file is piped through that command instead. Since the *command* argument must + be an identifier, ``help exec`` must be entered to get help on the ``!`` + command. + +w(here) + Print a stack trace, with the most recent frame at the bottom. An arrow + indicates the current frame, which determines the context of most commands. + +d(own) + Move the current frame one level down in the stack trace (to a newer frame). + +u(p) + Move the current frame one level up in the stack trace (to an older frame). + +b(reak) [[*filename*:]*lineno*``|``*function*[, *condition*]] + With a *lineno* argument, set a break there in the current file. With a + *function* argument, set a break at the first executable statement within that + function. The line number may be prefixed with a filename and a colon, to + specify a breakpoint in another file (probably one that hasn't been loaded yet). + The file is searched on ``sys.path``. Note that each breakpoint is assigned a + number to which all the other breakpoint commands refer. + + If a second argument is present, it is an expression which must evaluate to true + before the breakpoint is honored. + + Without argument, list all breaks, including for each breakpoint, the number of + times that breakpoint has been hit, the current ignore count, and the associated + condition if any. + +tbreak [[*filename*:]*lineno*``|``*function*[, *condition*]] + Temporary breakpoint, which is removed automatically when it is first hit. The + arguments are the same as break. + +cl(ear) [*bpnumber* [*bpnumber ...*]] + With a space separated list of breakpoint numbers, clear those breakpoints. + Without argument, clear all breaks (but first ask confirmation). + +disable [*bpnumber* [*bpnumber ...*]] + Disables the breakpoints given as a space separated list of breakpoint numbers. + Disabling a breakpoint means it cannot cause the program to stop execution, but + unlike clearing a breakpoint, it remains in the list of breakpoints and can be + (re-)enabled. + +enable [*bpnumber* [*bpnumber ...*]] + Enables the breakpoints specified. + +ignore *bpnumber* [*count*] + Sets the ignore count for the given breakpoint number. If count is omitted, the + ignore count is set to 0. A breakpoint becomes active when the ignore count is + zero. When non-zero, the count is decremented each time the breakpoint is + reached and the breakpoint is not disabled and any associated condition + evaluates to true. + +condition *bpnumber* [*condition*] + Condition is an expression which must evaluate to true before the breakpoint is + honored. If condition is absent, any existing condition is removed; i.e., the + breakpoint is made unconditional. + +commands [*bpnumber*] + Specify a list of commands for breakpoint number *bpnumber*. The commands + themselves appear on the following lines. Type a line containing just 'end' to + terminate the commands. An example:: + + (Pdb) commands 1 + (com) print some_variable + (com) end + (Pdb) + + To remove all commands from a breakpoint, type commands and follow it + immediately with end; that is, give no commands. + + With no *bpnumber* argument, commands refers to the last breakpoint set. + + You can use breakpoint commands to start your program up again. Simply use the + continue command, or step, or any other command that resumes execution. + + Specifying any command resuming execution (currently continue, step, next, + return, jump, quit and their abbreviations) terminates the command list (as if + that command was immediately followed by end). This is because any time you + resume execution (even with a simple next or step), you may encounter· another + breakpoint--which could have its own command list, leading to ambiguities about + which list to execute. + + If you use the 'silent' command in the command list, the usual message about + stopping at a breakpoint is not printed. This may be desirable for breakpoints + that are to print a specific message and then continue. If none of the other + commands print anything, you see no sign that the breakpoint was reached. + + .. versionadded:: 2.5 + +s(tep) + Execute the current line, stop at the first possible occasion (either in a + function that is called or on the next line in the current function). + +n(ext) + Continue execution until the next line in the current function is reached or it + returns. (The difference between ``next`` and ``step`` is that ``step`` stops + inside a called function, while ``next`` executes called functions at (nearly) + full speed, only stopping at the next line in the current function.) + +r(eturn) + Continue execution until the current function returns. + +c(ont(inue)) + Continue execution, only stop when a breakpoint is encountered. + +j(ump) *lineno* + Set the next line that will be executed. Only available in the bottom-most + frame. This lets you jump back and execute code again, or jump forward to skip + code that you don't want to run. + + It should be noted that not all jumps are allowed --- for instance it is not + possible to jump into the middle of a :keyword:`for` loop or out of a + :keyword:`finally` clause. + +l(ist) [*first*[, *last*]] + List source code for the current file. Without arguments, list 11 lines around + the current line or continue the previous listing. With one argument, list 11 + lines around at that line. With two arguments, list the given range; if the + second argument is less than the first, it is interpreted as a count. + +a(rgs) + Print the argument list of the current function. + +p *expression* + Evaluate the *expression* in the current context and print its value. + + .. note:: + + ``print`` can also be used, but is not a debugger command --- this executes the + Python :keyword:`print` statement. + +pp *expression* + Like the ``p`` command, except the value of the expression is pretty-printed + using the :mod:`pprint` module. + +alias [*name* [command]] + Creates an alias called *name* that executes *command*. The command must *not* + be enclosed in quotes. Replaceable parameters can be indicated by ``%1``, + ``%2``, and so on, while ``%*`` is replaced by all the parameters. If no + command is given, the current alias for *name* is shown. If no arguments are + given, all aliases are listed. + + Aliases may be nested and can contain anything that can be legally typed at the + pdb prompt. Note that internal pdb commands *can* be overridden by aliases. + Such a command is then hidden until the alias is removed. Aliasing is + recursively applied to the first word of the command line; all other words in + the line are left alone. + + As an example, here are two useful aliases (especially when placed in the + :file:`.pdbrc` file):: + + #Print instance variables (usage "pi classInst") + alias pi for k in %1.__dict__.keys(): print "%1.",k,"=",%1.__dict__[k] + #Print instance variables in self + alias ps pi self + +unalias *name* + Deletes the specified alias. + +[!]*statement* + Execute the (one-line) *statement* in the context of the current stack frame. + The exclamation point can be omitted unless the first word of the statement + resembles a debugger command. To set a global variable, you can prefix the + assignment command with a ``global`` command on the same line, e.g.:: + + (Pdb) global list_options; list_options = ['-l'] + (Pdb) + +run [*args* ...] + Restart the debugged python program. If an argument is supplied, it is splitted + with "shlex" and the result is used as the new sys.argv. History, breakpoints, + actions and debugger options are preserved. "restart" is an alias for "run". + + .. versionadded:: 2.6 + +q(uit) + Quit from the debugger. The program being executed is aborted. + + +.. _debugger-hooks: + +How It Works +============ + +Some changes were made to the interpreter: + +* ``sys.settrace(func)`` sets the global trace function + +* there can also a local trace function (see later) + +Trace functions have three arguments: *frame*, *event*, and *arg*. *frame* is +the current stack frame. *event* is a string: ``'call'``, ``'line'``, +``'return'``, ``'exception'``, ``'c_call'``, ``'c_return'``, or +``'c_exception'``. *arg* depends on the event type. + +The global trace function is invoked (with *event* set to ``'call'``) whenever a +new local scope is entered; it should return a reference to the local trace +function to be used that scope, or ``None`` if the scope shouldn't be traced. + +The local trace function should return a reference to itself (or to another +function for further tracing in that scope), or ``None`` to turn off tracing in +that scope. + +Instance methods are accepted (and very useful!) as trace functions. + +The events have the following meaning: + +``'call'`` + A function is called (or some other code block entered). The global trace + function is called; *arg* is ``None``; the return value specifies the local + trace function. + +``'line'`` + The interpreter is about to execute a new line of code (sometimes multiple line + events on one line exist). The local trace function is called; *arg* is + ``None``; the return value specifies the new local trace function. + +``'return'`` + A function (or other code block) is about to return. The local trace function + is called; *arg* is the value that will be returned. The trace function's + return value is ignored. + +``'exception'`` + An exception has occurred. The local trace function is called; *arg* is a + triple ``(exception, value, traceback)``; the return value specifies the new + local trace function. + +``'c_call'`` + A C function is about to be called. This may be an extension function or a + builtin. *arg* is the C function object. + +``'c_return'`` + A C function has returned. *arg* is ``None``. + +``'c_exception'`` + A C function has thrown an exception. *arg* is ``None``. + +Note that as an exception is propagated down the chain of callers, an +``'exception'`` event is generated at each level. + +For more information on code and frame objects, refer to :ref:`types`. + |