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}{mzadka@geocities.com}
   8 \modulesynopsis{Compile (possibly incomplete) Python code.}
   9
  10 The \module{codeop} module provides a function to compile Python code
  11 with hints on whether it is certainly complete, possibly complete or
  12 definitely incomplete.  This is used by the \refmodule{code} module
  13 and should not normally be used directly.
  14
  15 The \module{codeop} module defines the following function:
  16
  17 \begin{funcdesc}{compile_command}
  18                 {source\optional{, filename\optional{, symbol}}}
  19 Tries to compile \var{source}, which should be a string of Python
  20 code and return a code object if \var{source} is valid
  21 Python code. In that case, the filename attribute of the code object
  22 will be \var{filename}, which defaults to \code{'<input>'}.
  23 Returns \code{None} if \var{source} is \emph{not} valid Python
  24 code, but is a prefix of valid Python code.
  25
  26 If there is a problem with \var{source}, an exception will be raised.
  27 \exception{SyntaxError} is raised if there is invalid Python syntax,
  28 and \exception{OverflowError} if there is an invalid numeric
  29 constant.
  30
  31 The \var{symbol} argument determines whether \var{source} is compiled
  32 as a statement (\code{'single'}, the default) or as an expression
  33 (\code{'eval'}).  Any other value will cause \exception{ValueError} to
  34 be raised.
  35
  36 \strong{Caveat:}
  37 It is possible (but not likely) that the parser stops parsing
  38 with a successful outcome before reaching the end of the source;
  39 in this case, trailing symbols may be ignored instead of causing an
  40 error.  For example, a backslash followed by two newlines may be
  41 followed by arbitrary garbage.  This will be fixed once the API
  42 for the parser is better.
  43 \end{funcdesc}