PageRenderTime 82ms CodeModel.GetById 40ms app.highlight 4ms RepoModel.GetById 36ms app.codeStats 0ms

ReStructuredText | 93 lines | 67 code | 26 blank | 0 comment | 0 complexity | bc4c06ff93c7e7a50768a6fe19ac9bcc MD5 | raw file
 2:mod:`codeop` --- Compile Python code
 5.. module:: codeop
 6   :synopsis: Compile (possibly incomplete) Python code.
 7.. sectionauthor:: Moshe Zadka <>
 8.. sectionauthor:: Michael Hudson <>
10The :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.
16There are two parts to this job:
18#. Being able to tell if a line of input completes a Python  statement: in
19   short, telling whether to print '``>>>``' or '``...``' next.
21#. Remembering which future statements the user has entered, so  subsequent
22   input can be compiled with these in effect.
24The :mod:`codeop` module provides a way of doing each of these things, and a way
25of doing them both.
27To do just the former:
29.. function:: compile_command(source[, filename[, symbol]])
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.
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.
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.
45   .. note::
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.
54.. class:: Compile()
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.
63.. class:: CommandCompiler()
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.
70A note on version compatibility: the :class:`Compile` and
71:class:`CommandCompiler` are new in Python 2.2.  If you want to enable the
72future-tracking features of 2.2 but also retain compatibility with 2.1 and
73earlier versions of Python you can either write ::
75   try:
76       from codeop import CommandCompiler
77       compile_command = CommandCompiler()
78       del CommandCompiler
79   except ImportError:
80       from codeop import compile_command
82which is a low-impact change, but introduces possibly unwanted global state into
83your program, or you can write::
85   try:
86       from codeop import CommandCompiler
87   except ImportError:
88       def CommandCompiler():
89           from codeop import compile_command
90           return compile_command
92and then call ``CommandCompiler`` every time you need a fresh compiler object.