Richard Wolff's changes:
pdb.doc Updated to reflect better the various changes.
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 @@
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 @@
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 @@
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).
+ 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.
+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 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.
+ The condition argument, if present, is a string which must
+ evaluate to true in order for the breakpoint to be honored.
-cl(ear) [lineno]
- With a line number argument, clear that break in the current file.
- Without argument, clear all breaks (but first ask confirmation).
+tbreak [ ([filename:]lineno | function) [, "condition"] ]
+ Temporary breakpoint, which is removed automatically when it is
+ first hit. The arguments are the same as break.
- 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) [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