Doc/lib/libcodeop.tex

   1 \section{\module{codeop} ---
   2          Compile Python code}
   3
   4 % LaTeXed from excellent doc-string.
   5
   6 \declaremodule{standard}{codeop}
   7 \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
   8 \sectionauthor{Michael Hudson}{mwh@python.net}
   9 \modulesynopsis{Compile (possibly incomplete) Python code.}
  10
  11 The \module{codeop} module provides utilities upon which the Python
  12 read-eval-print loop can be emulated, as is done in the
  13 \refmodule{code} module.  As a result, you probably don't want to use
  14 the module directly; if you want to include such a loop in your
  15 program you probably want to use the \refmodule{code} module instead.
  16
  17 There are two parts to this job:
  18
  19 \begin{enumerate}
  20   \item Being able to tell if a line of input completes a Python
  21         statement: in short, telling whether to print
  22         `\code{>\code{>}>~} or `\code{...~}' next.
  23   \item Remembering which future statements the user has entered, so
  24         subsequent input can be compiled with these in effect.
  25 \end{enumerate}
  26
  27 The \module{codeop} module provides a way of doing each of these
  28 things, and a way of doing them both.
  29
  30 To do just the former:
  31
  32 \begin{funcdesc}{compile_command}
  33                 {source\optional{, filename\optional{, symbol}}}
  34 Tries to compile \var{source}, which should be a string of Python
  35 code and return a code object if \var{source} is valid
  36 Python code. In that case, the filename attribute of the code object
  37 will be \var{filename}, which defaults to \code{'<input>'}.
  38 Returns \code{None} if \var{source} is \emph{not} valid Python
  39 code, but is a prefix of valid Python code.
  40
  41 If there is a problem with \var{source}, an exception will be raised.
  42 \exception{SyntaxError} is raised if there is invalid Python syntax,
  43 and \exception{OverflowError} or \exception{ValueError} if there is an
  44 invalid literal.
  45
  46 The \var{symbol} argument determines whether \var{source} is compiled
  47 as a statement (\code{'single'}, the default) or as an expression
  48 (\code{'eval'}).  Any other value will cause \exception{ValueError} to
  49 be raised.
  50
  51 \strong{Caveat:}
  52 It is possible (but not likely) that the parser stops parsing
  53 with a successful outcome before reaching the end of the source;
  54 in this case, trailing symbols may be ignored instead of causing an
  55 error.  For example, a backslash followed by two newlines may be
  56 followed by arbitrary garbage.  This will be fixed once the API
  57 for the parser is better.
  58 \end{funcdesc}
  59
  60 \begin{classdesc}{Compile}{}
  61 Instances of this class have \method{__call__()} methods indentical in
  62 signature to the built-in function \function{compile()}, but with the
  63 difference that if the instance compiles program text containing a
  64 \module{__future__} statement, the instance 'remembers' and compiles
  65 all subsequent program texts with the statement in force.
  66 \end{classdesc}
  67
  68 \begin{classdesc}{CommandCompiler}{}
  69 Instances of this class have \method{__call__()} methods identical in
  70 signature to \function{compile_command()}; the difference is that if
  71 the instance compiles program text containing a \code{__future__}
  72 statement, the instance 'remembers' and compiles all subsequent
  73 program texts with the statement in force.
  74 \end{classdesc}
  75
  76 A note on version compatibility: the \class{Compile} and
  77 \class{CommandCompiler} are new in Python 2.2.  If you want to enable
  78 the future-tracking features of 2.2 but also retain compatibility with
  79 2.1 and earlier versions of Python you can either write
  80
  81 \begin{verbatim}
  82 try:
  83     from codeop import CommandCompiler
  84     compile_command = CommandCompiler()
  85     del CommandCompiler
  86 except ImportError:
  87     from codeop import compile_command
  88 \end{verbatim}
  89
  90 which is a low-impact change, but introduces possibly unwanted global
  91 state into your program, or you can write:
  92
  93 \begin{verbatim}
  94 try:
  95     from codeop import CommandCompiler
  96 except ImportError:
  97     def CommandCompiler():
  98         from codeop import compile_command
  99         return compile_comamnd
 100 \end{verbatim}
 101
 102 and then call \code{CommandCompiler} every time you need a fresh
 103 compiler object.