summaryrefslogtreecommitdiff
path: root/sys/src/cmd/python/Doc/lib/libpdb.tex
diff options
context:
space:
mode:
authorcinap_lenrek <cinap_lenrek@localhost>2011-05-03 11:25:13 +0000
committercinap_lenrek <cinap_lenrek@localhost>2011-05-03 11:25:13 +0000
commit458120dd40db6b4df55a4e96b650e16798ef06a0 (patch)
tree8f82685be24fef97e715c6f5ca4c68d34d5074ee /sys/src/cmd/python/Doc/lib/libpdb.tex
parent3a742c699f6806c1145aea5149bf15de15a0afd7 (diff)
add hg and python
Diffstat (limited to 'sys/src/cmd/python/Doc/lib/libpdb.tex')
-rw-r--r--sys/src/cmd/python/Doc/lib/libpdb.tex456
1 files changed, 456 insertions, 0 deletions
diff --git a/sys/src/cmd/python/Doc/lib/libpdb.tex b/sys/src/cmd/python/Doc/lib/libpdb.tex
new file mode 100644
index 000000000..b252aeb42
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libpdb.tex
@@ -0,0 +1,456 @@
+\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 \keyword{exec} statement or the
+\function{eval()} built-in function.)
+\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[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}.