mirror of
https://github.com/python/cpython.git
synced 2025-10-31 05:31:20 +00:00
103 lines
3.9 KiB
TeX
103 lines
3.9 KiB
TeX
\section{\module{codeop} ---
|
|
Compile Python code}
|
|
|
|
% LaTeXed from excellent doc-string.
|
|
|
|
\declaremodule{standard}{codeop}
|
|
\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
|
|
\sectionauthor{Michael Hudson}{mwh@python.net}
|
|
\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{>\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 indentical 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.
|