Mercurial > cpython-lru_cache-weakref

annotate Doc/library/codeop.rst @ 79691:05c8928362ee

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merge __next__ method link fixes with 3.3.
author Ezio Melotti <ezio.melotti@gmail.com>
date Fri, 12 Oct 2012 13:46:37 +0300
parents d143eb624cf5
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 :mod:`codeop` --- Compile Python code
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2 =====================================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
4 .. module:: codeop
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 :synopsis: Compile (possibly incomplete) Python code.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
6 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
7 .. sectionauthor:: Michael Hudson <mwh@python.net>
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
8
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
9 The :mod:`codeop` module provides utilities upon which the Python
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
10 read-eval-print loop can be emulated, as is done in the :mod:`code` module. As
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 a result, you probably don't want to use the module directly; if you want to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 include such a loop in your program you probably want to use the :mod:`code`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
13 module instead.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
14
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
15 There are two parts to this job:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
16
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
17 #. Being able to tell if a line of input completes a Python statement: in
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
18 short, telling whether to print '``>>>``' or '``...``' next.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
19
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 #. Remembering which future statements the user has entered, so subsequent
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
21 input can be compiled with these in effect.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
22
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
23 The :mod:`codeop` module provides a way of doing each of these things, and a way
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
24 of doing them both.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
25
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
26 To do just the former:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
27
53033
6bf426e551d5 Update signature style for optional arguments, part 3.
Georg Brandl <georg@python.org>
parents: 50563
diff changeset
28 .. function:: compile_command(source, filename="<input>", symbol="single")
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
29
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 Tries to compile *source*, which should be a string of Python code and return a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 code object if *source* is valid Python code. In that case, the filename
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
32 attribute of the code object will be *filename*, which defaults to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
33 ``'<input>'``. Returns ``None`` if *source* is *not* valid Python code, but is a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
34 prefix of valid Python code.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
35
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
36 If there is a problem with *source*, an exception will be raised.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
37 :exc:`SyntaxError` is raised if there is invalid Python syntax, and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
38 :exc:`OverflowError` or :exc:`ValueError` if there is an invalid literal.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
39
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
40 The *symbol* argument determines whether *source* is compiled as a statement
44104
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 42630
diff changeset
41 (``'single'``, the default) or as an :term:`expression` (``'eval'``). Any
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 42630
diff changeset
42 other value will cause :exc:`ValueError` to be raised.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
43
53511
11a5452e3305 Merged revisions 72009 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53033
diff changeset
44 .. note::
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 46963
diff changeset
45
42630
20aec9f34598 Manually patched a few things that didn't get merged in, but should.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
46 It is possible (but not likely) that the parser stops parsing with a
20aec9f34598 Manually patched a few things that didn't get merged in, but should.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
47 successful outcome before reaching the end of the source; in this case,
20aec9f34598 Manually patched a few things that didn't get merged in, but should.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
48 trailing symbols may be ignored instead of causing an error. For example,
20aec9f34598 Manually patched a few things that didn't get merged in, but should.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
49 a backslash followed by two newlines may be followed by arbitrary garbage.
20aec9f34598 Manually patched a few things that didn't get merged in, but should.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
50 This will be fixed once the API for the parser is better.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
51
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
52
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
53 .. class:: Compile()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
54
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
55 Instances of this class have :meth:`__call__` methods identical in signature to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
56 the built-in function :func:`compile`, but with the difference that if the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
57 instance compiles program text containing a :mod:`__future__` statement, the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 instance 'remembers' and compiles all subsequent program texts with the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
59 statement in force.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
60
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
61
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 .. class:: CommandCompiler()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
63
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
64 Instances of this class have :meth:`__call__` methods identical in signature to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
65 :func:`compile_command`; the difference is that if the instance compiles program
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
66 text containing a ``__future__`` statement, the instance 'remembers' and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
67 compiles all subsequent program texts with the statement in force.