Debian Codegraph @

Doc/library/codeop.rst

raw
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.