Richard Wolff's changes:
pdb.doc Updated to reflect better the various changes.
This commit is contained in:
Guido van Rossum
parent
2424f855f3
commit
f0a275d4db
174
Lib/pdb.doc
174
Lib/pdb.doc
|
|
@ -1,5 +1,5 @@
|
|||
The Python Debugger
|
||||
===================
|
||||
The Python Debugger Pdb
|
||||
=======================
|
||||
|
||||
To use the debugger in its simplest form:
|
||||
|
||||
|
|
@ -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,9 +35,24 @@ 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
|
||||
|
|
@ -46,8 +61,7 @@ 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
|
||||
(this is currently not implemented).
|
||||
|
||||
w(here)
|
||||
Print a stack trace, with the most recent frame at the bottom.
|
||||
|
|
@ -62,24 +76,47 @@ 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.
|
||||
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
|
||||
|
|
@ -110,15 +147,96 @@ 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.
|
||||
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.
|
||||
|
||||
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue