From dc46c7f7346ba2f70dc011e8a38287e80dc5cb63 Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Wed, 1 Mar 1995 15:38:16 +0000 Subject: small nits and new files --- Doc/Makefile | 8 +- Doc/lib.tex | 8 ++ Doc/lib/lib.tex | 8 ++ Doc/lib/libhtmllib.tex | 2 +- Doc/lib/libpdb.tex | 210 +++++++++++++++++++++++++++++++++++++++++++++++ Doc/lib/libtemplate.tex | 3 +- Doc/lib/libtypes2.tex | 4 +- Doc/libhtmllib.tex | 2 +- Doc/libmac.tex | 4 - Doc/libpdb.tex | 210 +++++++++++++++++++++++++++++++++++++++++++++++ Doc/libtemplate.tex | 3 +- Doc/libtypes2.tex | 4 +- Doc/mac/libmac.tex | 4 - Doc/templates/module.tex | 3 +- 14 files changed, 455 insertions(+), 18 deletions(-) create mode 100644 Doc/lib/libpdb.tex create mode 100644 Doc/libpdb.tex diff --git a/Doc/Makefile b/Doc/Makefile index a717fc2..95ff674 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -32,7 +32,7 @@ ref.dvi: ref.tex ref1.tex ref2.tex ref3.tex ref4.tex ref5.tex ref6.tex \ LIBFILES = lib.tex \ libal.tex libaifc.tex libamoeba.tex libarray.tex libaudio.tex libaudioop.tex \ libbltin.tex \ -libcgi.tex libcopy.tex libcrypto.tex \ +libcgi.tex libcopy.tex libctb.tex libcrypto.tex \ libdbm.tex \ libexcs.tex \ libfcntl.tex libfl.tex libfm.tex libftplib.tex libfuncs.tex \ @@ -40,7 +40,8 @@ libgdbm.tex libgetopt.tex libgl.tex libgopherlib.tex libgrp.tex \ libhtmllib.tex libhttplib.tex \ libimageop.tex libimgfile.tex libintro.tex \ libjpeg.tex \ -libmac.tex libmain.tex libmarshal.tex libmath.tex \ +libmac.tex libmacconsole.tex libmacfs.tex libmactcp.tex libmacspeech.tex \ + libmain.tex libmarshal.tex libmath.tex \ libmd5.tex libmimetools.tex libmm.tex libmods.tex libmpz.tex \ libnntplib.tex \ libobjs.tex libos.tex \ @@ -51,7 +52,8 @@ librand.tex libregex.tex libregsub.tex \ libselect.tex libsgi.tex libsgmllib.tex \ libshelve.tex libsocket.tex libstd.tex libstdwin.tex \ libstring.tex libstruct.tex libsun.tex libsys.tex \ -libthread.tex libtime.tex libtypes.tex libtypes2.tex \ +libtempfile.tex libthread.tex libtime.tex \ + libtraceback.tex libtypes.tex libtypes2.tex \ libunix.tex liburllib.tex liburlparse.tex \ libwhrandom.tex libwww.tex diff --git a/Doc/lib.tex b/Doc/lib.tex index 873e8fb..aa1846e 100644 --- a/Doc/lib.tex +++ b/Doc/lib.tex @@ -75,6 +75,9 @@ language. \input{libshelve} \input{libcopy} \input{libtypes2} % types is already taken :-( +\input{libtempfile} +\input{libtraceback} +\input{libpdb} \input{libunix} % UNIX ONLY \input{libdbm} @@ -117,6 +120,11 @@ language. %\input{libamoeba} % AMOEBA ONLY \input{libmac} % MACINTOSH ONLY +\input{libctb} +\input{libmacconsole} +\input{libmacfs} +\input{libmactcp} +\input{libmacspeech} \input{libstdwin} % STDWIN ONLY diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 873e8fb..aa1846e 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -75,6 +75,9 @@ language. \input{libshelve} \input{libcopy} \input{libtypes2} % types is already taken :-( +\input{libtempfile} +\input{libtraceback} +\input{libpdb} \input{libunix} % UNIX ONLY \input{libdbm} @@ -117,6 +120,11 @@ language. %\input{libamoeba} % AMOEBA ONLY \input{libmac} % MACINTOSH ONLY +\input{libctb} +\input{libmacconsole} +\input{libmacfs} +\input{libmactcp} +\input{libmacspeech} \input{libstdwin} % STDWIN ONLY diff --git a/Doc/lib/libhtmllib.tex b/Doc/lib/libhtmllib.tex index e192774..75fd994 100644 --- a/Doc/lib/libhtmllib.tex +++ b/Doc/lib/libhtmllib.tex @@ -135,7 +135,7 @@ string. Anchors with neither a \code{HREF} not a \code{NAME} attribute are not entered in these lists at all. The module also defines a number of style sheet classes. These should -never be instantiated --- their class variables are the only behaviour +never be instantiated --- their class variables are the only behavior required. Note that style sheets are specifically designed for a particular formatter implementation. The currently defined style sheets are: diff --git a/Doc/lib/libpdb.tex b/Doc/lib/libpdb.tex new file mode 100644 index 0000000..e393118 --- /dev/null +++ b/Doc/lib/libpdb.tex @@ -0,0 +1,210 @@ +\section{Standard module \sectcode{pdb}} +\stmodindex{pdb} +\index{debugging} + +This module defines an interactive source code debugger for Python +programs. It supports 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 a class +\code{Pdb}. The extension interface uses the (also undocumented) +modules \code{bdb} and \code{cmd}; it is currently undocumented. +\ttindex{Pdb} +\ttindex{bdb} +\ttindex{cmd} + +A primitive windowing version of the debugger also exists --- this is +module \code{wdb}, which requires STDWIN. +\index{stdwin} +\ttindex{wdb} + +Typical usage to run a program under control of the debugger is: + +\begin{verbatim} +>>> import pdb +>>> import mymodule +>>> pdb.run('mymodule.test()') +(Pdb) +\end{verbatim} + +Typical usage to inspect a crashed program is: + +\begin{verbatim} +>>> import pdb +>>> import mymodule +>>> mymodule.test() +(crashes with a stack trace) +>>> pdb.pm() +(Pdb) +\end{verbatim} + +The debugger's prompt is ``\code{(Pdb) }''. + +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} (which should be a string) under debugger +control. The debugger prompt appears before any code is executed; you +can set breakpoint and type \code{continue}, or you can step through +the statement using \code{step} or \code{next}. The optional +\var{globals} and \var{locals} arguments specify the environment in +which the code is executed; by default the dictionary of the module +\code{__main__} is used. (See the explanation of the \code{exec} +statement or the \code{eval()} built-in function.) +\end{funcdesc} + +\begin{funcdesc}{runeval}{expression\optional{\, globals\optional{\, locals}}} +Evaluate the \var{expression} (which should be a string) under +debugger control. When \code{runeval()} returns, it returns the value +of the expression. Otherwise this function is similar to +\code{run()}. +\end{funcdesc} + +\begin{funcdesc}{runcall}{function\optional{\, argument\, ...}} +Call the \var{function} (which should be a callable Python object, not +a string) with the given arguments. When \code{runcall()} returns, it +returns the return value of the function call. 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 code, even if the code is +not otherwise being debugged. +\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 based on the traceback found in +\code{sys.last_traceback}. +\end{funcdesc} + +\subsection{Debugger Commands} + +The debugger recognizes the following commands. Most commands can be +abbreviated to one or two letters; e.g. ``\code{h(elp)}'' means that +either ``\code{h}'' or ``\code{help}'' can be used to enter the help +command (but not ``\code{he}'' or ``\code{hel}'', nor ``\code{H}'' or +``\code{Help} or ``\code{HELP}''). Arguments to commands must be +separated by whitespace (spaces or tabs). Optional arguments are +enclosed in square brackets (``\code{[]}'')in the command syntax; the +square brackets must not be typed. Alternatives in the command syntax +are separated by a vertical bar (``\code{|}''). + +Entering a blank line repeats the last command entered. Exception: if +the last command was a ``\code{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 (``\code{!}''). This is a powerful way to inspect the program +being debugged; it is even possible to change variables. When an +exception occurs in such a statement, the exception name is printed +but the debugger's state is not changed. + +\begin{description} + +\item[{h(elp) [\var{command}]}] + +Without argument, print the list of available commands. +With a \var{command} as argument, print help about that command. +``\code{help pdb}'' displays the full documentation file; if the +environment variable \code{PAGER} is defined, the file is piped +through that command instead. Since the var{command} argument must be +an identifier, ``\code{help exec}'' gives help on the ``\code{!}'' +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 an older frame). + +\item[{u(p)}] + +Move the current frame one level up in the stack trace +(to a newer frame). + +\item[{b(reak) [\var{lineno} \code{|} \var{function}]}] + +With a \var{lineno} argument, set a break there in the current +file. With a \var{function} argument, set a break at the entry of +that function. Without argument, list all breaks. + +\item[{cl(ear) [lineno]}] + +With a \var{lineno} argument, clear that break in the current file. +Without argument, clear all breaks (but first ask confirmation). + +\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 \code{next} and +\code{step} is that \code{step} stops inside a called function, while +\code{next} executes called functions at 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[{l(ist) [\var{first} [, \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 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. + +\item[{[!] \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 ``\code{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} diff --git a/Doc/lib/libtemplate.tex b/Doc/lib/libtemplate.tex index 5c702e5..a7f70ae 100644 --- a/Doc/lib/libtemplate.tex +++ b/Doc/lib/libtemplate.tex @@ -37,7 +37,8 @@ only available on genuine UNIX systems. The \code{spam} module defines the following functions: % ---- 3.1. ---- -% Redefine the ``indexsubitem'' macro to point to this module: +% Redefine the ``indexsubitem'' macro to point to this module +% (alternatively, you can put this at the top of the file): \renewcommand{\indexsubitem}{(in module spam)} diff --git a/Doc/lib/libtypes2.tex b/Doc/lib/libtypes2.tex index 7c51bb9..2280ed7 100644 --- a/Doc/lib/libtypes2.tex +++ b/Doc/lib/libtypes2.tex @@ -1,9 +1,11 @@ \section{Built-in module \sectcode{types}} \stmodindex{types} +\renewcommand{\indexsubitem}{(in module types)} + This module defines names for all object types that are used by the standard Python interpreter (but not for the types defined by various -extension modules). It is safe to use \code{from types import *} --- +extension modules). It is safe to use ``\code{from types import *}'' --- the module does not export any other names besides the ones listed here. New names exported by future versions of this module will all end in \code{Type}. diff --git a/Doc/libhtmllib.tex b/Doc/libhtmllib.tex index e192774..75fd994 100644 --- a/Doc/libhtmllib.tex +++ b/Doc/libhtmllib.tex @@ -135,7 +135,7 @@ string. Anchors with neither a \code{HREF} not a \code{NAME} attribute are not entered in these lists at all. The module also defines a number of style sheet classes. These should -never be instantiated --- their class variables are the only behaviour +never be instantiated --- their class variables are the only behavior required. Note that style sheets are specifically designed for a particular formatter implementation. The currently defined style sheets are: diff --git a/Doc/libmac.tex b/Doc/libmac.tex index 9a6ccd9..62babda 100644 --- a/Doc/libmac.tex +++ b/Doc/libmac.tex @@ -38,7 +38,3 @@ The following functions are available in this module: \code{isdir}, \code{isfile}, \code{exists}. - -\input{libmacconsole} -\input{libmacfs} -\input{libmacspeech} diff --git a/Doc/libpdb.tex b/Doc/libpdb.tex new file mode 100644 index 0000000..e393118 --- /dev/null +++ b/Doc/libpdb.tex @@ -0,0 +1,210 @@ +\section{Standard module \sectcode{pdb}} +\stmodindex{pdb} +\index{debugging} + +This module defines an interactive source code debugger for Python +programs. It supports 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 a class +\code{Pdb}. The extension interface uses the (also undocumented) +modules \code{bdb} and \code{cmd}; it is currently undocumented. +\ttindex{Pdb} +\ttindex{bdb} +\ttindex{cmd} + +A primitive windowing version of the debugger also exists --- this is +module \code{wdb}, which requires STDWIN. +\index{stdwin} +\ttindex{wdb} + +Typical usage to run a program under control of the debugger is: + +\begin{verbatim} +>>> import pdb +>>> import mymodule +>>> pdb.run('mymodule.test()') +(Pdb) +\end{verbatim} + +Typical usage to inspect a crashed program is: + +\begin{verbatim} +>>> import pdb +>>> import mymodule +>>> mymodule.test() +(crashes with a stack trace) +>>> pdb.pm() +(Pdb) +\end{verbatim} + +The debugger's prompt is ``\code{(Pdb) }''. + +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} (which should be a string) under debugger +control. The debugger prompt appears before any code is executed; you +can set breakpoint and type \code{continue}, or you can step through +the statement using \code{step} or \code{next}. The optional +\var{globals} and \var{locals} arguments specify the environment in +which the code is executed; by default the dictionary of the module +\code{__main__} is used. (See the explanation of the \code{exec} +statement or the \code{eval()} built-in function.) +\end{funcdesc} + +\begin{funcdesc}{runeval}{expression\optional{\, globals\optional{\, locals}}} +Evaluate the \var{expression} (which should be a string) under +debugger control. When \code{runeval()} returns, it returns the value +of the expression. Otherwise this function is similar to +\code{run()}. +\end{funcdesc} + +\begin{funcdesc}{runcall}{function\optional{\, argument\, ...}} +Call the \var{function} (which should be a callable Python object, not +a string) with the given arguments. When \code{runcall()} returns, it +returns the return value of the function call. 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 code, even if the code is +not otherwise being debugged. +\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 based on the traceback found in +\code{sys.last_traceback}. +\end{funcdesc} + +\subsection{Debugger Commands} + +The debugger recognizes the following commands. Most commands can be +abbreviated to one or two letters; e.g. ``\code{h(elp)}'' means that +either ``\code{h}'' or ``\code{help}'' can be used to enter the help +command (but not ``\code{he}'' or ``\code{hel}'', nor ``\code{H}'' or +``\code{Help} or ``\code{HELP}''). Arguments to commands must be +separated by whitespace (spaces or tabs). Optional arguments are +enclosed in square brackets (``\code{[]}'')in the command syntax; the +square brackets must not be typed. Alternatives in the command syntax +are separated by a vertical bar (``\code{|}''). + +Entering a blank line repeats the last command entered. Exception: if +the last command was a ``\code{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 (``\code{!}''). This is a powerful way to inspect the program +being debugged; it is even possible to change variables. When an +exception occurs in such a statement, the exception name is printed +but the debugger's state is not changed. + +\begin{description} + +\item[{h(elp) [\var{command}]}] + +Without argument, print the list of available commands. +With a \var{command} as argument, print help about that command. +``\code{help pdb}'' displays the full documentation file; if the +environment variable \code{PAGER} is defined, the file is piped +through that command instead. Since the var{command} argument must be +an identifier, ``\code{help exec}'' gives help on the ``\code{!}'' +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 an older frame). + +\item[{u(p)}] + +Move the current frame one level up in the stack trace +(to a newer frame). + +\item[{b(reak) [\var{lineno} \code{|} \var{function}]}] + +With a \var{lineno} argument, set a break there in the current +file. With a \var{function} argument, set a break at the entry of +that function. Without argument, list all breaks. + +\item[{cl(ear) [lineno]}] + +With a \var{lineno} argument, clear that break in the current file. +Without argument, clear all breaks (but first ask confirmation). + +\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 \code{next} and +\code{step} is that \code{step} stops inside a called function, while +\code{next} executes called functions at 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[{l(ist) [\var{first} [, \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 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. + +\item[{[!] \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 ``\code{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} diff --git a/Doc/libtemplate.tex b/Doc/libtemplate.tex index 5c702e5..a7f70ae 100644 --- a/Doc/libtemplate.tex +++ b/Doc/libtemplate.tex @@ -37,7 +37,8 @@ only available on genuine UNIX systems. The \code{spam} module defines the following functions: % ---- 3.1. ---- -% Redefine the ``indexsubitem'' macro to point to this module: +% Redefine the ``indexsubitem'' macro to point to this module +% (alternatively, you can put this at the top of the file): \renewcommand{\indexsubitem}{(in module spam)} diff --git a/Doc/libtypes2.tex b/Doc/libtypes2.tex index 7c51bb9..2280ed7 100644 --- a/Doc/libtypes2.tex +++ b/Doc/libtypes2.tex @@ -1,9 +1,11 @@ \section{Built-in module \sectcode{types}} \stmodindex{types} +\renewcommand{\indexsubitem}{(in module types)} + This module defines names for all object types that are used by the standard Python interpreter (but not for the types defined by various -extension modules). It is safe to use \code{from types import *} --- +extension modules). It is safe to use ``\code{from types import *}'' --- the module does not export any other names besides the ones listed here. New names exported by future versions of this module will all end in \code{Type}. diff --git a/Doc/mac/libmac.tex b/Doc/mac/libmac.tex index 9a6ccd9..62babda 100644 --- a/Doc/mac/libmac.tex +++ b/Doc/mac/libmac.tex @@ -38,7 +38,3 @@ The following functions are available in this module: \code{isdir}, \code{isfile}, \code{exists}. - -\input{libmacconsole} -\input{libmacfs} -\input{libmacspeech} diff --git a/Doc/templates/module.tex b/Doc/templates/module.tex index 5c702e5..a7f70ae 100644 --- a/Doc/templates/module.tex +++ b/Doc/templates/module.tex @@ -37,7 +37,8 @@ only available on genuine UNIX systems. The \code{spam} module defines the following functions: % ---- 3.1. ---- -% Redefine the ``indexsubitem'' macro to point to this module: +% Redefine the ``indexsubitem'' macro to point to this module +% (alternatively, you can put this at the top of the file): \renewcommand{\indexsubitem}{(in module spam)} -- cgit v0.12