Doc/library/codeop.rst

   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