summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorGuido van Rossum <guido@python.org>1995-03-02 12:37:55 (GMT)
committerGuido van Rossum <guido@python.org>1995-03-02 12:37:55 (GMT)
commitf4aac48cc3b33b558c8ab6c501d8f7b21cd4f2e5 (patch)
treeef33f1fa06f722aeb2a3887c5109d2ac3e452ce1
parent0bf4d892ebbc2ba1b56c5710c36abfd4e9a3c73c (diff)
downloadcpython-f4aac48cc3b33b558c8ab6c501d8f7b21cd4f2e5.zip
cpython-f4aac48cc3b33b558c8ab6c501d8f7b21cd4f2e5.tar.gz
cpython-f4aac48cc3b33b558c8ab6c501d8f7b21cd4f2e5.tar.bz2
minor update
-rw-r--r--Doc/lib/libpdb.tex85
-rw-r--r--Doc/libpdb.tex85
2 files changed, 90 insertions, 80 deletions
diff --git a/Doc/lib/libpdb.tex b/Doc/lib/libpdb.tex
index e393118..ea03abf 100644
--- a/Doc/lib/libpdb.tex
+++ b/Doc/lib/libpdb.tex
@@ -1,23 +1,27 @@
-\section{Standard module \sectcode{pdb}}
+\chapter{The Python Debugger}
\stmodindex{pdb}
\index{debugging}
-This module defines an interactive source code debugger for Python
-programs. It supports breakpoints and single stepping at the source
-line level, inspection of stack frames, source code listing, and
-evaluation of arbitrary Python code in the context of any stack frame.
-It also supports post-mortem debugging and can be called under program
-control.
+\renewcommand{\indexsubitem}{(in module pdb)}
+
+The module \code{pdb} defines an interactive source code debugger for
+Python programs. It supports setting breakpoints and single stepping
+at the source line level, inspection of stack frames, source code
+listing, and evaluation of arbitrary Python code in the context of any
+stack frame. It also supports post-mortem debugging and can be called
+under program control.
The debugger is extensible --- it is actually defined as a class
\code{Pdb}. The extension interface uses the (also undocumented)
-modules \code{bdb} and \code{cmd}; it is currently undocumented.
+modules \code{bdb} and \code{cmd}; it is currently undocumented but
+easily understood by reading the source.
\ttindex{Pdb}
\ttindex{bdb}
\ttindex{cmd}
A primitive windowing version of the debugger also exists --- this is
-module \code{wdb}, which requires STDWIN.
+module \code{wdb}, which requires STDWIN (see the chapter on STDWIN
+specific modules).
\index{stdwin}
\ttindex{wdb}
@@ -47,34 +51,35 @@ The module defines the following functions; each enters the debugger
in a slightly different way:
\begin{funcdesc}{run}{statement\optional{\, globals\optional{\, locals}}}
-Execute the \var{statement} (which should be a string) under debugger
+Execute the \var{statement} (given as a string) under debugger
control. The debugger prompt appears before any code is executed; you
-can set breakpoint and type \code{continue}, or you can step through
-the statement using \code{step} or \code{next}. The optional
-\var{globals} and \var{locals} arguments specify the environment in
-which the code is executed; by default the dictionary of the module
-\code{__main__} is used. (See the explanation of the \code{exec}
-statement or the \code{eval()} built-in function.)
+can set breakpoints and type \code{continue}, or you can step through
+the statement using \code{step} or \code{next} (all these commands are
+explained below). The optional \var{globals} and \var{locals}
+arguments specify the environment in which the code is executed; by
+default the dictionary of the module \code{__main__} is used. (See
+the explanation of the \code{exec} statement or the \code{eval()}
+built-in function.)
\end{funcdesc}
\begin{funcdesc}{runeval}{expression\optional{\, globals\optional{\, locals}}}
-Evaluate the \var{expression} (which should be a string) under
-debugger control. When \code{runeval()} returns, it returns the value
-of the expression. Otherwise this function is similar to
+Evaluate the \var{expression} (given as a a string) under debugger
+control. When \code{runeval()} returns, it returns the value of the
+expression. Otherwise this function is similar to
\code{run()}.
\end{funcdesc}
\begin{funcdesc}{runcall}{function\optional{\, argument\, ...}}
-Call the \var{function} (which should be a callable Python object, not
-a string) with the given arguments. When \code{runcall()} returns, it
-returns the return value of the function call. The debugger prompt
-appears as soon as the function is entered.
+Call the \var{function} (a function or method object, not a string)
+with the given arguments. When \code{runcall()} returns, it returns
+whatever the function call returned. The debugger prompt appears as
+soon as the function is entered.
\end{funcdesc}
\begin{funcdesc}{set_trace}{}
Enter the debugger at the calling stack frame. This is useful to
-hard-code a breakpoint at a given point in code, even if the code is
-not otherwise being debugged.
+hard-code a breakpoint at a given point in a program, even if the code
+is not otherwise being debugged (e.g. when an assertion fails).
\end{funcdesc}
\begin{funcdesc}{post_mortem}{traceback}
@@ -82,7 +87,7 @@ Enter post-mortem debugging of the given \var{traceback} object.
\end{funcdesc}
\begin{funcdesc}{pm}{}
-Enter post-mortem debugging based on the traceback found in
+Enter post-mortem debugging of the traceback found in
\code{sys.last_traceback}.
\end{funcdesc}
@@ -118,9 +123,9 @@ Without argument, print the list of available commands.
With a \var{command} as argument, print help about that command.
``\code{help pdb}'' displays the full documentation file; if the
environment variable \code{PAGER} is defined, the file is piped
-through that command instead. Since the var{command} argument must be
-an identifier, ``\code{help exec}'' gives help on the ``\code{!}''
-command.
+through that command instead. Since the \var{command} argument must be
+an identifier, ``\code{help exec}'' must be entered to get help on the
+``\code{!}'' command.
\item[{w(here)}]
@@ -138,13 +143,13 @@ Move the current frame one level down in the stack trace
Move the current frame one level up in the stack trace
(to a newer frame).
-\item[{b(reak) [\var{lineno} \code{|} \var{function}]}]
+\item[{b(reak) [\var{lineno}\code{|}\var{function}]}]
With a \var{lineno} argument, set a break there in the current
file. With a \var{function} argument, set a break at the entry of
that function. Without argument, list all breaks.
-\item[{cl(ear) [lineno]}]
+\item[{cl(ear) [\var{lineno}]}]
With a \var{lineno} argument, clear that break in the current file.
Without argument, clear all breaks (but first ask confirmation).
@@ -160,8 +165,8 @@ current function).
Continue execution until the next line in the current function
is reached or it returns. (The difference between \code{next} and
\code{step} is that \code{step} stops inside a called function, while
-\code{next} executes called functions at full speed, only stopping at
-the next line in the current function.)
+\code{next} executes called functions at (nearly) full speed, only
+stopping at the next line in the current function.)
\item[{r(eturn)}]
@@ -173,12 +178,11 @@ Continue execution, only stop when a breakpoint is encountered.
\item[{l(ist) [\var{first} [, \var{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 around 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 around at that line. With two arguments,
+list the given range; if the second argument is less than the first,
+it is interpreted as a count.
\item[{a(rgs)}]
@@ -187,7 +191,8 @@ Print the argument list of the current function.
\item[{p \var{expression}}]
Evaluate the \var{expression} in the current context and print its
-value.
+value. (Note: \code{print} can also be used, but is not a debugger
+command --- this executes the Python \code{print} statement.)
\item[{[!] \var{statement}}]
diff --git a/Doc/libpdb.tex b/Doc/libpdb.tex
index e393118..ea03abf 100644
--- a/Doc/libpdb.tex
+++ b/Doc/libpdb.tex
@@ -1,23 +1,27 @@
-\section{Standard module \sectcode{pdb}}
+\chapter{The Python Debugger}
\stmodindex{pdb}
\index{debugging}
-This module defines an interactive source code debugger for Python
-programs. It supports breakpoints and single stepping at the source
-line level, inspection of stack frames, source code listing, and
-evaluation of arbitrary Python code in the context of any stack frame.
-It also supports post-mortem debugging and can be called under program
-control.
+\renewcommand{\indexsubitem}{(in module pdb)}
+
+The module \code{pdb} defines an interactive source code debugger for
+Python programs. It supports setting breakpoints and single stepping
+at the source line level, inspection of stack frames, source code
+listing, and evaluation of arbitrary Python code in the context of any
+stack frame. It also supports post-mortem debugging and can be called
+under program control.
The debugger is extensible --- it is actually defined as a class
\code{Pdb}. The extension interface uses the (also undocumented)
-modules \code{bdb} and \code{cmd}; it is currently undocumented.
+modules \code{bdb} and \code{cmd}; it is currently undocumented but
+easily understood by reading the source.
\ttindex{Pdb}
\ttindex{bdb}
\ttindex{cmd}
A primitive windowing version of the debugger also exists --- this is
-module \code{wdb}, which requires STDWIN.
+module \code{wdb}, which requires STDWIN (see the chapter on STDWIN
+specific modules).
\index{stdwin}
\ttindex{wdb}
@@ -47,34 +51,35 @@ The module defines the following functions; each enters the debugger
in a slightly different way:
\begin{funcdesc}{run}{statement\optional{\, globals\optional{\, locals}}}
-Execute the \var{statement} (which should be a string) under debugger
+Execute the \var{statement} (given as a string) under debugger
control. The debugger prompt appears before any code is executed; you
-can set breakpoint and type \code{continue}, or you can step through
-the statement using \code{step} or \code{next}. The optional
-\var{globals} and \var{locals} arguments specify the environment in
-which the code is executed; by default the dictionary of the module
-\code{__main__} is used. (See the explanation of the \code{exec}
-statement or the \code{eval()} built-in function.)
+can set breakpoints and type \code{continue}, or you can step through
+the statement using \code{step} or \code{next} (all these commands are
+explained below). The optional \var{globals} and \var{locals}
+arguments specify the environment in which the code is executed; by
+default the dictionary of the module \code{__main__} is used. (See
+the explanation of the \code{exec} statement or the \code{eval()}
+built-in function.)
\end{funcdesc}
\begin{funcdesc}{runeval}{expression\optional{\, globals\optional{\, locals}}}
-Evaluate the \var{expression} (which should be a string) under
-debugger control. When \code{runeval()} returns, it returns the value
-of the expression. Otherwise this function is similar to
+Evaluate the \var{expression} (given as a a string) under debugger
+control. When \code{runeval()} returns, it returns the value of the
+expression. Otherwise this function is similar to
\code{run()}.
\end{funcdesc}
\begin{funcdesc}{runcall}{function\optional{\, argument\, ...}}
-Call the \var{function} (which should be a callable Python object, not
-a string) with the given arguments. When \code{runcall()} returns, it
-returns the return value of the function call. The debugger prompt
-appears as soon as the function is entered.
+Call the \var{function} (a function or method object, not a string)
+with the given arguments. When \code{runcall()} returns, it returns
+whatever the function call returned. The debugger prompt appears as
+soon as the function is entered.
\end{funcdesc}
\begin{funcdesc}{set_trace}{}
Enter the debugger at the calling stack frame. This is useful to
-hard-code a breakpoint at a given point in code, even if the code is
-not otherwise being debugged.
+hard-code a breakpoint at a given point in a program, even if the code
+is not otherwise being debugged (e.g. when an assertion fails).
\end{funcdesc}
\begin{funcdesc}{post_mortem}{traceback}
@@ -82,7 +87,7 @@ Enter post-mortem debugging of the given \var{traceback} object.
\end{funcdesc}
\begin{funcdesc}{pm}{}
-Enter post-mortem debugging based on the traceback found in
+Enter post-mortem debugging of the traceback found in
\code{sys.last_traceback}.
\end{funcdesc}
@@ -118,9 +123,9 @@ Without argument, print the list of available commands.
With a \var{command} as argument, print help about that command.
``\code{help pdb}'' displays the full documentation file; if the
environment variable \code{PAGER} is defined, the file is piped
-through that command instead. Since the var{command} argument must be
-an identifier, ``\code{help exec}'' gives help on the ``\code{!}''
-command.
+through that command instead. Since the \var{command} argument must be
+an identifier, ``\code{help exec}'' must be entered to get help on the
+``\code{!}'' command.
\item[{w(here)}]
@@ -138,13 +143,13 @@ Move the current frame one level down in the stack trace
Move the current frame one level up in the stack trace
(to a newer frame).
-\item[{b(reak) [\var{lineno} \code{|} \var{function}]}]
+\item[{b(reak) [\var{lineno}\code{|}\var{function}]}]
With a \var{lineno} argument, set a break there in the current
file. With a \var{function} argument, set a break at the entry of
that function. Without argument, list all breaks.
-\item[{cl(ear) [lineno]}]
+\item[{cl(ear) [\var{lineno}]}]
With a \var{lineno} argument, clear that break in the current file.
Without argument, clear all breaks (but first ask confirmation).
@@ -160,8 +165,8 @@ current function).
Continue execution until the next line in the current function
is reached or it returns. (The difference between \code{next} and
\code{step} is that \code{step} stops inside a called function, while
-\code{next} executes called functions at full speed, only stopping at
-the next line in the current function.)
+\code{next} executes called functions at (nearly) full speed, only
+stopping at the next line in the current function.)
\item[{r(eturn)}]
@@ -173,12 +178,11 @@ Continue execution, only stop when a breakpoint is encountered.
\item[{l(ist) [\var{first} [, \var{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 around 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 around at that line. With two arguments,
+list the given range; if the second argument is less than the first,
+it is interpreted as a count.
\item[{a(rgs)}]
@@ -187,7 +191,8 @@ Print the argument list of the current function.
\item[{p \var{expression}}]
Evaluate the \var{expression} in the current context and print its
-value.
+value. (Note: \code{print} can also be used, but is not a debugger
+command --- this executes the Python \code{print} statement.)
\item[{[!] \var{statement}}]