ref: 2fe3b28f86ed4aa291fb8a620b948abe9c6a1f84
dir: /sys/src/cmd/python/Doc/lib/libcodeop.tex/
\section{\module{codeop} --- Compile Python code} % LaTeXed from excellent doc-string. \declaremodule{standard}{codeop} \sectionauthor{Moshe Zadka}{[email protected]} \sectionauthor{Michael Hudson}{[email protected]} \modulesynopsis{Compile (possibly incomplete) Python code.} The \module{codeop} module provides utilities upon which the Python read-eval-print loop can be emulated, as is done in the \refmodule{code} module. As a result, you probably don't want to use the module directly; if you want to include such a loop in your program you probably want to use the \refmodule{code} module instead. There are two parts to this job: \begin{enumerate} \item Being able to tell if a line of input completes a Python statement: in short, telling whether to print `\code{>>>~}' or `\code{...~}' next. \item Remembering which future statements the user has entered, so subsequent input can be compiled with these in effect. \end{enumerate} The \module{codeop} module provides a way of doing each of these things, and a way of doing them both. To do just the former: \begin{funcdesc}{compile_command} {source\optional{, filename\optional{, symbol}}} Tries to compile \var{source}, which should be a string of Python code and return a code object if \var{source} is valid Python code. In that case, the filename attribute of the code object will be \var{filename}, which defaults to \code{'<input>'}. Returns \code{None} if \var{source} is \emph{not} valid Python code, but is a prefix of valid Python code. If there is a problem with \var{source}, an exception will be raised. \exception{SyntaxError} is raised if there is invalid Python syntax, and \exception{OverflowError} or \exception{ValueError} if there is an invalid literal. The \var{symbol} argument determines whether \var{source} is compiled as a statement (\code{'single'}, the default) or as an expression (\code{'eval'}). Any other value will cause \exception{ValueError} to be raised. \strong{Caveat:} It is possible (but not likely) that the parser stops parsing with a successful outcome before reaching the end of the source; in this case, trailing symbols may be ignored instead of causing an error. For example, a backslash followed by two newlines may be followed by arbitrary garbage. This will be fixed once the API for the parser is better. \end{funcdesc} \begin{classdesc}{Compile}{} Instances of this class have \method{__call__()} methods identical in signature to the built-in function \function{compile()}, but with the difference that if the instance compiles program text containing a \module{__future__} statement, the instance 'remembers' and compiles all subsequent program texts with the statement in force. \end{classdesc} \begin{classdesc}{CommandCompiler}{} Instances of this class have \method{__call__()} methods identical in signature to \function{compile_command()}; the difference is that if the instance compiles program text containing a \code{__future__} statement, the instance 'remembers' and compiles all subsequent program texts with the statement in force. \end{classdesc} A note on version compatibility: the \class{Compile} and \class{CommandCompiler} are new in Python 2.2. If you want to enable the future-tracking features of 2.2 but also retain compatibility with 2.1 and earlier versions of Python you can either write \begin{verbatim} try: from codeop import CommandCompiler compile_command = CommandCompiler() del CommandCompiler except ImportError: from codeop import compile_command \end{verbatim} which is a low-impact change, but introduces possibly unwanted global state into your program, or you can write: \begin{verbatim} try: from codeop import CommandCompiler except ImportError: def CommandCompiler(): from codeop import compile_command return compile_command \end{verbatim} and then call \code{CommandCompiler} every time you need a fresh compiler object.