Doc/lib/libcode.tex

   1 \section{\module{code} ---
   2          Interpreter base classes}
   3 \declaremodule{standard}{code}
   4
   5 \modulesynopsis{Base classes for interactive Python interpreters.}
   6
   7
   8 The \code{code} module provides facilities to implement
   9 read-eval-print loops in Python.  Two classes and convenience
  10 functions are included which can be used to build applications which
  11 provide an interactive interpreter prompt.
  12
  13
  14 \begin{classdesc}{InteractiveInterpreter}{\optional{locals}}
  15 This class deals with parsing and interpreter state (the user's
  16 namespace); it does not deal with input buffering or prompting or
  17 input file naming (the filename is always passed in explicitly).
  18 The optional \var{locals} argument specifies the dictionary in
  19 which code will be executed; it defaults to a newly created
  20 dictionary with key \code{'__name__'} set to \code{'__console__'}
  21 and key \code{'__doc__'} set to \code{None}.
  22 \end{classdesc}
  23
  24 \begin{classdesc}{InteractiveConsole}{\optional{locals\optional{, filename}}}
  25 Closely emulate the behavior of the interactive Python interpreter.
  26 This class builds on \class{InteractiveInterpreter} and adds
  27 prompting using the familiar \code{sys.ps1} and \code{sys.ps2}, and
  28 input buffering.
  29 \end{classdesc}
  30
  31
  32 \begin{funcdesc}{interact}{\optional{banner\optional{,
  33                            readfunc\optional{, local}}}}
  34 Convenience function to run a read-eval-print loop.  This creates a
  35 new instance of \class{InteractiveConsole} and sets \var{readfunc}
  36 to be used as the \method{raw_input()} method, if provided.  If
  37 \var{local} is provided, it is passed to the
  38 \class{InteractiveConsole} constructor for use as the default
  39 namespace for the interpreter loop.  The \method{interact()} method
  40 of the instance is then run with \var{banner} passed as the banner
  41 to use, if provided.  The console object is discarded after use.
  42 \end{funcdesc}
  43
  44 \begin{funcdesc}{compile_command}{source\optional{,
  45                                   filename\optional{, symbol}}}
  46 This function is useful for programs that want to emulate Python's
  47 interpreter main loop (a.k.a. the read-eval-print loop).  The tricky
  48 part is to determine when the user has entered an incomplete command
  49 that can be completed by entering more text (as opposed to a
  50 complete command or a syntax error).  This function
  51 \emph{almost} always makes the same decision as the real interpreter
  52 main loop.
  53
  54 \var{source} is the source string; \var{filename} is the optional
  55 filename from which source was read, defaulting to \code{'<input>'};
  56 and \var{symbol} is the optional grammar start symbol, which should
  57 be either \code{'single'} (the default) or \code{'eval'}.
  58
  59 Returns a code object (the same as \code{compile(\var{source},
  60 \var{filename}, \var{symbol})}) if the command is complete and
  61 valid; \code{None} if the command is incomplete; raises
  62 \exception{SyntaxError} if the command is complete and contains a
  63 syntax error, or raises \exception{OverflowError} or
  64 \exception{ValueError} if the command contains an invalid literal.
  65 \end{funcdesc}
  66
  67
  68 \subsection{Interactive Interpreter Objects
  69             \label{interpreter-objects}}
  70
  71 \begin{methoddesc}{runsource}{source\optional{, filename\optional{, symbol}}}
  72 Compile and run some source in the interpreter.
  73 Arguments are the same as for \function{compile_command()}; the
  74 default for \var{filename} is \code{'<input>'}, and for
  75 \var{symbol} is \code{'single'}.  One several things can happen:
  76
  77 \begin{itemize}
  78 \item
  79 The input is incorrect; \function{compile_command()} raised an
  80 exception (\exception{SyntaxError} or \exception{OverflowError}).  A
  81 syntax traceback will be printed by calling the
  82 \method{showsyntaxerror()} method.  \method{runsource()} returns
  83 \code{False}.
  84
  85 \item
  86 The input is incomplete, and more input is required;
  87 \function{compile_command()} returned \code{None}.
  88 \method{runsource()} returns \code{True}.
  89
  90 \item
  91 The input is complete; \function{compile_command()} returned a code
  92 object.  The code is executed by calling the \method{runcode()} (which
  93 also handles run-time exceptions, except for \exception{SystemExit}).
  94 \method{runsource()} returns \code{False}.
  95 \end{itemize}
  96
  97 The return value can be used to decide whether to use
  98 \code{sys.ps1} or \code{sys.ps2} to prompt the next line.
  99 \end{methoddesc}
 100
 101 \begin{methoddesc}{runcode}{code}
 102 Execute a code object.
 103 When an exception occurs, \method{showtraceback()} is called to
 104 display a traceback.  All exceptions are caught except
 105 \exception{SystemExit}, which is allowed to propagate.
 106
 107 A note about \exception{KeyboardInterrupt}: this exception may occur
 108 elsewhere in this code, and may not always be caught.  The caller
 109 should be prepared to deal with it.
 110 \end{methoddesc}
 111
 112 \begin{methoddesc}{showsyntaxerror}{\optional{filename}}
 113 Display the syntax error that just occurred.  This does not display
 114 a stack trace because there isn't one for syntax errors.
 115 If \var{filename} is given, it is stuffed into the exception instead
 116 of the default filename provided by Python's parser, because it
 117 always uses \code{'<string>'} when reading from a string.
 118 The output is written by the \method{write()} method.
 119 \end{methoddesc}
 120
 121 \begin{methoddesc}{showtraceback}{}
 122 Display the exception that just occurred.  We remove the first stack
 123 item because it is within the interpreter object implementation.
 124 The output is written by the \method{write()} method.
 125 \end{methoddesc}
 126
 127 \begin{methoddesc}{write}{data}
 128 Write a string to the standard error stream (\code{sys.stderr}).
 129 Derived classes should override this to provide the appropriate output
 130 handling as needed.
 131 \end{methoddesc}
 132
 133
 134 \subsection{Interactive Console Objects
 135             \label{console-objects}}
 136
 137 The \class{InteractiveConsole} class is a subclass of
 138 \class{InteractiveInterpreter}, and so offers all the methods of the
 139 interpreter objects as well as the following additions.
 140
 141 \begin{methoddesc}{interact}{\optional{banner}}
 142 Closely emulate the interactive Python console.
 143 The optional banner argument specify the banner to print before the
 144 first interaction; by default it prints a banner similar to the one
 145 printed by the standard Python interpreter, followed by the class
 146 name of the console object in parentheses (so as not to confuse this
 147 with the real interpreter -- since it's so close!).
 148 \end{methoddesc}
 149
 150 \begin{methoddesc}{push}{line}
 151 Push a line of source text to the interpreter.
 152 The line should not have a trailing newline; it may have internal
 153 newlines.  The line is appended to a buffer and the interpreter's
 154 \method{runsource()} method is called with the concatenated contents
 155 of the buffer as source.  If this indicates that the command was
 156 executed or invalid, the buffer is reset; otherwise, the command is
 157 incomplete, and the buffer is left as it was after the line was
 158 appended.  The return value is \code{True} if more input is required,
 159 \code{False} if the line was dealt with in some way (this is the same as
 160 \method{runsource()}).
 161 \end{methoddesc}
 162
 163 \begin{methoddesc}{resetbuffer}{}
 164 Remove any unhandled source text from the input buffer.
 165 \end{methoddesc}
 166
 167 \begin{methoddesc}{raw_input}{\optional{prompt}}
 168 Write a prompt and read a line.  The returned line does not include
 169 the trailing newline.  When the user enters the \EOF{} key sequence,
 170 \exception{EOFError} is raised.  The base implementation uses the
 171 built-in function \function{raw_input()}; a subclass may replace this
 172 with a different implementation.
 173 \end{methoddesc}