diff options
Diffstat (limited to 'Lib/pdb.doc')
| -rw-r--r-- | Lib/pdb.doc | 157 |
1 files changed, 157 insertions, 0 deletions
diff --git a/Lib/pdb.doc b/Lib/pdb.doc new file mode 100644 index 0000000..7eb68d2 --- /dev/null +++ b/Lib/pdb.doc @@ -0,0 +1,157 @@ +The Python Debugger +=================== + +To use the debugger in its simplest form: + + >>> import pdb + >>> pdb.run('<a statement>') + +The debugger's prompt is '(Pdb) '. This will stop in the first +function call in <a statement>. + +The commands recognized by the debugger are listed in the next +section. Most can be abbreviated as indicated; e.g., h(elp) means +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.) + +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 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. + + +Debugger commands +================= + +h(elp) + 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. + +d(own) + 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) [lineno] + With a line number argument, set a break there in the current file. + Without argument, list all breaks. + +cl(ear) [lineno] + With a line number argument, clear that break in the current file. + Without argument, clear all breaks (but first ask confirmation). + +s(tep) + 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. + +r(eturn) + Continue execution until the current function returns. + +c(ont(inue)) + 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. + +a(rgs) + Print the argument list of the current function. + +p 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) + +q(uit) + Quit from the debugger. + The program being executed is aborted. + + +How it works +============ + +Some changes were made to the interpreter: +- if sys.trace is defined (by the user) and not None, it should be a function +- sys.trace is called 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 |