source: trunk/essentials/dev-lang/python/Doc/lib/libcodeop.tex@ 3368

\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.