diff options
Diffstat (limited to 'Doc/lib/libpdb.tex')
| -rw-r--r-- | Doc/lib/libpdb.tex | 464 |
1 files changed, 0 insertions, 464 deletions
diff --git a/Doc/lib/libpdb.tex b/Doc/lib/libpdb.tex deleted file mode 100644 index 45e778c..0000000 --- a/Doc/lib/libpdb.tex +++ /dev/null @@ -1,464 +0,0 @@ -\chapter{The Python Debugger \label{debugger}} - -\declaremodule{standard}{pdb} -\modulesynopsis{The Python debugger for interactive interpreters.} - - -The module \module{pdb} defines an interactive source code -debugger\index{debugging} for Python programs. It supports setting -(conditional) breakpoints and single stepping at the source line -level, inspection of stack frames, source code listing, and evaluation -of arbitrary Python code in the context of any stack frame. It also -supports post-mortem debugging and can be called under program -control. - -The debugger is extensible --- it is actually defined as the class -\class{Pdb}\withsubitem{(class in pdb)}{\ttindex{Pdb}}. -This is currently undocumented but easily understood by reading the -source. The extension interface uses the modules -\module{bdb}\refstmodindex{bdb} (undocumented) and -\refmodule{cmd}\refstmodindex{cmd}. - -The debugger's prompt is \samp{(Pdb) }. -Typical usage to run a program under control of the debugger is: - -\begin{verbatim} ->>> import pdb ->>> import mymodule ->>> pdb.run('mymodule.test()') -> <string>(0)?() -(Pdb) continue -> <string>(1)?() -(Pdb) continue -NameError: 'spam' -> <string>(1)?() -(Pdb) -\end{verbatim} - -\file{pdb.py} can also be invoked as -a script to debug other scripts. For example: - -\begin{verbatim} -python -m pdb myscript.py -\end{verbatim} - -When invoked as a script, pdb will automatically enter post-mortem debugging -if the program being debugged exits abnormally. After post-mortem debugging -(or after normal exit of the program), pdb will restart the program. -Automatic restarting preserves pdb's state (such as breakpoints) and in most -cases is more useful than quitting the debugger upon program's exit. -\versionadded[Restarting post-mortem behavior added]{2.4} - -Typical usage to inspect a crashed program is: - -\begin{verbatim} ->>> import pdb ->>> import mymodule ->>> mymodule.test() -Traceback (most recent call last): - File "<stdin>", line 1, in ? - File "./mymodule.py", line 4, in test - test2() - File "./mymodule.py", line 3, in test2 - print spam -NameError: spam ->>> pdb.pm() -> ./mymodule.py(3)test2() --> print spam -(Pdb) -\end{verbatim} - -The module defines the following functions; each enters the debugger -in a slightly different way: - -\begin{funcdesc}{run}{statement\optional{, globals\optional{, locals}}} -Execute the \var{statement} (given as a string) under debugger -control. The debugger prompt appears before any code is executed; you -can set breakpoints and type \samp{continue}, or you can step through -the statement using \samp{step} or \samp{next} (all these commands are -explained below). The optional \var{globals} and \var{locals} -arguments specify the environment in which the code is executed; by -default the dictionary of the module \refmodule[main]{__main__} is -used. (See the explanation of the built-in \function{exec()} or -\function{eval()} functions.) -\end{funcdesc} - -\begin{funcdesc}{runeval}{expression\optional{, globals\optional{, locals}}} -Evaluate the \var{expression} (given as a string) under debugger -control. When \function{runeval()} returns, it returns the value of the -expression. Otherwise this function is similar to -\function{run()}. -\end{funcdesc} - -\begin{funcdesc}{runcall}{function\optional{, argument, ...}} -Call the \var{function} (a function or method object, not a string) -with the given arguments. When \function{runcall()} returns, it returns -whatever the function call returned. The debugger prompt appears as -soon as the function is entered. -\end{funcdesc} - -\begin{funcdesc}{set_trace}{} -Enter the debugger at the calling stack frame. This is useful to -hard-code a breakpoint at a given point in a program, even if the code -is not otherwise being debugged (e.g. when an assertion fails). -\end{funcdesc} - -\begin{funcdesc}{post_mortem}{traceback} -Enter post-mortem debugging of the given \var{traceback} object. -\end{funcdesc} - -\begin{funcdesc}{pm}{} -Enter post-mortem debugging of the traceback found in -\code{sys.last_traceback}. -\end{funcdesc} - - -\section{Debugger Commands \label{debugger-commands}} - -The debugger recognizes the following commands. Most commands can be -abbreviated to one or two letters; e.g. \samp{h(elp)} means that -either \samp{h} or \samp{help} can be used to enter the help -command (but not \samp{he} or \samp{hel}, nor \samp{H} or -\samp{Help} or \samp{HELP}). Arguments to commands must be -separated by whitespace (spaces or tabs). Optional arguments are -enclosed in square brackets (\samp{[]}) in the command syntax; the -square brackets must not be typed. Alternatives in the command syntax -are separated by a vertical bar (\samp{|}). - -Entering a blank line repeats the last command entered. Exception: if -the last command was a \samp{list} command, the next 11 lines are -listed. - -Commands that the debugger doesn't recognize are assumed to be Python -statements and are executed in the context of the program being -debugged. Python statements can also be prefixed with an exclamation -point (\samp{!}). This is a powerful way to inspect the program -being debugged; it is even possible to change a variable or call a -function. When an -exception occurs in such a statement, the exception name is printed -but the debugger's state is not changed. - -Multiple commands may be entered on a single line, separated by -\samp{;;}. (A single \samp{;} is not used as it is -the separator for multiple commands in a line that is passed to -the Python parser.) -No intelligence is applied to separating the commands; -the input is split at the first \samp{;;} pair, even if it is in -the middle of a quoted string. - -The debugger supports aliases. Aliases can have parameters which -allows one a certain level of adaptability to the context under -examination. - -If a file \file{.pdbrc} -\indexii{.pdbrc}{file}\indexiii{debugger}{configuration}{file} -exists in the user's home directory or in the current directory, it is -read in and executed as if it had been typed at the debugger prompt. -This is particularly useful for aliases. If both files exist, the one -in the home directory is read first and aliases defined there can be -overridden by the local file. - -\begin{description} - -\item[h(elp) \optional{\var{command}}] - -Without argument, print the list of available commands. With a -\var{command} as argument, print help about that command. \samp{help -pdb} displays the full documentation file; if the environment variable -\envvar{PAGER} is defined, the file is piped through that command -instead. Since the \var{command} argument must be an identifier, -\samp{help exec} must be entered to get help on the \samp{!} command. - -\item[w(here)] - -Print a stack trace, with the most recent frame at the bottom. An -arrow indicates the current frame, which determines the context of -most commands. - -\item[d(own)] - -Move the current frame one level down in the stack trace -(to a newer frame). - -\item[u(p)] - -Move the current frame one level up in the stack trace -(to an older frame). - -\item[b(reak) \optional{\optional{\var{filename}:}\var{lineno}\code{\Large{|}}\var{function}\optional{, \var{condition}}}] - -With a \var{lineno} argument, set a break there in the current -file. With a \var{function} argument, set a break at the first -executable statement within that function. -The line number may be prefixed with a filename and a colon, -to specify a breakpoint in another file (probably one that -hasn't been loaded yet). The file is searched on \code{sys.path}. -Note that each breakpoint is assigned a number to which all the other -breakpoint commands refer. - -If a second argument is present, it is an expression which must -evaluate to true before the breakpoint is honored. - -Without argument, list all breaks, including for each breakpoint, -the number of times that breakpoint has been hit, the current -ignore count, and the associated condition if any. - -\item[tbreak \optional{\optional{\var{filename}:}\var{lineno}\code{\Large{|}}\var{function}\optional{, \var{condition}}}] - -Temporary breakpoint, which is removed automatically when it is -first hit. The arguments are the same as break. - -\item[cl(ear) \optional{\var{bpnumber} \optional{\var{bpnumber ...}}}] - -With a space separated list of breakpoint numbers, clear those -breakpoints. Without argument, clear all breaks (but first -ask confirmation). - -\item[disable \optional{\var{bpnumber} \optional{\var{bpnumber ...}}}] - -Disables the breakpoints given as a space separated list of -breakpoint numbers. Disabling a breakpoint means it cannot cause -the program to stop execution, but unlike clearing a breakpoint, it -remains in the list of breakpoints and can be (re-)enabled. - -\item[enable \optional{\var{bpnumber} \optional{\var{bpnumber ...}}}] - -Enables the breakpoints specified. - -\item[ignore \var{bpnumber} \optional{\var{count}}] - -Sets the ignore count for the given breakpoint number. If -count is omitted, the ignore count is set to 0. A breakpoint -becomes active when the ignore count is zero. When non-zero, -the count is decremented each time the breakpoint is reached -and the breakpoint is not disabled and any associated condition -evaluates to true. - -\item[condition \var{bpnumber} \optional{\var{condition}}] - -Condition is an expression which must evaluate to true before -the breakpoint is honored. If condition is absent, any existing -condition is removed; i.e., the breakpoint is made unconditional. - -\item[commands \optional{\var{bpnumber}}] - -Specify a list of commands for breakpoint number \var{bpnumber}. The -commands themselves appear on the following lines. Type a line -containing just 'end' to terminate the commands. An example: - -\begin{verbatim} -(Pdb) commands 1 -(com) print some_variable -(com) end -(Pdb) -\end{verbatim} - -To remove all commands from a breakpoint, type commands and -follow it immediately with end; that is, give no commands. - -With no \var{bpnumber} argument, commands refers to the last -breakpoint set. - -You can use breakpoint commands to start your program up again. -Simply use the continue command, or step, or any other -command that resumes execution. - -Specifying any command resuming execution (currently continue, -step, next, return, jump, quit and their abbreviations) terminates -the command list (as if that command was immediately followed by end). -This is because any time you resume execution -(even with a simple next or step), you may encounter· -another breakpoint--which could have its own command list, leading to -ambiguities about which list to execute. - - If you use the 'silent' command in the command list, the -usual message about stopping at a breakpoint is not printed. This may -be desirable for breakpoints that are to print a specific message and -then continue. If none of the other commands print anything, you -see no sign that the breakpoint was reached. - -\versionadded{2.5} - -\item[s(tep)] - -Execute the current line, stop at the first possible occasion -(either in a function that is called or on the next line in the -current function). - -\item[n(ext)] - -Continue execution until the next line in the current function -is reached or it returns. (The difference between \samp{next} and -\samp{step} is that \samp{step} stops inside a called function, while -\samp{next} executes called functions at (nearly) full speed, only -stopping at the next line in the current function.) - -\item[r(eturn)] - -Continue execution until the current function returns. - -\item[c(ont(inue))] - -Continue execution, only stop when a breakpoint is encountered. - -\item[j(ump) \var{lineno}] - -Set the next line that will be executed. Only available in the -bottom-most frame. This lets you jump back and execute code -again, or jump forward to skip code that you don't want to run. - -It should be noted that not all jumps are allowed --- for instance it -is not possible to jump into the middle of a \keyword{for} loop or out -of a \keyword{finally} clause. - -\item[l(ist) \optional{\var{first}\optional{, \var{last}}}] - -List source code for the current file. Without arguments, list 11 -lines around the current line or continue the previous listing. With -one argument, list 11 lines around at that line. With two arguments, -list the given range; if the second argument is less than the first, -it is interpreted as a count. - -\item[a(rgs)] - -Print the argument list of the current function. - -\item[p \var{expression}] - -Evaluate the \var{expression} in the current context and print its -value. \note{\samp{print} can also be used, but is not a debugger -command --- this executes the Python \keyword{print} statement.} - -\item[pp \var{expression}] - -Like the \samp{p} command, except the value of the expression is -pretty-printed using the \module{pprint} module. - -\item[alias \optional{\var{name} \optional{command}}] - -Creates an alias called \var{name} that executes \var{command}. The -command must \emph{not} be enclosed in quotes. Replaceable parameters -can be indicated by \samp{\%1}, \samp{\%2}, and so on, while \samp{\%*} is -replaced by all the parameters. If no command is given, the current -alias for \var{name} is shown. If no arguments are given, all -aliases are listed. - -Aliases may be nested and can contain anything that can be -legally typed at the pdb prompt. Note that internal pdb commands -\emph{can} be overridden by aliases. Such a command is -then hidden until the alias is removed. Aliasing is recursively -applied to the first word of the command line; all other words -in the line are left alone. - -As an example, here are two useful aliases (especially when placed -in the \file{.pdbrc} file): - -\begin{verbatim} -#Print instance variables (usage "pi classInst") -alias pi for k in %1.__dict__.keys(): print "%1.",k,"=",%1.__dict__[k] -#Print instance variables in self -alias ps pi self -\end{verbatim} - -\item[unalias \var{name}] - -Deletes the specified alias. - -\item[\optional{!}\var{statement}] - -Execute the (one-line) \var{statement} in the context of -the current stack frame. -The exclamation point can be omitted unless the first word -of the statement resembles a debugger command. -To set a global variable, you can prefix the assignment -command with a \samp{global} command on the same line, e.g.: - -\begin{verbatim} -(Pdb) global list_options; list_options = ['-l'] -(Pdb) -\end{verbatim} - -\item[run \optional{\var{args} ...}] -Restart the debugged python program. If an argument is supplied, it is -splitted with "shlex" and the result is used as the new sys.argv. -History, breakpoints, actions and debugger options are preserved. -"restart" is an alias for "run". - -\versionadded{2.6} - -\item[q(uit)] - -Quit from the debugger. -The program being executed is aborted. - -\end{description} - -\section{How It Works \label{debugger-hooks}} - -Some changes were made to the interpreter: - -\begin{itemize} -\item \code{sys.settrace(\var{func})} sets the global trace function -\item there can also a local trace function (see later) -\end{itemize} - -Trace functions have three arguments: \var{frame}, \var{event}, and -\var{arg}. \var{frame} is the current stack frame. \var{event} is a -string: \code{'call'}, \code{'line'}, \code{'return'}, \code{'exception'}, - \code{'c_call'}, \code{'c_return'}, or \code{'c_exception'}. \var{arg} - depends on the event type. - -The global trace function is invoked (with \var{event} set to -\code{'call'}) whenever a new local scope is entered; it should return -a reference to the local trace function to be used that scope, or -\code{None} if the scope shouldn't be traced. - -The local trace function should return a reference to itself (or to -another function for further tracing in that scope), or \code{None} to -turn off tracing in that scope. - -Instance methods are accepted (and very useful!) as trace functions. - -The events have the following meaning: - -\begin{description} - -\item[\code{'call'}] -A function is called (or some other code block entered). The global -trace function is called; \var{arg} is \code{None}; -the return value specifies the local trace function. - -\item[\code{'line'}] -The interpreter is about to execute a new line of code (sometimes -multiple line events on one line exist). The local trace function is -called; \var{arg} is \code{None}; the return value specifies the new -local trace function. - -\item[\code{'return'}] -A function (or other code block) is about to return. The local trace -function is called; \var{arg} is the value that will be returned. The -trace function's return value is ignored. - -\item[\code{'exception'}] -An exception has occurred. The local trace function is called; -\var{arg} is a triple \code{(\var{exception}, \var{value}, -\var{traceback})}; the return value specifies the new local trace -function. - -\item[\code{'c_call'}] -A C function is about to be called. This may be an extension function -or a builtin. \var{arg} is the C function object. - -\item[\code{'c_return'}] -A C function has returned. \var{arg} is \code{None}. - -\item[\code{'c_exception'}] -A C function has thrown an exception. \var{arg} is \code{None}. - -\end{description} - -Note that as an exception is propagated down the chain of callers, an -\code{'exception'} event is generated at each level. - -For more information on code and frame objects, refer to the -\citetitle[../ref/ref.html]{Python Reference Manual}. |