1 2 :mod:`codeop` --- Compile Python code 3 ===================================== 4 5 .. module:: codeop 6 :synopsis: Compile (possibly incomplete) Python code. 7 .. sectionauthor:: Moshe Zadka <moshez (a] zadka.site.co.il> 8 .. sectionauthor:: Michael Hudson <mwh (a] 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 .. 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 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 94
