diff options
Diffstat (limited to 'Doc/lib/libcode.tex')
| -rw-r--r-- | Doc/lib/libcode.tex | 181 |
1 files changed, 162 insertions, 19 deletions
diff --git a/Doc/lib/libcode.tex b/Doc/lib/libcode.tex index 877b7a4..4b66394 100644 --- a/Doc/lib/libcode.tex +++ b/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. - -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'}. - -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. +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. + +\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'}. + +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} |