
``codeop`` --- Compile Python code
**********************************

The ``codeop`` module provides utilities upon which the Python read-
eval-print loop can be emulated, as is done in the ``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 ``code`` module instead.

There are two parts to this job:

1. Being able to tell if a line of input completes a Python
   statement: in short, telling whether to print '``>>>``' or
   '``...``' next.

2. Remembering which future statements the user has entered, so
   subsequent input can be compiled with these in effect.

The ``codeop`` module provides a way of doing each of these things,
and a way of doing them both.

To do just the former:

codeop.compile_command(source[, filename[, symbol]])

   Tries to compile *source*, which should be a string of Python code
   and return a code object if *source* is valid Python code. In that
   case, the filename attribute of the code object will be *filename*,
   which defaults to ``'<input>'``. Returns ``None`` if *source* is
   *not* valid Python code, but is a prefix of valid Python code.

   If there is a problem with *source*, an exception will be raised.
   ``SyntaxError`` is raised if there is invalid Python syntax, and
   ``OverflowError`` or ``ValueError`` if there is an invalid literal.

   The *symbol* argument determines whether *source* is compiled as a
   statement (``'single'``, the default) or as an *expression*
   (``'eval'``).  Any other value will cause ``ValueError`` to  be
   raised.

   Warning: 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.

class codeop.Compile

   Instances of this class have ``__call__()`` methods identical in
   signature to the built-in function ``compile()``, but with the
   difference that if the instance compiles program text containing a
   ``__future__`` statement, the instance 'remembers' and compiles all
   subsequent program texts with the statement in force.

class codeop.CommandCompiler

   Instances of this class have ``__call__()`` methods identical in
   signature to ``compile_command()``; the difference is that if the
   instance compiles program text containing a ``__future__``
   statement, the instance 'remembers' and compiles all subsequent
   program texts with the statement in force.

A note on version compatibility: the ``Compile`` and
``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

   try:
       from codeop import CommandCompiler
       compile_command = CommandCompiler()
       del CommandCompiler
   except ImportError:
       from codeop import compile_command

which is a low-impact change, but introduces possibly unwanted global
state into your program, or you can write:

   try:
       from codeop import CommandCompiler
   except ImportError:
       def CommandCompiler():
           from codeop import compile_command
           return compile_command

and then call ``CommandCompiler`` every time you need a fresh compiler
object.
