1 

     2 :mod:`codeop` --- Compile Python code

     3 =====================================

     4 

     5 .. module:: codeop

     6    :synopsis: Compile (possibly incomplete) Python code.

     7 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>

     8 .. sectionauthor:: Michael Hudson <mwh@python.net>

     9 

    10 The :mod:`codeop` module provides utilities upon which the Python

    11 read-eval-print loop can be emulated, as is done in the :mod:`code` module.  As

    12 a result, you probably don't want to use the module directly; if you want to

    13 include such a loop in your program you probably want to use the :mod:`code`

    14 module instead.

    15 

    16 There are two parts to this job:

    17 

    18 #. Being able to tell if a line of input completes a Python  statement: in

    19    short, telling whether to print '``>>>``' or '``...``' next.

    20 

    21 #. Remembering which future statements the user has entered, so  subsequent

    22    input can be compiled with these in effect.

    23 

    24 The :mod:`codeop` module provides a way of doing each of these things, and a way

    25 of doing them both.

    26 

    27 To do just the former:

    28 

    29 .. function:: compile_command(source[, filename[, symbol]])

    30 

    31    Tries to compile *source*, which should be a string of Python code and return a

    32    code object if *source* is valid Python code. In that case, the filename

    33    attribute of the code object will be *filename*, which defaults to

    34    ``'<input>'``. Returns ``None`` if *source* is *not* valid Python code, but is a

    35    prefix of valid Python code.

    36 

    37    If there is a problem with *source*, an exception will be raised.

    38    :exc:`SyntaxError` is raised if there is invalid Python syntax, and

    39    :exc:`OverflowError` or :exc:`ValueError` if there is an invalid literal.

    40 

    41    The *symbol* argument determines whether *source* is compiled as a statement

    42    (``'single'``, the default) or as an :term:`expression` (``'eval'``).  Any

    43    other value will cause :exc:`ValueError` to  be raised.

    44 

    45    .. warning::

    46       

    47       It is possible (but not likely) that the parser stops parsing with a

    48       successful outcome before reaching the end of the source; in this case,

    49       trailing symbols may be ignored instead of causing an error.  For example,

    50       a backslash followed by two newlines may be followed by arbitrary garbage.

    51       This will be fixed once the API for the parser is better.

    52 

    53 

    54 .. class:: Compile()

    55 

    56    Instances of this class have :meth:`__call__` methods identical in signature to

    57    the built-in function :func:`compile`, but with the difference that if the

    58    instance compiles program text containing a :mod:`__future__` statement, the

    59    instance 'remembers' and compiles all subsequent program texts with the

    60    statement in force.

    61 

    62 

    63 .. class:: CommandCompiler()

    64 

    65    Instances of this class have :meth:`__call__` methods identical in signature to

    66    :func:`compile_command`; the difference is that if the instance compiles program

    67    text containing a ``__future__`` statement, the instance 'remembers' and

    68    compiles all subsequent program texts with the statement in force.

    69 

    70 A note on version compatibility: the :class:`Compile` and

    71 :class:`CommandCompiler` are new in Python 2.2.  If you want to enable the

    72 future-tracking features of 2.2 but also retain compatibility with 2.1 and

    73 earlier versions of Python you can either write ::

    74 

    75    try:

    76        from codeop import CommandCompiler

    77        compile_command = CommandCompiler()

    78        del CommandCompiler

    79    except ImportError:

    80        from codeop import compile_command

    81 

    82 which is a low-impact change, but introduces possibly unwanted global state into

    83 your program, or you can write::

    84 

    85    try:

    86        from codeop import CommandCompiler

    87    except ImportError:

    88        def CommandCompiler():

    89            from codeop import compile_command

    90            return compile_command

    91 

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

    93