:mod:`codeop` --- Compile Python code ===================================== .. module:: codeop :synopsis: Compile (possibly incomplete) Python code. .. sectionauthor:: Moshe Zadka .. sectionauthor:: Michael Hudson The :mod:`codeop` module provides utilities upon which the Python read-eval-print loop can be emulated, as is done in the :mod:`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 :mod:`code` module instead. There are two parts to this job: #. Being able to tell if a line of input completes a Python statement: in short, telling whether to print '``>>>``' or '``...``' next. #. Remembering which future statements the user has entered, so subsequent input can be compiled with these in effect. The :mod:`codeop` module provides a way of doing each of these things, and a way of doing them both. To do just the former: .. function:: 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 ``''``. 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. :exc:`SyntaxError` is raised if there is invalid Python syntax, and :exc:`OverflowError` or :exc:`ValueError` if there is an invalid literal. The *symbol* argument determines whether *source* is compiled as a statement (``'single'``, the default) or as an :term:`expression` (``'eval'``). Any other value will cause :exc:`ValueError` to be raised. .. note:: 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:: Compile() Instances of this class have :meth:`__call__` methods identical in signature to the built-in function :func:`compile`, but with the difference that if the instance compiles program text containing a :mod:`__future__` statement, the instance 'remembers' and compiles all subsequent program texts with the statement in force. .. class:: CommandCompiler() Instances of this class have :meth:`__call__` methods identical in signature to :func:`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 :class:`Compile` and :class:`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.