Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`codeop` --- Compile Python code |
| 2 | ===================================== |
| 3 | |
| 4 | .. module:: codeop |
| 5 | :synopsis: Compile (possibly incomplete) Python code. |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 6 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il> |
| 8 | .. sectionauthor:: Michael Hudson <mwh@python.net> |
| 9 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 10 | **Source code:** :source:`Lib/codeop.py` |
| 11 | |
| 12 | -------------- |
| 13 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 14 | The :mod:`codeop` module provides utilities upon which the Python |
| 15 | read-eval-print loop can be emulated, as is done in the :mod:`code` module. As |
| 16 | a result, you probably don't want to use the module directly; if you want to |
| 17 | include such a loop in your program you probably want to use the :mod:`code` |
| 18 | module instead. |
| 19 | |
| 20 | There are two parts to this job: |
| 21 | |
| 22 | #. Being able to tell if a line of input completes a Python statement: in |
| 23 | short, telling whether to print '``>>>``' or '``...``' next. |
| 24 | |
| 25 | #. Remembering which future statements the user has entered, so subsequent |
| 26 | input can be compiled with these in effect. |
| 27 | |
| 28 | The :mod:`codeop` module provides a way of doing each of these things, and a way |
| 29 | of doing them both. |
| 30 | |
| 31 | To do just the former: |
| 32 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 33 | .. function:: compile_command(source, filename="<input>", symbol="single") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 34 | |
| 35 | Tries to compile *source*, which should be a string of Python code and return a |
| 36 | code object if *source* is valid Python code. In that case, the filename |
| 37 | attribute of the code object will be *filename*, which defaults to |
| 38 | ``'<input>'``. Returns ``None`` if *source* is *not* valid Python code, but is a |
| 39 | prefix of valid Python code. |
| 40 | |
| 41 | If there is a problem with *source*, an exception will be raised. |
| 42 | :exc:`SyntaxError` is raised if there is invalid Python syntax, and |
| 43 | :exc:`OverflowError` or :exc:`ValueError` if there is an invalid literal. |
| 44 | |
| 45 | The *symbol* argument determines whether *source* is compiled as a statement |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 46 | (``'single'``, the default) or as an :term:`expression` (``'eval'``). Any |
| 47 | other value will cause :exc:`ValueError` to be raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 48 | |
Georg Brandl | e720c0a | 2009-04-27 16:20:50 +0000 | [diff] [blame] | 49 | .. note:: |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 50 | |
Guido van Rossum | da27fd2 | 2007-08-17 00:24:54 +0000 | [diff] [blame] | 51 | It is possible (but not likely) that the parser stops parsing with a |
| 52 | successful outcome before reaching the end of the source; in this case, |
| 53 | trailing symbols may be ignored instead of causing an error. For example, |
| 54 | a backslash followed by two newlines may be followed by arbitrary garbage. |
| 55 | This will be fixed once the API for the parser is better. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 56 | |
| 57 | |
| 58 | .. class:: Compile() |
| 59 | |
| 60 | Instances of this class have :meth:`__call__` methods identical in signature to |
| 61 | the built-in function :func:`compile`, but with the difference that if the |
| 62 | instance compiles program text containing a :mod:`__future__` statement, the |
| 63 | instance 'remembers' and compiles all subsequent program texts with the |
| 64 | statement in force. |
| 65 | |
| 66 | |
| 67 | .. class:: CommandCompiler() |
| 68 | |
| 69 | Instances of this class have :meth:`__call__` methods identical in signature to |
| 70 | :func:`compile_command`; the difference is that if the instance compiles program |
| 71 | text containing a ``__future__`` statement, the instance 'remembers' and |
| 72 | compiles all subsequent program texts with the statement in force. |