summaryrefslogtreecommitdiff
path: root/Lib/pdb.doc
diff options
context:
space:
mode:
authorGuido van Rossum <guido@python.org>1998-09-17 15:01:38 +0000
committerGuido van Rossum <guido@python.org>1998-09-17 15:01:38 +0000
commitfc076d4ce2b95c34f26935e287b84cfa69baf265 (patch)
tree48a4aa31a0ebddd767918e01525d6db1e79783e5 /Lib/pdb.doc
parent3a98e78a6e8d89d03a6b6291054cc0f2154b50d0 (diff)
downloadcpython-git-fc076d4ce2b95c34f26935e287b84cfa69baf265.tar.gz
Untabified and applied Richard Wolff's changes (plus my own reflowing
of some paragraphs).
Diffstat (limited to 'Lib/pdb.doc')
-rw-r--r--Lib/pdb.doc270
1 files changed, 110 insertions, 160 deletions
diff --git a/Lib/pdb.doc b/Lib/pdb.doc
index e8f0725b7a..3beb0c2b7e 100644
--- a/Lib/pdb.doc
+++ b/Lib/pdb.doc
@@ -3,8 +3,8 @@ 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
@@ -35,208 +35,158 @@ 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 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.
+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.
+Multiple commands may be entered on a single line, separated by the
+pair ';;'. 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.
+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.
+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
- (this is currently not implemented).
+ 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) [ ([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.
+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 to which all the other breakpoint
+ commands refer.
- The condition argument, if present, is a string which must
- evaluate to true in order for the breakpoint to be honored.
+ 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.
+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).
+ 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.
+ 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.
+ 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.
+ 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.
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.
+ 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
-
+ 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.
+ 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
+ Quit from the debugger.
+ The program being executed is aborted.