Merged changes from the 1.5.2p2 release.

(Very rough.)

Doc/lib/libcode.tex

@@ -1,30 +1,173 @@
 \section{\module{code} ---
-         Code object services.}
+         Interpreter base classes}
 \declaremodule{standard}{code}
 
-\modulesynopsis{Code object services.}
+\modulesynopsis{Base classes for interactive Python interpreters.}
 
 
-The \code{code} module defines operations pertaining to Python code
-objects.  It defines the following function:
+The \code{code} module provides facilities to implement
+read-eval-print loops in Python.  Two classes and convenience
+functions are included which can be used to build applications which
+provide an interactive interpreter prompt.
 
 
-\begin{funcdesc}{compile_command}{source, \optional{filename\optional{, symbol}}}
+\begin{classdesc}{InteractiveInterpreter}{\optional{locals}}
+This class deals with parsing and interpreter state (the user's
+namespace); it does not deal with input buffering or prompting or
+input file naming (the filename is always passed in explicitly).
+The optional \var{locals} argument specifies the dictionary in
+which code will be executed; it defaults to a newly created
+dictionary with key \code{'__name__'} set to \code{'__console__'}
+and key \code{'__doc__'} set to \code{None}.
+\end{classdesc}
+
+\begin{classdesc}{InteractiveConsole}{\optional{locals\optional{, filename}}}
+Closely emulate the behavior of the interactive Python interpreter.
+This class builds on \class{InteractiveInterpreter} and adds
+prompting using the familiar \code{sys.ps1} and \code{sys.ps2}, and
+input buffering.
+\end{classdesc}
+
+
+\begin{funcdesc}{interact}{\optional{banner\optional{,
+                           readfunc\optional{, local}}}}
+Convenience function to run a read-eval-print loop.  This creates a
+new instance of \class{InteractiveConsole} and sets \var{readfunc}
+to be used as the \method{raw_input()} method, if provided.  If
+\var{local} is provided, it is passed to the
+\class{InteractiveConsole} constructor for use as the default
+namespace for the interpreter loop.  The \method{interact()} method
+of the instance is then run with \var{banner} passed as the banner
+to use, if provided.  The console object is discarded after use.
+\end{funcdesc}
+
+\begin{funcdesc}{compile_command}{source\optional{,
+                                  filename\optional{, symbol}}}
 This function is useful for programs that want to emulate Python's
 interpreter main loop (a.k.a. the read-eval-print loop).  The tricky
 part is to determine when the user has entered an incomplete command
-that can be completed by entering more text (as opposed to a complete
-command or a syntax error).  This function \emph{almost} always makes
-the same decision as the real interpreter main loop.
+that can be completed by entering more text (as opposed to a
+complete command or a syntax error).  This function
+\emph{almost} always makes the same decision as the real interpreter
+main loop.
 
-Arguments: \var{source} is the source string; \var{filename} is the
-optional filename from which source was read, defaulting to
-\code{'<input>'}; and \var{symbol} is the optional grammar start
-symbol, which should be either \code{'single'} (the default) or
-\code{'eval'}.
+\var{source} is the source string; \var{filename} is the optional
+filename from which source was read, defaulting to \code{'<input>'};
+and \var{symbol} is the optional grammar start symbol, which should
+be either \code{'single'} (the default) or \code{'eval'}.
 
-Return a code object (the same as \code{compile(\var{source},
-\var{filename}, \var{symbol})}) if the command is complete and valid;
-return \code{None} if the command is incomplete; raise
-\exception{SyntaxError} if the command is a syntax error.
+Returns a code object (the same as \code{compile(\var{source},
+\var{filename}, \var{symbol})}) if the command is complete and
+valid; \code{None} if the command is incomplete; raises
+\exception{SyntaxError} if the command is complete and contains a
+syntax error, or raises \exception{OverflowError} if the command
+includes a numeric constant which exceeds the range of the
+appropriate numeric type.
 \end{funcdesc}
+
+
+\subsection{Interactive Interpreter Objects
+            \label{interpreter-objects}}
+
+\begin{methoddesc}{runsource}{source\optional{, filename\optional{, symbol}}}
+Compile and run some source in the interpreter.
+Arguments are the same as for \function{compile_command()}; the
+default for \var{filename} is \code{'<input>'}, and for
+\var{symbol} is \code{'single'}.  One several things can happen:
+
+\begin{itemize}
+\item
+The input is incorrect; \function{compile_command()} raised an
+exception (\exception{SyntaxError} or \exception{OverflowError}).  A
+syntax traceback will be printed by calling the
+\method{showsyntaxerror()} method.  \method{runsource()} returns
+\code{0}.
+
+\item
+The input is incomplete, and more input is required;
+\function{compile_command()} returned \code{None}.
+\method{runsource()} returns \code{1}.
+
+\item
+The input is complete; \function{compile_command()} returned a code
+object.  The code is executed by calling the \method{runcode()} (which
+also handles run-time exceptions, except for \exception{SystemExit}).
+\method{runsource()} returns \code{0}.
+\end{itemize}
+
+The return value can be used to decide whether to use
+\code{sys.ps1} or \code{sys.ps2} to prompt the next line.
+\end{methoddesc}
+
+\begin{methoddesc}{runcode}{code}
+Execute a code object.
+When an exception occurs, \method{showtraceback()} is called to
+display a traceback.  All exceptions are caught except
+\exception{SystemExit}, which is allowed to propogate.
+
+A note about \exception{KeyboardInterrupt}: this exception may occur
+elsewhere in this code, and may not always be caught.  The caller
+should be prepared to deal with it.
+\end{methoddesc}
+
+\begin{methoddesc}{showsyntaxerror}{\optional{filename}}
+Display the syntax error that just occurred.  This does not display
+a stack trace because there isn't one for syntax errors.
+If \var{filename} is given, it is stuffed into the exception instead
+of the default filename provided by Python's parser, because it
+always uses \code{'<string>'} when reading from a string.
+The output is written by the \method{write()} method.
+\end{methoddesc}
+
+\begin{methoddesc}{showtraceback}{}
+Display the exception that just occurred.  We remove the first stack
+item because it is within the interpreter object implementation.
+The output is written by the \method{write()} method.
+\end{methoddesc}
+
+\begin{methoddesc}{write}{data}
+Write a string to standard output.  Derived classes should override
+this to provide the appropriate output handling as needed.
+\end{methoddesc}
+
+
+\subsection{Interactive Console Objects
+            \label{console-objects}}
+
+The \class{InteractiveConsole} class is a subclass of
+\class{InteractiveInterpreter}, and so offers all the methods of the
+interpreter objects as well as the following additions.
+
+\begin{methoddesc}{interact}{\optional{banner}}
+Closely emulate the interactive Python console.
+The optional banner argument specify the banner to print before the
+first interaction; by default it prints a banner similar to the one
+printed by the standard Python interpreter, followed by the class
+name of the console object in parentheses (so as not to confuse this
+with the real interpreter -- since it's so close!).
+\end{methoddesc}
+
+\begin{methoddesc}{push}{line}
+Push a line of source text to the interpreter.
+The line should not have a trailing newline; it may have internal
+newlines.  The line is appended to a buffer and the interpreter's
+\method{runsource()} method is called with the concatenated contents
+of the buffer as source.  If this indicates that the command was
+executed or invalid, the buffer is reset; otherwise, the command is
+incomplete, and the buffer is left as it was after the line was
+appended.  The return value is \code{1} if more input is required,
+\code{0} if the line was dealt with in some way (this is the same as
+\method{runsource()}).
+\end{methoddesc}
+
+\begin{methoddesc}{resetbuffer}{}
+Remove any unhandled source text from the input buffer.
+\end{methoddesc}
+
+\begin{methoddesc}{raw_input}{\optional{prompt}}
+Write a prompt and read a line.  The returned line does not include
+the trailing newline.  When the user enters the \EOF{} key sequence,
+\exception{EOFError} is raised.  The base implementation uses the
+built-in function \function{raw_input()}; a subclass may replace this
+with a different implementation.
+\end{methoddesc}