cpython-lru_cache-weakref: Doc/lib/libpdb.tex annotate

annotate Doc/lib/libpdb.tex @ 21467:4e35fa5d5708 legacy-trunk

Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.

author	Fred Drake <fdrake@acm.org>
date	Tue, 18 Dec 2001 16:31:08 +0000
parents	0491ea611bc4
children	0dbd6b73abd2

rev	line source
18693 4381461cce5d Add some symbolic names to support hyperlinked references. Fred Drake <fdrake@acm.org> parents: 16590 diff changeset	1 \chapter{The Python Debugger \label{debugger}}
8716 760dcf197048 Adjusted to use the new module synopsis support macros. Fred Drake <fdrake@acm.org> parents: 8693 diff changeset	2
10690 a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	3 \declaremodule{standard}{pdb}
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	4 \modulesynopsis{The Python debugger for interactive interpreters.}
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	5
2464 e726f90d2a9f minor update Guido van Rossum <guido@python.org> parents: 2462 diff changeset	6
10690 a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	7 The module \module{pdb} defines an interactive source code
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	8 debugger\index{debugging} for Python programs. It supports setting
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	9 (conditional) breakpoints and single stepping at the source line
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	10 level, inspection of stack frames, source code listing, and evaluation
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	11 of arbitrary Python code in the context of any stack frame. It also
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	12 supports post-mortem debugging and can be called under program
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	13 control.
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	14
10690 a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	15 The debugger is extensible --- it is actually defined as the class
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	16 \class{Pdb}\withsubitem{(class in pdb)}{\ttindex{Pdb}}.
7896 29ab3f602d00 Fixed some index entries. Fred Drake <fdrake@acm.org> parents: 7863 diff changeset	17 This is currently undocumented but easily understood by reading the
10690 a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	18 source. The extension interface uses the modules
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	19 \module{bdb}\refstmodindex{bdb} (undocumented) and
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	20 \refmodule{cmd}\refstmodindex{cmd}.
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	21
7896 29ab3f602d00 Fixed some index entries. Fred Drake <fdrake@acm.org> parents: 7863 diff changeset	22 The debugger's prompt is \samp{(Pdb) }.
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	23 Typical usage to run a program under control of the debugger is:
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	24
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7061 diff changeset	25 \begin{verbatim}
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	26 >>> import pdb
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	27 >>> import mymodule
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	28 >>> pdb.run('mymodule.test()')
2629 175671cc21d8 more complete examples Guido van Rossum <guido@python.org> parents: 2576 diff changeset	29 > <string>(0)?()
175671cc21d8 more complete examples Guido van Rossum <guido@python.org> parents: 2576 diff changeset	30 (Pdb) continue
175671cc21d8 more complete examples Guido van Rossum <guido@python.org> parents: 2576 diff changeset	31 > <string>(1)?()
175671cc21d8 more complete examples Guido van Rossum <guido@python.org> parents: 2576 diff changeset	32 (Pdb) continue
175671cc21d8 more complete examples Guido van Rossum <guido@python.org> parents: 2576 diff changeset	33 NameError: 'spam'
175671cc21d8 more complete examples Guido van Rossum <guido@python.org> parents: 2576 diff changeset	34 > <string>(1)?()
175671cc21d8 more complete examples Guido van Rossum <guido@python.org> parents: 2576 diff changeset	35 (Pdb)
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7061 diff changeset	36 \end{verbatim}
7896 29ab3f602d00 Fixed some index entries. Fred Drake <fdrake@acm.org> parents: 7863 diff changeset	37
29ab3f602d00 Fixed some index entries. Fred Drake <fdrake@acm.org> parents: 7863 diff changeset	38 \file{pdb.py} can also be invoked as
5679 d5911ca8d4eb Mention use of pdb.py to run a script (AMK). Guido van Rossum <guido@python.org> parents: 2629 diff changeset	39 a script to debug other scripts. For example:
7896 29ab3f602d00 Fixed some index entries. Fred Drake <fdrake@acm.org> parents: 7863 diff changeset	40
29ab3f602d00 Fixed some index entries. Fred Drake <fdrake@acm.org> parents: 7863 diff changeset	41 \begin{verbatim}
29ab3f602d00 Fixed some index entries. Fred Drake <fdrake@acm.org> parents: 7863 diff changeset	42 python /usr/local/lib/python1.5/pdb.py myscript.py
29ab3f602d00 Fixed some index entries. Fred Drake <fdrake@acm.org> parents: 7863 diff changeset	43 \end{verbatim}
5679 d5911ca8d4eb Mention use of pdb.py to run a script (AMK). Guido van Rossum <guido@python.org> parents: 2629 diff changeset	44
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	45 Typical usage to inspect a crashed program is:
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	46
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7061 diff changeset	47 \begin{verbatim}
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	48 >>> import pdb
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	49 >>> import mymodule
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	50 >>> mymodule.test()
16590 f813e987e65c Reflect change in traceback format: Fred Drake <fdrake@acm.org> parents: 14559 diff changeset	51 Traceback (most recent call last):
2629 175671cc21d8 more complete examples Guido van Rossum <guido@python.org> parents: 2576 diff changeset	52 File "<stdin>", line 1, in ?
175671cc21d8 more complete examples Guido van Rossum <guido@python.org> parents: 2576 diff changeset	53 File "./mymodule.py", line 4, in test
175671cc21d8 more complete examples Guido van Rossum <guido@python.org> parents: 2576 diff changeset	54 test2()
175671cc21d8 more complete examples Guido van Rossum <guido@python.org> parents: 2576 diff changeset	55 File "./mymodule.py", line 3, in test2
175671cc21d8 more complete examples Guido van Rossum <guido@python.org> parents: 2576 diff changeset	56 print spam
175671cc21d8 more complete examples Guido van Rossum <guido@python.org> parents: 2576 diff changeset	57 NameError: spam
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	58 >>> pdb.pm()
2629 175671cc21d8 more complete examples Guido van Rossum <guido@python.org> parents: 2576 diff changeset	59 > ./mymodule.py(3)test2()
175671cc21d8 more complete examples Guido van Rossum <guido@python.org> parents: 2576 diff changeset	60 -> print spam
175671cc21d8 more complete examples Guido van Rossum <guido@python.org> parents: 2576 diff changeset	61 (Pdb)
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7061 diff changeset	62 \end{verbatim}
7896 29ab3f602d00 Fixed some index entries. Fred Drake <fdrake@acm.org> parents: 7863 diff changeset	63
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	64 The module defines the following functions; each enters the debugger
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	65 in a slightly different way:
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	66
7712 0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain, Fred Drake <fdrake@acm.org> parents: 7647 diff changeset	67 \begin{funcdesc}{run}{statement\optional{, globals\optional{, locals}}}
2464 e726f90d2a9f minor update Guido van Rossum <guido@python.org> parents: 2462 diff changeset	68 Execute the \var{statement} (given as a string) under debugger
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	69 control. The debugger prompt appears before any code is executed; you
10690 a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	70 can set breakpoints and type \samp{continue}, or you can step through
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	71 the statement using \samp{step} or \samp{next} (all these commands are
2464 e726f90d2a9f minor update Guido van Rossum <guido@python.org> parents: 2462 diff changeset	72 explained below). The optional \var{globals} and \var{locals}
e726f90d2a9f minor update Guido van Rossum <guido@python.org> parents: 2462 diff changeset	73 arguments specify the environment in which the code is executed; by
14559 28caaa3e292f Remove reference to the stdwin-based windowed debugger, since stdwin Fred Drake <fdrake@acm.org> parents: 13625 diff changeset	74 default the dictionary of the module \refmodule[main]{__main__} is
28caaa3e292f Remove reference to the stdwin-based windowed debugger, since stdwin Fred Drake <fdrake@acm.org> parents: 13625 diff changeset	75 used. (See the explanation of the \keyword{exec} statement or the
10690 a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	76 \function{eval()} built-in function.)
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	77 \end{funcdesc}
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	78
7712 0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain, Fred Drake <fdrake@acm.org> parents: 7647 diff changeset	79 \begin{funcdesc}{runeval}{expression\optional{, globals\optional{, locals}}}
2464 e726f90d2a9f minor update Guido van Rossum <guido@python.org> parents: 2462 diff changeset	80 Evaluate the \var{expression} (given as a a string) under debugger
10690 a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	81 control. When \function{runeval()} returns, it returns the value of the
2464 e726f90d2a9f minor update Guido van Rossum <guido@python.org> parents: 2462 diff changeset	82 expression. Otherwise this function is similar to
10690 a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	83 \function{run()}.
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	84 \end{funcdesc}
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	85
7712 0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain, Fred Drake <fdrake@acm.org> parents: 7647 diff changeset	86 \begin{funcdesc}{runcall}{function\optional{, argument, ...}}
2464 e726f90d2a9f minor update Guido van Rossum <guido@python.org> parents: 2462 diff changeset	87 Call the \var{function} (a function or method object, not a string)
10690 a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	88 with the given arguments. When \function{runcall()} returns, it returns
2464 e726f90d2a9f minor update Guido van Rossum <guido@python.org> parents: 2462 diff changeset	89 whatever the function call returned. The debugger prompt appears as
e726f90d2a9f minor update Guido van Rossum <guido@python.org> parents: 2462 diff changeset	90 soon as the function is entered.
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	91 \end{funcdesc}
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	92
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	93 \begin{funcdesc}{set_trace}{}
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	94 Enter the debugger at the calling stack frame. This is useful to
2464 e726f90d2a9f minor update Guido van Rossum <guido@python.org> parents: 2462 diff changeset	95 hard-code a breakpoint at a given point in a program, even if the code
e726f90d2a9f minor update Guido van Rossum <guido@python.org> parents: 2462 diff changeset	96 is not otherwise being debugged (e.g. when an assertion fails).
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	97 \end{funcdesc}
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	98
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	99 \begin{funcdesc}{post_mortem}{traceback}
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	100 Enter post-mortem debugging of the given \var{traceback} object.
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	101 \end{funcdesc}
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	102
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	103 \begin{funcdesc}{pm}{}
2464 e726f90d2a9f minor update Guido van Rossum <guido@python.org> parents: 2462 diff changeset	104 Enter post-mortem debugging of the traceback found in
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	105 \code{sys.last_traceback}.
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	106 \end{funcdesc}
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	107
10690 a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	108
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	109 \section{Debugger Commands \label{debugger-commands}}
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	110
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	111 The debugger recognizes the following commands. Most commands can be
10690 a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	112 abbreviated to one or two letters; e.g. \samp{h(elp)} means that
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	113 either \samp{h} or \samp{help} can be used to enter the help
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	114 command (but not \samp{he} or \samp{hel}, nor \samp{H} or
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	115 \samp{Help} or \samp{HELP}). Arguments to commands must be
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	116 separated by whitespace (spaces or tabs). Optional arguments are
10690 a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	117 enclosed in square brackets (\samp{[]}) in the command syntax; the
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	118 square brackets must not be typed. Alternatives in the command syntax
10690 a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	119 are separated by a vertical bar (\samp{\|}).
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	120
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	121 Entering a blank line repeats the last command entered. Exception: if
10690 a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	122 the last command was a \samp{list} command, the next 11 lines are
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	123 listed.
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	124
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	125 Commands that the debugger doesn't recognize are assumed to be Python
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	126 statements and are executed in the context of the program being
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	127 debugged. Python statements can also be prefixed with an exclamation
10690 a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	128 point (\samp{!}). This is a powerful way to inspect the program
2629 175671cc21d8 more complete examples Guido van Rossum <guido@python.org> parents: 2576 diff changeset	129 being debugged; it is even possible to change a variable or call a
175671cc21d8 more complete examples Guido van Rossum <guido@python.org> parents: 2576 diff changeset	130 function. When an
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	131 exception occurs in such a statement, the exception name is printed
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	132 but the debugger's state is not changed.
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	133
9120 55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	134 Multiple commands may be entered on a single line, separated by
10690 a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	135 \samp{;;}. (A single \samp{;} is not used as it is
9120 55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	136 the separator for multiple commands in a line that is passed to
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	137 the Python parser.)
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	138 No intelligence is applied to separating the commands;
10690 a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	139 the input is split at the first \samp{;;} pair, even if it is in
9120 55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	140 the middle of a quoted string.
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	141
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	142 The debugger supports aliases. Aliases can have parameters which
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	143 allows one a certain level of adaptability to the context under
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	144 examination.
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	145
10690 a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	146 If a file \file{.pdbrc}
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	147 \indexii{.pdbrc}{file}\indexiii{debugger}{configuration}{file}
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	148 exists in the user's home directory or in the current directory, it is
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	149 read in and executed as if it had been typed at the debugger prompt.
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	150 This is particularly useful for aliases. If both files exist, the one
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	151 in the home directory is read first and aliases defined there can be
13625 fdfd1049f36e Rob W. W. Hooft's spelling fixes for the Library Reference. I hope Thomas Wouters <thomas@python.org> parents: 12244 diff changeset	152 overridden by the local file.
9120 55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	153
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	154 \begin{description}
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	155
7061 1d0b9028523c Modify command descriptions to use \optional{} instead of ad-hoc markup. Fred Drake <fdrake@acm.org> parents: 6530 diff changeset	156 \item[h(elp) \optional{\var{command}}]
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	157
7061 1d0b9028523c Modify command descriptions to use \optional{} instead of ad-hoc markup. Fred Drake <fdrake@acm.org> parents: 6530 diff changeset	158 Without argument, print the list of available commands. With a
1d0b9028523c Modify command descriptions to use \optional{} instead of ad-hoc markup. Fred Drake <fdrake@acm.org> parents: 6530 diff changeset	159 \var{command} as argument, print help about that command. \samp{help
1d0b9028523c Modify command descriptions to use \optional{} instead of ad-hoc markup. Fred Drake <fdrake@acm.org> parents: 6530 diff changeset	160 pdb} displays the full documentation file; if the environment variable
10690 a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	161 \envvar{PAGER} is defined, the file is piped through that command
7061 1d0b9028523c Modify command descriptions to use \optional{} instead of ad-hoc markup. Fred Drake <fdrake@acm.org> parents: 6530 diff changeset	162 instead. Since the \var{command} argument must be an identifier,
1d0b9028523c Modify command descriptions to use \optional{} instead of ad-hoc markup. Fred Drake <fdrake@acm.org> parents: 6530 diff changeset	163 \samp{help exec} must be entered to get help on the \samp{!} command.
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	164
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	165 \item[w(here)]
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	166
7061 1d0b9028523c Modify command descriptions to use \optional{} instead of ad-hoc markup. Fred Drake <fdrake@acm.org> parents: 6530 diff changeset	167 Print a stack trace, with the most recent frame at the bottom. An
1d0b9028523c Modify command descriptions to use \optional{} instead of ad-hoc markup. Fred Drake <fdrake@acm.org> parents: 6530 diff changeset	168 arrow indicates the current frame, which determines the context of
1d0b9028523c Modify command descriptions to use \optional{} instead of ad-hoc markup. Fred Drake <fdrake@acm.org> parents: 6530 diff changeset	169 most commands.
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	170
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	171 \item[d(own)]
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	172
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	173 Move the current frame one level down in the stack trace
12244 3dac854e6118 Noted by Guido: Fred Drake <fdrake@acm.org> parents: 11458 diff changeset	174 (to an newer frame).
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	175
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	176 \item[u(p)]
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	177
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	178 Move the current frame one level up in the stack trace
12244 3dac854e6118 Noted by Guido: Fred Drake <fdrake@acm.org> parents: 11458 diff changeset	179 (to a older frame).
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	180
10594 29abb7d96c25 Work around problems with HTML conversion by making the break and Fred Drake <fdrake@acm.org> parents: 9566 diff changeset	181 \item[b(reak) \optional{\optional{\var{filename}:}\var{lineno}\code{\Large{\|}}\var{function}\optional{, \var{condition}}}]
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	182
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	183 With a \var{lineno} argument, set a break there in the current
9120 55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	184 file. With a \var{function} argument, set a break at the first
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	185 executable statement within that function.
8693 8aa9d126e473 Add new syntax for specifying filenames on break and clear commands. Guido van Rossum <guido@python.org> parents: 7896 diff changeset	186 The line number may be prefixed with a filename and a colon,
8aa9d126e473 Add new syntax for specifying filenames on break and clear commands. Guido van Rossum <guido@python.org> parents: 7896 diff changeset	187 to specify a breakpoint in another file (probably one that
8aa9d126e473 Add new syntax for specifying filenames on break and clear commands. Guido van Rossum <guido@python.org> parents: 7896 diff changeset	188 hasn't been loaded yet). The file is searched on \code{sys.path}.
9120 55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	189 Note that each breakpoint is assigned a number to which all the other
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	190 breakpoint commands refer.
8693 8aa9d126e473 Add new syntax for specifying filenames on break and clear commands. Guido van Rossum <guido@python.org> parents: 7896 diff changeset	191
9120 55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	192 If a second argument is present, it is an expression which must
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	193 evaluate to true before the breakpoint is honored.
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	194
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	195 Without argument, list all breaks, including for each breakpoint,
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	196 the number of times that breakpoint has been hit, the current
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	197 ignore count, and the associated condition if any.
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	198
10594 29abb7d96c25 Work around problems with HTML conversion by making the break and Fred Drake <fdrake@acm.org> parents: 9566 diff changeset	199 \item[tbreak \optional{\optional{\var{filename}:}\var{lineno}\code{\Large{\|}}\var{function}\optional{, \var{condition}}}]
9120 55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	200
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	201 Temporary breakpoint, which is removed automatically when it is
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	202 first hit. The arguments are the same as break.
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	203
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	204 \item[cl(ear) \optional{\var{bpnumber} \optional{\var{bpnumber ...}}}]
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	205
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	206 With a space separated list of breakpoint numbers, clear those
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	207 breakpoints. Without argument, clear all breaks (but first
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	208 ask confirmation).
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	209
9120 55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	210 \item[disable \optional{\var{bpnumber} \optional{\var{bpnumber ...}}}]
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	211
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	212 Disables the breakpoints given as a space separated list of
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	213 breakpoint numbers. Disabling a breakpoint means it cannot cause
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	214 the program to stop execution, but unlike clearing a breakpoint, it
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	215 remains in the list of breakpoints and can be (re-)enabled.
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	216
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	217 \item[enable \optional{\var{bpnumber} \optional{\var{bpnumber ...}}}]
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	218
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	219 Enables the breakpoints specified.
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	220
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	221 \item[ignore \var{bpnumber} \optional{\var{count}}]
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	222
9120 55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	223 Sets the ignore count for the given breakpoint number. If
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	224 count is omitted, the ignore count is set to 0. A breakpoint
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	225 becomes active when the ignore count is zero. When non-zero,
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	226 the count is decremented each time the breakpoint is reached
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	227 and the breakpoint is not disabled and any associated condition
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	228 evaluates to true.
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	229
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	230 \item[condition \var{bpnumber} \optional{\var{condition}}]
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	231
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	232 Condition is an expression which must evaluate to true before
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	233 the breakpoint is honored. If condition is absent, any existing
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	234 condition is removed; i.e., the breakpoint is made unconditional.
8693 8aa9d126e473 Add new syntax for specifying filenames on break and clear commands. Guido van Rossum <guido@python.org> parents: 7896 diff changeset	235
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	236 \item[s(tep)]
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	237
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	238 Execute the current line, stop at the first possible occasion
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	239 (either in a function that is called or on the next line in the
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	240 current function).
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	241
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	242 \item[n(ext)]
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	243
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	244 Continue execution until the next line in the current function
10690 a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	245 is reached or it returns. (The difference between \samp{next} and
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	246 \samp{step} is that \samp{step} stops inside a called function, while
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	247 \samp{next} executes called functions at (nearly) full speed, only
2464 e726f90d2a9f minor update Guido van Rossum <guido@python.org> parents: 2462 diff changeset	248 stopping at the next line in the current function.)
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	249
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	250 \item[r(eturn)]
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	251
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	252 Continue execution until the current function returns.
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	253
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	254 \item[c(ont(inue))]
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	255
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	256 Continue execution, only stop when a breakpoint is encountered.
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	257
7061 1d0b9028523c Modify command descriptions to use \optional{} instead of ad-hoc markup. Fred Drake <fdrake@acm.org> parents: 6530 diff changeset	258 \item[l(ist) \optional{\var{first\optional{, last}}}]
9122 86b7129d8d08 Get rid of 'ppp' that accidentally crept in. Guido van Rossum <guido@python.org> parents: 9120 diff changeset	259
2464 e726f90d2a9f minor update Guido van Rossum <guido@python.org> parents: 2462 diff changeset	260 List source code for the current file. Without arguments, list 11
e726f90d2a9f minor update Guido van Rossum <guido@python.org> parents: 2462 diff changeset	261 lines around the current line or continue the previous listing. With
e726f90d2a9f minor update Guido van Rossum <guido@python.org> parents: 2462 diff changeset	262 one argument, list 11 lines around at that line. With two arguments,
e726f90d2a9f minor update Guido van Rossum <guido@python.org> parents: 2462 diff changeset	263 list the given range; if the second argument is less than the first,
e726f90d2a9f minor update Guido van Rossum <guido@python.org> parents: 2462 diff changeset	264 it is interpreted as a count.
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	265
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	266 \item[a(rgs)]
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	267
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	268 Print the argument list of the current function.
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	269
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	270 \item[p \var{expression}]
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	271
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	272 Evaluate the \var{expression} in the current context and print its
10690 a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	273 value. (Note: \samp{print} can also be used, but is not a debugger
a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	274 command --- this executes the Python \keyword{print} statement.)
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	275
9120 55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	276 \item[alias \optional{\var{name} \optional{command}}]
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	277
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	278 Creates an alias called \var{name} that executes \var{command}. The
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	279 command must \emph{not} be enclosed in quotes. Replaceable parameters
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	280 can be indicated by \samp{\%1}, \samp{\%2}, and so on, while \samp{\%*} is
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	281 replaced by all the parameters. If no command is given, the current
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	282 alias for \var{name} is shown. If no arguments are given, all
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	283 aliases are listed.
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	284
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	285 Aliases may be nested and can contain anything that can be
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	286 legally typed at the pdb prompt. Note that internal pdb commands
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	287 \emph{can} be overridden by aliases. Such a command is
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	288 then hidden until the alias is removed. Aliasing is recursively
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	289 applied to the first word of the command line; all other words
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	290 in the line are left alone.
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	291
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	292 As an example, here are two useful aliases (especially when placed
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	293 in the \file{.pdbrc} file):
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	294
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	295 \begin{verbatim}
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	296 #Print instance variables (usage "pi classInst")
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	297 alias pi for k in %1.__dict__.keys(): print "%1.",k,"=",%1.__dict__[k]
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	298 #Print instance variables in self
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	299 alias ps pi self
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	300 \end{verbatim}
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	301
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	302 \item[unalias \var{name}]
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	303
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	304 Deletes the specified alias.
55c1811bb8ef Richard Wolff's changes, documenting his changes to pdb.py. Guido van Rossum <guido@python.org> parents: 8716 diff changeset	305
7061 1d0b9028523c Modify command descriptions to use \optional{} instead of ad-hoc markup. Fred Drake <fdrake@acm.org> parents: 6530 diff changeset	306 \item[\optional{!}\var{statement}]
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	307
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	308 Execute the (one-line) \var{statement} in the context of
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	309 the current stack frame.
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	310 The exclamation point can be omitted unless the first word
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	311 of the statement resembles a debugger command.
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	312 To set a global variable, you can prefix the assignment
10690 a9d613ab5a76 Logical markup and small nits. Fred Drake <fdrake@acm.org> parents: 10594 diff changeset	313 command with a \samp{global} command on the same line, e.g.:
7896 29ab3f602d00 Fixed some index entries. Fred Drake <fdrake@acm.org> parents: 7863 diff changeset	314
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7061 diff changeset	315 \begin{verbatim}
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	316 (Pdb) global list_options; list_options = ['-l']
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	317 (Pdb)
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7061 diff changeset	318 \end{verbatim}
7896 29ab3f602d00 Fixed some index entries. Fred Drake <fdrake@acm.org> parents: 7863 diff changeset	319
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	320 \item[q(uit)]
2462 e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	321
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	322 Quit from the debugger.
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	323 The program being executed is aborted.
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	324
e9e86ae5f5a4 small nits and new files Guido van Rossum <guido@python.org> parents: diff changeset	325 \end{description}
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	326
18693 4381461cce5d Add some symbolic names to support hyperlinked references. Fred Drake <fdrake@acm.org> parents: 16590 diff changeset	327 \section{How It Works \label{debugger-hooks}}
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	328
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	329 Some changes were made to the interpreter:
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	330
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	331 \begin{itemize}
7061 1d0b9028523c Modify command descriptions to use \optional{} instead of ad-hoc markup. Fred Drake <fdrake@acm.org> parents: 6530 diff changeset	332 \item \code{sys.settrace(\var{func})} sets the global trace function
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	333 \item there can also a local trace function (see later)
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	334 \end{itemize}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	335
7896 29ab3f602d00 Fixed some index entries. Fred Drake <fdrake@acm.org> parents: 7863 diff changeset	336 Trace functions have three arguments: \var{frame}, \var{event}, and
29ab3f602d00 Fixed some index entries. Fred Drake <fdrake@acm.org> parents: 7863 diff changeset	337 \var{arg}. \var{frame} is the current stack frame. \var{event} is a
29ab3f602d00 Fixed some index entries. Fred Drake <fdrake@acm.org> parents: 7863 diff changeset	338 string: \code{'call'}, \code{'line'}, \code{'return'} or
29ab3f602d00 Fixed some index entries. Fred Drake <fdrake@acm.org> parents: 7863 diff changeset	339 \code{'exception'}. \var{arg} depends on the event type.
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	340
6530 0cd1f2f1d82d Small wording change about global and local trace functions. Guido van Rossum <guido@python.org> parents: 5818 diff changeset	341 The global trace function is invoked (with \var{event} set to
0cd1f2f1d82d Small wording change about global and local trace functions. Guido van Rossum <guido@python.org> parents: 5818 diff changeset	342 \code{'call'}) whenever a new local scope is entered; it should return
0cd1f2f1d82d Small wording change about global and local trace functions. Guido van Rossum <guido@python.org> parents: 5818 diff changeset	343 a reference to the local trace function to be used that scope, or
0cd1f2f1d82d Small wording change about global and local trace functions. Guido van Rossum <guido@python.org> parents: 5818 diff changeset	344 \code{None} if the scope shouldn't be traced.
0cd1f2f1d82d Small wording change about global and local trace functions. Guido van Rossum <guido@python.org> parents: 5818 diff changeset	345
0cd1f2f1d82d Small wording change about global and local trace functions. Guido van Rossum <guido@python.org> parents: 5818 diff changeset	346 The local trace function should return a reference to itself (or to
0cd1f2f1d82d Small wording change about global and local trace functions. Guido van Rossum <guido@python.org> parents: 5818 diff changeset	347 another function for further tracing in that scope), or \code{None} to
0cd1f2f1d82d Small wording change about global and local trace functions. Guido van Rossum <guido@python.org> parents: 5818 diff changeset	348 turn off tracing in that scope.
0cd1f2f1d82d Small wording change about global and local trace functions. Guido van Rossum <guido@python.org> parents: 5818 diff changeset	349
0cd1f2f1d82d Small wording change about global and local trace functions. Guido van Rossum <guido@python.org> parents: 5818 diff changeset	350 Instance methods are accepted (and very useful!) as trace functions.
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	351
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	352 The events have the following meaning:
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	353
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	354 \begin{description}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	355
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	356 \item[\code{'call'}]
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	357 A function is called (or some other code block entered). The global
19896 0491ea611bc4 Admit that we'll never add the args for a "call" event to the profile Fred Drake <fdrake@acm.org> parents: 18693 diff changeset	358 trace function is called; \var{arg} is \code{None};
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	359 the return value specifies the local trace function.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	360
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	361 \item[\code{'line'}]
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	362 The interpreter is about to execute a new line of code (sometimes
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	363 multiple line events on one line exist). The local trace function is
19896 0491ea611bc4 Admit that we'll never add the args for a "call" event to the profile Fred Drake <fdrake@acm.org> parents: 18693 diff changeset	364 called; \var{arg} is \code{None}; the return value specifies the new
0491ea611bc4 Admit that we'll never add the args for a "call" event to the profile Fred Drake <fdrake@acm.org> parents: 18693 diff changeset	365 local trace function.
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	366
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	367 \item[\code{'return'}]
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	368 A function (or other code block) is about to return. The local trace
19896 0491ea611bc4 Admit that we'll never add the args for a "call" event to the profile Fred Drake <fdrake@acm.org> parents: 18693 diff changeset	369 function is called; \var{arg} is the value that will be returned. The
0491ea611bc4 Admit that we'll never add the args for a "call" event to the profile Fred Drake <fdrake@acm.org> parents: 18693 diff changeset	370 trace function's return value is ignored.
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	371
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	372 \item[\code{'exception'}]
19896 0491ea611bc4 Admit that we'll never add the args for a "call" event to the profile Fred Drake <fdrake@acm.org> parents: 18693 diff changeset	373 An exception has occurred. The local trace function is called;
0491ea611bc4 Admit that we'll never add the args for a "call" event to the profile Fred Drake <fdrake@acm.org> parents: 18693 diff changeset	374 \var{arg} is a triple \code{(\var{exception}, \var{value},
0491ea611bc4 Admit that we'll never add the args for a "call" event to the profile Fred Drake <fdrake@acm.org> parents: 18693 diff changeset	375 \var{traceback})}; the return value specifies the new local trace
0491ea611bc4 Admit that we'll never add the args for a "call" event to the profile Fred Drake <fdrake@acm.org> parents: 18693 diff changeset	376 function.
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	377
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	378 \end{description}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	379
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	380 Note that as an exception is propagated down the chain of callers, an
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	381 \code{'exception'} event is generated at each level.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	382
7647 dee56025d390 Replace lists of attributes for code and frame objects with a reference to the Fred Drake <fdrake@acm.org> parents: 7384 diff changeset	383 For more information on code and frame objects, refer to the
11458 6c5e12c5a616 Use \citetitle in one place. Fred Drake <fdrake@acm.org> parents: 10690 diff changeset	384 \citetitle[../ref/ref.html]{Python Reference Manual}.

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libpdb.tex @ 21467:4e35fa5d5708 legacy-trunk