blob: e4523b6b95412bb671bcefaf8a38e282ff9dc42b [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001
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
Georg Brandl116aa622007-08-15 14:28:22 +000010The :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
Georg Brandl116aa622007-08-15 14:28:22 +000029.. 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
Christian Heimesd8654cf2007-12-02 15:22:16 +000042 (``'single'``, the default) or as an :term:`expression` (``'eval'``). Any
43 other value will cause :exc:`ValueError` to be raised.
Georg Brandl116aa622007-08-15 14:28:22 +000044
Guido van Rossumda27fd22007-08-17 00:24:54 +000045 .. warning::
Georg Brandl48310cd2009-01-03 21:18:54 +000046
Guido van Rossumda27fd22007-08-17 00:24:54 +000047 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.
Georg Brandl116aa622007-08-15 14:28:22 +000052
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.