diff options
| -rw-r--r-- | Lib/pdb.doc | 252 |
1 files changed, 185 insertions, 67 deletions
diff --git a/Lib/pdb.doc b/Lib/pdb.doc index 6ae54e7..e8f0725 100644 --- a/Lib/pdb.doc +++ b/Lib/pdb.doc @@ -1,10 +1,10 @@ -The Python Debugger -=================== +The Python Debugger Pdb +======================= To use the debugger in its simplest form: - >>> import pdb - >>> pdb.run('<a statement>') + >>> import pdb + >>> pdb.run('<a statement>') The debugger's prompt is '(Pdb) '. This will stop in the first function call in <a statement>. @@ -13,10 +13,10 @@ Alternatively, if a statement terminated with an unhandled exception, you can use pdb's post-mortem facility to inspect the contents of the traceback: - >>> <a statement> - <exception traceback> - >>> import pdb - >>> pdb.pm() + >>> <a statement> + <exception traceback> + >>> import pdb + >>> pdb.pm() The commands recognized by the debugger are listed in the next section. Most can be abbreviated as indicated; e.g., h(elp) means @@ -24,8 +24,8 @@ that 'help' can be typed as 'h' or 'help' (but not as 'he' or 'hel', nor as 'H' or 'Help' or 'HELP'). Optional arguments are enclosed in square brackets. -A blank line repeats the previous command literally. (Except for -'list', where it lists the next 11 lines.) +A blank line repeats the previous command literally, except for +'list', where it lists the next 11 lines. Commands that the debugger doesn't recognize are assumed to be Python statements and are executed in the context of the program being @@ -35,90 +35,208 @@ debugged; it is even possible to change variables. When an exception occurs in such a statement, the exception name is printed but the debugger's state is not changed. -The debugger is not directly programmable; but it is implemented as a -class from which you can derive your own debugger class, so you can -make as fancy as you like. +The debugger supports aliases, which can save typing. And aliases +can have parameters (see the alias help entry) which allows one a +certain level of adaptability to the context under examination. + +Multiple commands may be entered on a single line, separated by +semi-colons. No intelligence is applied to separating the commands; +the input is split at the first ';', even if it is in the middle of +a quoted string. + +If a file ".pdbrc" exists in your 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 overriden by the local file. + +Aside from aliases, the debugger is not directly programmable; but +it is implemented as a class from which you can derive your own +debugger class, which you can make as fancy as you like. Debugger commands ================= h(elp) - Without argument, print the list of available commands. - With a command name as argument, print help about that command - "help pdb" pipes the full documentation file to the $PAGER - "help exec" gives help on the ! command + Without argument, print the list of available commands. + With a command name as argument, print help about that command + (this is currently not implemented). 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. + 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 an older frame). + Move the current frame one level down in the stack trace + (to an older frame). u(p) - Move the current frame one level up in the stack trace - (to a newer frame). - -b(reak) ([file:]lineno | function) [, "condition"] - With a line number argument, set a break there in the current - file. With a function name, set a break at the entry of that - function. Without argument, list all breaks. If a second - argument is present, it is a string specifying an expression - which must evaluate to true before the breakpoint is honored. - - 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. - -cl(ear) [lineno] - With a line number argument, clear that break in the current file. - Without argument, clear all breaks (but first ask confirmation). - - 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. + Move the current frame one level up in the stack trace + (to a newer frame). + +b(reak) [ ([filename:]lineno | function) [, "condition"] ] + With a filename:line number argument, set a break there. If + filename is omitted, use the current file. With a function name, + set a break at the first executable line of that function. + Without argument, list all breaks. Each breakpoint is assigned + a number which is by all the other breakpoint commands refer to it. + + The condition argument, if present, is a string which must + evaluate to true in order for the breakpoint to be honored. + +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 str_condition + str_condition is a string specifying an expression which + must evaluate to true before the breakpoint is honored. + If str_condition is absent, any existing condition is removed; + i.e., the breakpoint is made unconditional. s(tep) - Execute the current line, stop at the first possible occasion - (either in a function that is called or in the current function). + Execute the current line, stop at the first possible occasion + (either in a function that is called or in the current function). n(ext) - Continue execution until the next line in the current function - is reached or it returns. + Continue execution until the next line in the current function + is reached or it returns. r(eturn) - Continue execution until the current function returns. + Continue execution until the current function returns. c(ont(inue)) - Continue execution, only stop when a breakpoint is encountered. + Continue execution, only stop when a breakpoint is encountered. 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 starting at that line. - With two arguments, list the given range; - if the second argument is less than the first, it is a count. + 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 starting at that line. + With two arguments, list the given range; + if the second argument is less than the first, it is a count. a(rgs) - Print the argument list of the current function. + Print the argument list of the current function. p expression - Print the value of the expression. + Print the value of the expression. (!) 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 assign to a global variable you must always prefix the - command with a 'global' command, e.g.: - (Pdb) global list_options; list_options = ['-l'] - (Pdb) + 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 assign to a global variable you must always prefix the + command with a 'global' command, e.g.: + (Pdb) global list_options; list_options = ['-l'] + (Pdb) + + +whatis arg + Prints the type of the argument. + +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 name is given, all aliases are listed. + + Aliases may be nested and can contain anything that can be + legally typed at the pdb prompt. Note! You *can* override + internal pdb commands with aliases! Those internal commands + are 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 .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. q(uit) - Quit from the debugger. - The program being executed is aborted. + Quit from the debugger. + The program being executed is aborted. + + +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, arg) + - frame is the current stack frame + - event is a string: 'call', 'line', 'return' or 'exception' + - arg is dependent on the event type +A trace function should return a new trace function or None. +Class methods are accepted (and most useful!) as trace methods. + +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 the argument list to the function; + 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 in 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 + +Note that as an exception is propagated down the chain of callers, an +'exception' event is generated at each level. + +Stack frame objects have the following read-only attributes: + f_code: the code object being executed + f_lineno: the current line number (-1 for 'call' events) + f_back: the stack frame of the caller, or None + f_locals: dictionary containing local name bindings + f_globals: dictionary containing global name bindings + +Code objects have the following read-only attributes: + co_code: the code string + co_names: the list of names used by the code + co_consts: the list of (literal) constants used by the code + co_filename: the filename from which the code was compiled |