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 10The :mod:`codeop` module provides utilities upon which the Python 11read-eval-print loop can be emulated, as is done in the :mod:`code` module. As 12a result, you probably don't want to use the module directly; if you want to 13include such a loop in your program you probably want to use the :mod:`code` 14module instead. 15 16There 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 24The :mod:`codeop` module provides a way of doing each of these things, and a way 25of doing them both. 26 27To 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 .. note:: 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 70A note on version compatibility: the :class:`Compile` and 71:class:`CommandCompiler` are new in Python 2.2. If you want to enable the 72future-tracking features of 2.2 but also retain compatibility with 2.1 and 73earlier 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 82which is a low-impact change, but introduces possibly unwanted global state into 83your 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 92and then call ``CommandCompiler`` every time you need a fresh compiler object. 93 94