diff options
Diffstat (limited to 'Doc/lib/libcode.tex')
| -rw-r--r-- | Doc/lib/libcode.tex | 173 |
1 files changed, 0 insertions, 173 deletions
diff --git a/Doc/lib/libcode.tex b/Doc/lib/libcode.tex deleted file mode 100644 index 8e14b0280d..0000000000 --- a/Doc/lib/libcode.tex +++ /dev/null @@ -1,173 +0,0 @@ -\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} or -\exception{ValueError} if the command contains an invalid literal. -\end{funcdesc} - - -\subsection{Interactive Interpreter Objects - \label{interpreter-objects}} - -\begin{methoddesc}[InteractiveInterpreter]{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{False}. - -\item -The input is incomplete, and more input is required; -\function{compile_command()} returned \code{None}. -\method{runsource()} returns \code{True}. - -\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{False}. -\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}[InteractiveInterpreter]{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}[InteractiveInterpreter]{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}[InteractiveInterpreter]{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}[InteractiveInterpreter]{write}{data} -Write a string to the standard error stream (\code{sys.stderr}). -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}[InteractiveConsole]{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}[InteractiveConsole]{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{True} if more input is required, -\code{False} if the line was dealt with in some way (this is the same as -\method{runsource()}). -\end{methoddesc} - -\begin{methoddesc}[InteractiveConsole]{resetbuffer}{} -Remove any unhandled source text from the input buffer. -\end{methoddesc} - -\begin{methoddesc}[InteractiveConsole]{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 reads from -\code{sys.stdin}; a subclass may replace this -with a different implementation. -\end{methoddesc} |