rest25/library/pdb.rst => rest262/library/pdb.rst
f1
2.. _debugger:
3
n4-*******************
n4+:mod:`pdb` --- The Python Debugger
5-The Python Debugger
5+==================================
6-*******************
7
8.. module:: pdb
9   :synopsis: The Python debugger for interactive interpreters.
10
11
12.. index:: single: debugging
13
14The module :mod:`pdb` defines an interactive source code debugger for Python
33   >>> import mymodule
34   >>> pdb.run('mymodule.test()')
35   > <string>(0)?()
36   (Pdb) continue
37   > <string>(1)?()
38   (Pdb) continue
39   NameError: 'spam'
40   > <string>(1)?()
n41-   (Pdb) 
n40+   (Pdb)
42
43:file:`pdb.py` can also be invoked as a script to debug other scripts.  For
44example::
45
46   python -m pdb myscript.py
47
48When invoked as a script, pdb will automatically enter post-mortem debugging if
49the program being debugged exits abnormally. After post-mortem debugging (or
64     File "./mymodule.py", line 4, in test
65       test2()
66     File "./mymodule.py", line 3, in test2
67       print spam
68   NameError: spam
69   >>> pdb.pm()
70   > ./mymodule.py(3)test2()
71   -> print spam
n72-   (Pdb) 
n71+   (Pdb)
73
74The module defines the following functions; each enters the debugger in a
75slightly different way:
76
77
78.. function:: run(statement[, globals[, locals]])
79
80   Execute the *statement* (given as a string) under debugger control.  The
103
104.. function:: set_trace()
105
106   Enter the debugger at the calling stack frame.  This is useful to hard-code a
107   breakpoint at a given point in a program, even if the code is not otherwise
108   being debugged (e.g. when an assertion fails).
109
110
n111-.. function:: post_mortem(traceback)
n110+.. function:: post_mortem([traceback])
112
n113-   Enter post-mortem debugging of the given *traceback* object.
n112+   Enter post-mortem debugging of the given *traceback* object.  If no
113+   *traceback* is given, it uses the one of the exception that is currently
114+   being handled (an exception must be being handled if the default is to be
115+   used).
114
115
116.. function:: pm()
117
118   Enter post-mortem debugging of the traceback found in ``sys.last_traceback``.
119
120
121.. _debugger-commands:
174   indicates the current frame, which determines the context of most commands.
175
176d(own)
177   Move the current frame one level down in the stack trace (to a newer frame).
178
179u(p)
180   Move the current frame one level up in the stack trace (to an older frame).
181
n182-b(reak) [[*filename*:]*lineno*``|``*function*[, *condition*]]
n184+b(reak) [[*filename*:]*lineno* | *function*[, *condition*]]
183   With a *lineno* argument, set a break there in the current file.  With a
184   *function* argument, set a break at the first executable statement within that
185   function. The line number may be prefixed with a filename and a colon, to
186   specify a breakpoint in another file (probably one that hasn't been loaded yet).
187   The file is searched on ``sys.path``. Note that each breakpoint is assigned a
188   number to which all the other breakpoint commands refer.
189
190   If a second argument is present, it is an expression which must evaluate to true
191   before the breakpoint is honored.
192
193   Without argument, list all breaks, including for each breakpoint, the number of
194   times that breakpoint has been hit, the current ignore count, and the associated
195   condition if any.
196
n197-tbreak [[*filename*:]*lineno*``|``*function*[, *condition*]]
n199+tbreak [[*filename*:]*lineno* | *function*[, *condition*]]
198   Temporary breakpoint, which is removed automatically when it is first hit.  The
199   arguments are the same as break.
200
201cl(ear) [*bpnumber* [*bpnumber ...*]]
202   With a space separated list of breakpoint numbers, clear those breakpoints.
203   Without argument, clear all breaks (but first ask confirmation).
204
205disable [*bpnumber* [*bpnumber ...*]]
239   With no *bpnumber* argument, commands refers to the last breakpoint set.
240
241   You can use breakpoint commands to start your program up again. Simply use the
242   continue command, or step, or any other command that resumes execution.
243
244   Specifying any command resuming execution (currently continue, step, next,
245   return, jump, quit and their abbreviations) terminates the command list (as if
246   that command was immediately followed by end). This is because any time you
n247-   resume execution (even with a simple next or step), you may encounter· another
n249+   resume execution (even with a simple next or step), you may encounter another
248   breakpoint--which could have its own command list, leading to ambiguities about
249   which list to execute.
250
251   If you use the 'silent' command in the command list, the usual message about
252   stopping at a breakpoint is not printed.  This may be desirable for breakpoints
253   that are to print a specific message and then continue.  If none of the other
254   commands print anything, you see no sign that the breakpoint was reached.
255
260   function that is called or on the next line in the current function).
261
262n(ext)
263   Continue execution until the next line in the current function is reached or it
264   returns.  (The difference between ``next`` and ``step`` is that ``step`` stops
265   inside a called function, while ``next`` executes called functions at (nearly)
266   full speed, only stopping at the next line in the current function.)
267
n270+unt(il)
271+   Continue execution until the line with the line number greater than the
272+   current one is reached or when returning from current frame.
273+ 
274+   .. versionadded:: 2.6
275+ 
268r(eturn)
269   Continue execution until the current function returns.
270
271c(ont(inue))
272   Continue execution, only stop when a breakpoint is encountered.
273
274j(ump) *lineno*
275   Set the next line that will be executed.  Only available in the bottom-most
276   frame.  This lets you jump back and execute code again, or jump forward to skip
277   code that you don't want to run.
278
279   It should be noted that not all jumps are allowed --- for instance it is not
280   possible to jump into the middle of a :keyword:`for` loop or out of a
281   :keyword:`finally` clause.
282
n283-l(ist) [*first*[, *last*]]
n291+l(ist) [*first*[, *last*]]
284   List source code for the current file.  Without arguments, list 11 lines around
285   the current line or continue the previous listing.  With one argument, list 11
286   lines around at that line.  With two arguments, list the given range; if the
287   second argument is less than the first, it is interpreted as a count.
288
289a(rgs)
290   Print the argument list of the current function.
291
320      #Print instance variables (usage "pi classInst")
321      alias pi for k in %1.__dict__.keys(): print "%1.",k,"=",%1.__dict__[k]
322      #Print instance variables in self
323      alias ps pi self
324
325unalias *name*
326   Deletes the specified alias.
327
n328-[!]*statement*
n336+[!]*statement*
329   Execute the (one-line) *statement* in the context of the current stack frame.
330   The exclamation point can be omitted unless the first word of the statement
331   resembles a debugger command. To set a global variable, you can prefix the
332   assignment command with a ``global`` command on the same line, e.g.::
333
334      (Pdb) global list_options; list_options = ['-l']
335      (Pdb)
336
n345+run [*args* ...]
346+   Restart the debugged python program. If an argument is supplied, it is split
347+   with "shlex" and the result is used as the new sys.argv. History, breakpoints,
348+   actions and debugger options are preserved. "restart" is an alias for "run".
349+ 
350+   .. versionadded:: 2.6
351+ 
337q(uit)
338   Quit from the debugger. The program being executed is aborted.
t339- 
340- 
341-.. _debugger-hooks:
342- 
343-How It Works
344-============
345- 
346-Some changes were made to the interpreter:
347- 
348-* ``sys.settrace(func)`` sets the global trace function
349- 
350-* there can also a local trace function (see later)
351- 
352-Trace functions have three arguments: *frame*, *event*, and *arg*. *frame* is
353-the current stack frame.  *event* is a string: ``'call'``, ``'line'``,
354-``'return'``, ``'exception'``, ``'c_call'``, ``'c_return'``, or
355-``'c_exception'``. *arg* depends on the event type.
356- 
357-The global trace function is invoked (with *event* set to ``'call'``) whenever a
358-new local scope is entered; it should return a reference to the local trace
359-function to be used that scope, or ``None`` if the scope shouldn't be traced.
360- 
361-The local trace function should return a reference to itself (or to another
362-function for further tracing in that scope), or ``None`` to turn off tracing in
363-that scope.
364- 
365-Instance methods are accepted (and very useful!) as trace functions.
366- 
367-The events have the following meaning:
368- 
369-``'call'``
370-   A function is called (or some other code block entered).  The global trace
371-   function is called; *arg* is ``None``; the return value specifies the local
372-   trace function.
373- 
374-``'line'``
375-   The interpreter is about to execute a new line of code (sometimes multiple line
376-   events on one line exist).  The local trace function is called; *arg* is
377-   ``None``; the return value specifies the new local trace function.
378- 
379-``'return'``
380-   A function (or other code block) is about to return.  The local trace function
381-   is called; *arg* is the value that will be returned.  The trace function's
382-   return value is ignored.
383- 
384-``'exception'``
385-   An exception has occurred.  The local trace function is called; *arg* is a
386-   triple ``(exception, value, traceback)``; the return value specifies the new
387-   local trace function.
388- 
389-``'c_call'``
390-   A C function is about to be called.  This may be an extension function or a
391-   builtin.  *arg* is the C function object.
392- 
393-``'c_return'``
394-   A C function has returned. *arg* is ``None``.
395- 
396-``'c_exception'``
397-   A C function has thrown an exception.  *arg* is ``None``.
398- 
399-Note that as an exception is propagated down the chain of callers, an
400-``'exception'`` event is generated at each level.
401- 
402-For more information on code and frame objects, refer to the Python Reference
403-Manual (XXX reference: ../ref/ref.html).
404- 
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op