| 1 |
:mod:`!codeop` --- Compile Python code |
| 2 |
====================================== |
| 3 |
|
| 4 |
.. module:: codeop |
| 5 |
:synopsis: Compile (possibly incomplete) Python code. |
| 6 |
|
| 7 |
.. sectionauthor:: Moshe Zadka <[email protected]> |
| 8 |
.. sectionauthor:: Michael Hudson <[email protected]> |
| 9 |
|
| 10 |
**Source code:** :source:`Lib/codeop.py` |
| 11 |
|
| 12 |
-------------- |
| 13 |
|
| 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 |
|
| 33 |
.. function:: compile_command(source, filename="<input>", symbol="single") |
| 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 |
| 46 |
(``'single'``, the default), as a sequence of :term:`statement` (``'exec'``) or |
| 47 |
as an :term:`expression` (``'eval'``). Any other value will |
| 48 |
cause :exc:`ValueError` to be raised. |
| 49 |
|
| 50 |
.. note:: |
| 51 |
|
| 52 |
It is possible (but not likely) that the parser stops parsing with a |
| 53 |
successful outcome before reaching the end of the source; in this case, |
| 54 |
trailing symbols may be ignored instead of causing an error. For example, |
| 55 |
a backslash followed by two newlines may be followed by arbitrary garbage. |
| 56 |
This will be fixed once the API for the parser is better. |
| 57 |
|
| 58 |
|
| 59 |
.. class:: Compile() |
| 60 |
|
| 61 |
Instances of this class have :meth:`~object.__call__` methods identical in signature to |
| 62 |
the built-in function :func:`compile`, but with the difference that if the |
| 63 |
instance compiles program text containing a :mod:`__future__` statement, the |
| 64 |
instance 'remembers' and compiles all subsequent program texts with the |
| 65 |
statement in force. |
| 66 |
|
| 67 |
|
| 68 |
.. class:: CommandCompiler() |
| 69 |
|
| 70 |
Instances of this class have :meth:`~object.__call__` methods identical in signature to |
| 71 |
:func:`compile_command`; the difference is that if the instance compiles program |
| 72 |
text containing a :mod:`__future__` statement, the instance 'remembers' and |
| 73 |
compiles all subsequent program texts with the statement in force. |