Mercurial > cpython-lru_cache-weakref
annotate Doc/lib/libpdb.tex @ 5817:48b94de85bf3 legacy-trunk
Extensive changes by AMK.
| author | Guido van Rossum <guido@python.org> |
|---|---|
| date | Thu, 17 Jul 1997 16:29:42 +0000 |
| parents | b7649491ae92 |
| children | 3468ea8645ca |
| rev | line source |
|---|---|
| 2464 | 1 \chapter{The Python Debugger} |
| 2462 | 2 \stmodindex{pdb} |
| 3 \index{debugging} | |
| 4 | |
| 2464 | 5 \renewcommand{\indexsubitem}{(in module pdb)} |
| 6 | |
| 7 The module \code{pdb} defines an interactive source code debugger for | |
|
5768
7de59f47e85b
Added (minimal) doc for conditional breakpoints.
Guido van Rossum <guido@python.org>
parents:
5679
diff
changeset
|
8 Python programs. It supports setting |
|
7de59f47e85b
Added (minimal) doc for conditional breakpoints.
Guido van Rossum <guido@python.org>
parents:
5679
diff
changeset
|
9 (conditional) breakpoints and single stepping |
| 2464 | 10 at the source line level, inspection of stack frames, source code |
| 11 listing, and evaluation of arbitrary Python code in the context of any | |
| 12 stack frame. It also supports post-mortem debugging and can be called | |
| 13 under program control. | |
| 2462 | 14 |
| 15 The debugger is extensible --- it is actually defined as a class | |
|
2629
175671cc21d8
more complete examples
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
16 \code{Pdb}. This is currently undocumented but easily understood by |
|
175671cc21d8
more complete examples
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
17 reading the source. The extension interface uses the (also |
|
175671cc21d8
more complete examples
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
18 undocumented) modules \code{bdb} and \code{cmd}. |
| 2462 | 19 \ttindex{Pdb} |
| 20 \ttindex{bdb} | |
| 21 \ttindex{cmd} | |
| 22 | |
| 23 A primitive windowing version of the debugger also exists --- this is | |
| 2464 | 24 module \code{wdb}, which requires STDWIN (see the chapter on STDWIN |
| 25 specific modules). | |
| 2462 | 26 \index{stdwin} |
| 27 \ttindex{wdb} | |
| 28 | |
|
2629
175671cc21d8
more complete examples
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
29 The debugger's prompt is ``\code{(Pdb) }''. |
| 2462 | 30 Typical usage to run a program under control of the debugger is: |
| 31 | |
| 32 \begin{verbatim} | |
| 33 >>> import pdb | |
| 34 >>> import mymodule | |
| 35 >>> pdb.run('mymodule.test()') | |
|
2629
175671cc21d8
more complete examples
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
36 > <string>(0)?() |
|
175671cc21d8
more complete examples
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
37 (Pdb) continue |
|
175671cc21d8
more complete examples
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
38 > <string>(1)?() |
|
175671cc21d8
more complete examples
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
39 (Pdb) continue |
|
175671cc21d8
more complete examples
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
40 NameError: 'spam' |
|
175671cc21d8
more complete examples
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
41 > <string>(1)?() |
|
175671cc21d8
more complete examples
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
42 (Pdb) |
| 2462 | 43 \end{verbatim} |
| 44 | |
|
5679
d5911ca8d4eb
Mention use of pdb.py to run a script (AMK).
Guido van Rossum <guido@python.org>
parents:
2629
diff
changeset
|
45 \code{pdb.py} can also be invoked as |
|
d5911ca8d4eb
Mention use of pdb.py to run a script (AMK).
Guido van Rossum <guido@python.org>
parents:
2629
diff
changeset
|
46 a script to debug other scripts. For example: |
|
d5911ca8d4eb
Mention use of pdb.py to run a script (AMK).
Guido van Rossum <guido@python.org>
parents:
2629
diff
changeset
|
47 \code{python /usr/local/lib/python1.4/pdb.py myscript.py} |
|
d5911ca8d4eb
Mention use of pdb.py to run a script (AMK).
Guido van Rossum <guido@python.org>
parents:
2629
diff
changeset
|
48 |
| 2462 | 49 Typical usage to inspect a crashed program is: |
| 50 | |
| 51 \begin{verbatim} | |
| 52 >>> import pdb | |
| 53 >>> import mymodule | |
| 54 >>> mymodule.test() | |
|
2629
175671cc21d8
more complete examples
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
55 Traceback (innermost last): |
|
175671cc21d8
more complete examples
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
56 File "<stdin>", line 1, in ? |
|
175671cc21d8
more complete examples
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
57 File "./mymodule.py", line 4, in test |
|
175671cc21d8
more complete examples
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
58 test2() |
|
175671cc21d8
more complete examples
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
59 File "./mymodule.py", line 3, in 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 NameError: spam |
| 2462 | 62 >>> pdb.pm() |
|
2629
175671cc21d8
more complete examples
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
63 > ./mymodule.py(3)test2() |
|
175671cc21d8
more complete examples
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
64 -> print spam |
|
175671cc21d8
more complete examples
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
65 (Pdb) |
| 2462 | 66 \end{verbatim} |
| 67 | |
| 68 The module defines the following functions; each enters the debugger | |
| 69 in a slightly different way: | |
| 70 | |
| 71 \begin{funcdesc}{run}{statement\optional{\, globals\optional{\, locals}}} | |
| 2464 | 72 Execute the \var{statement} (given as a string) under debugger |
| 2462 | 73 control. The debugger prompt appears before any code is executed; you |
| 2464 | 74 can set breakpoints and type \code{continue}, or you can step through |
| 75 the statement using \code{step} or \code{next} (all these commands are | |
| 76 explained below). The optional \var{globals} and \var{locals} | |
| 77 arguments specify the environment in which the code is executed; by | |
| 78 default the dictionary of the module \code{__main__} is used. (See | |
| 79 the explanation of the \code{exec} statement or the \code{eval()} | |
| 80 built-in function.) | |
| 2462 | 81 \end{funcdesc} |
| 82 | |
| 83 \begin{funcdesc}{runeval}{expression\optional{\, globals\optional{\, locals}}} | |
| 2464 | 84 Evaluate the \var{expression} (given as a a string) under debugger |
| 85 control. When \code{runeval()} returns, it returns the value of the | |
| 86 expression. Otherwise this function is similar to | |
| 2462 | 87 \code{run()}. |
| 88 \end{funcdesc} | |
| 89 | |
| 90 \begin{funcdesc}{runcall}{function\optional{\, argument\, ...}} | |
| 2464 | 91 Call the \var{function} (a function or method object, not a string) |
| 92 with the given arguments. When \code{runcall()} returns, it returns | |
| 93 whatever the function call returned. The debugger prompt appears as | |
| 94 soon as the function is entered. | |
| 2462 | 95 \end{funcdesc} |
| 96 | |
| 97 \begin{funcdesc}{set_trace}{} | |
| 98 Enter the debugger at the calling stack frame. This is useful to | |
| 2464 | 99 hard-code a breakpoint at a given point in a program, even if the code |
| 100 is not otherwise being debugged (e.g. when an assertion fails). | |
| 2462 | 101 \end{funcdesc} |
| 102 | |
| 103 \begin{funcdesc}{post_mortem}{traceback} | |
| 104 Enter post-mortem debugging of the given \var{traceback} object. | |
| 105 \end{funcdesc} | |
| 106 | |
| 107 \begin{funcdesc}{pm}{} | |
| 2464 | 108 Enter post-mortem debugging of the traceback found in |
| 2462 | 109 \code{sys.last_traceback}. |
| 110 \end{funcdesc} | |
| 111 | |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
112 \section{Debugger Commands} |
| 2462 | 113 |
| 114 The debugger recognizes the following commands. Most commands can be | |
| 115 abbreviated to one or two letters; e.g. ``\code{h(elp)}'' means that | |
| 116 either ``\code{h}'' or ``\code{help}'' can be used to enter the help | |
| 117 command (but not ``\code{he}'' or ``\code{hel}'', nor ``\code{H}'' or | |
| 118 ``\code{Help} or ``\code{HELP}''). Arguments to commands must be | |
| 119 separated by whitespace (spaces or tabs). Optional arguments are | |
|
2491
fb8e08ec88dd
changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents:
2464
diff
changeset
|
120 enclosed in square brackets (``\code{[]}'') in the command syntax; the |
| 2462 | 121 square brackets must not be typed. Alternatives in the command syntax |
| 122 are separated by a vertical bar (``\code{|}''). | |
| 123 | |
| 124 Entering a blank line repeats the last command entered. Exception: if | |
| 125 the last command was a ``\code{list}'' command, the next 11 lines are | |
| 126 listed. | |
| 127 | |
| 128 Commands that the debugger doesn't recognize are assumed to be Python | |
| 129 statements and are executed in the context of the program being | |
| 130 debugged. Python statements can also be prefixed with an exclamation | |
| 131 point (``\code{!}''). This is a powerful way to inspect the program | |
|
2629
175671cc21d8
more complete examples
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
132 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
|
133 function. When an |
| 2462 | 134 exception occurs in such a statement, the exception name is printed |
| 135 but the debugger's state is not changed. | |
| 136 | |
| 137 \begin{description} | |
| 138 | |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
139 \item[h(elp) [\var{command}]] |
| 2462 | 140 |
| 141 Without argument, print the list of available commands. | |
| 142 With a \var{command} as argument, print help about that command. | |
| 143 ``\code{help pdb}'' displays the full documentation file; if the | |
| 144 environment variable \code{PAGER} is defined, the file is piped | |
| 2464 | 145 through that command instead. Since the \var{command} argument must be |
| 146 an identifier, ``\code{help exec}'' must be entered to get help on the | |
| 147 ``\code{!}'' command. | |
| 2462 | 148 |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
149 \item[w(here)] |
| 2462 | 150 |
| 151 Print a stack trace, with the most recent frame at the bottom. | |
| 152 An arrow indicates the current frame, which determines the | |
| 153 context of most commands. | |
| 154 | |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
155 \item[d(own)] |
| 2462 | 156 |
| 157 Move the current frame one level down in the stack trace | |
| 158 (to an older frame). | |
| 159 | |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
160 \item[u(p)] |
| 2462 | 161 |
| 162 Move the current frame one level up in the stack trace | |
| 163 (to a newer frame). | |
| 164 | |
|
5769
b7649491ae92
Oops, some clarifications to conditional breaks.
Guido van Rossum <guido@python.org>
parents:
5768
diff
changeset
|
165 \item[b(reak) [\var{lineno}\code{|}\var{function}] [, "\var{condition}"]] |
| 2462 | 166 |
| 167 With a \var{lineno} argument, set a break there in the current | |
| 168 file. With a \var{function} argument, set a break at the entry of | |
| 169 that function. Without argument, list all breaks. | |
|
5769
b7649491ae92
Oops, some clarifications to conditional breaks.
Guido van Rossum <guido@python.org>
parents:
5768
diff
changeset
|
170 If a second argument is present, it is a string (included in string |
|
b7649491ae92
Oops, some clarifications to conditional breaks.
Guido van Rossum <guido@python.org>
parents:
5768
diff
changeset
|
171 quotes!) specifying an expression which must evaluate to true before |
|
b7649491ae92
Oops, some clarifications to conditional breaks.
Guido van Rossum <guido@python.org>
parents:
5768
diff
changeset
|
172 the breakpoint is honored. |
| 2462 | 173 |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
174 \item[cl(ear) [\var{lineno}]] |
| 2462 | 175 |
| 176 With a \var{lineno} argument, clear that break in the current file. | |
| 177 Without argument, clear all breaks (but first ask confirmation). | |
| 178 | |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
179 \item[s(tep)] |
| 2462 | 180 |
| 181 Execute the current line, stop at the first possible occasion | |
| 182 (either in a function that is called or on the next line in the | |
| 183 current function). | |
| 184 | |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
185 \item[n(ext)] |
| 2462 | 186 |
| 187 Continue execution until the next line in the current function | |
| 188 is reached or it returns. (The difference between \code{next} and | |
| 189 \code{step} is that \code{step} stops inside a called function, while | |
| 2464 | 190 \code{next} executes called functions at (nearly) full speed, only |
| 191 stopping at the next line in the current function.) | |
| 2462 | 192 |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
193 \item[r(eturn)] |
| 2462 | 194 |
| 195 Continue execution until the current function returns. | |
| 196 | |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
197 \item[c(ont(inue))] |
| 2462 | 198 |
| 199 Continue execution, only stop when a breakpoint is encountered. | |
| 200 | |
|
5768
7de59f47e85b
Added (minimal) doc for conditional breakpoints.
Guido van Rossum <guido@python.org>
parents:
5679
diff
changeset
|
201 \item[l(ist) [\var{first}] [, \var{last}]] |
| 2462 | 202 |
| 2464 | 203 List source code for the current file. Without arguments, list 11 |
| 204 lines around the current line or continue the previous listing. With | |
| 205 one argument, list 11 lines around at that line. With two arguments, | |
| 206 list the given range; if the second argument is less than the first, | |
| 207 it is interpreted as a count. | |
| 2462 | 208 |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
209 \item[a(rgs)] |
| 2462 | 210 |
| 211 Print the argument list of the current function. | |
| 212 | |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
213 \item[p \var{expression}] |
| 2462 | 214 |
| 215 Evaluate the \var{expression} in the current context and print its | |
| 2464 | 216 value. (Note: \code{print} can also be used, but is not a debugger |
| 217 command --- this executes the Python \code{print} statement.) | |
| 2462 | 218 |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
219 \item[[!] \var{statement}] |
| 2462 | 220 |
| 221 Execute the (one-line) \var{statement} in the context of | |
| 222 the current stack frame. | |
| 223 The exclamation point can be omitted unless the first word | |
| 224 of the statement resembles a debugger command. | |
| 225 To set a global variable, you can prefix the assignment | |
| 226 command with a ``\code{global}'' command on the same line, e.g.: | |
| 227 \begin{verbatim} | |
| 228 (Pdb) global list_options; list_options = ['-l'] | |
| 229 (Pdb) | |
| 230 \end{verbatim} | |
| 231 | |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
232 \item[q(uit)] |
| 2462 | 233 |
| 234 Quit from the debugger. | |
| 235 The program being executed is aborted. | |
| 236 | |
| 237 \end{description} | |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
238 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
239 \section{How It Works} |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
240 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
241 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
|
242 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
243 \begin{itemize} |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
244 \item sys.settrace(func) sets the global trace function |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
245 \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
|
246 \end{itemize} |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
247 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
248 Trace functions have three arguments: (\var{frame}, \var{event}, \var{arg}) |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
249 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
250 \begin{description} |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
251 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
252 \item[\var{frame}] is the current stack frame |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
253 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
254 \item[\var{event}] is a string: \code{'call'}, \code{'line'}, \code{'return'} |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
255 or \code{'exception'} |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
256 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
257 \item[\var{arg}] is dependent on the event type |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
258 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
259 \end{description} |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
260 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
261 A trace function should return a new trace function or None. |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
262 Class methods are accepted (and most useful!) as trace methods. |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
263 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
264 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
|
265 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
266 \begin{description} |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
267 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
268 \item[\code{'call'}] |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
269 A function is called (or some other code block entered). The global |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
270 trace function is called; arg is the argument list to the function; |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
271 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
|
272 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
273 \item[\code{'line'}] |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
274 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
|
275 multiple line events on one line exist). The local trace function is |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
276 called; arg in None; the return value specifies the new local trace |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
277 function. |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
278 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
279 \item[\code{'return'}] |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
280 A function (or other code block) is about to return. The local trace |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
281 function is called; arg is the value that will be returned. The trace |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
282 function's return value is ignored. |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
283 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
284 \item[\code{'exception'}] |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
285 An exception has occurred. The local trace function is called; arg is |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
286 a triple (exception, value, traceback); the return value specifies the |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
287 new local trace function |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
288 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
289 \end{description} |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
290 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
291 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
|
292 \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
|
293 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
294 Stack frame objects have the following read-only attributes: |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
295 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
296 \begin{description} |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
297 \item[f_code] the code object being executed |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
298 \item[f_lineno] the current line number (\code{-1} for \code{'call'} events) |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
299 \item[f_back] the stack frame of the caller, or None |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
300 \item[f_locals] dictionary containing local name bindings |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
301 \item[f_globals] dictionary containing global name bindings |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
302 \end{description} |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
303 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
304 Code objects have the following read-only attributes: |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
305 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
306 \begin{description} |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
307 \item[co_code] the code string |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
308 \item[co_names] the list of names used by the code |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
309 \item[co_consts] the list of (literal) constants used by the code |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
310 \item[co_filename] the filename from which the code was compiled |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
311 \end{description} |