| \section{\module{code} --- |
| Interpreter base classes} |
| \declaremodule{standard}{code} |
| |
| \modulesynopsis{Base classes for interactive Python interpreters.} |
| |
| |
| 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{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. |
| |
| \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 propagate. |
| |
| 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} |