cpython/Doc/library/codeop.rst

68 lines
2.9 KiB
ReStructuredText
Raw Normal View History

2007-08-15 11:28:22 -03:00
:mod:`codeop` --- Compile Python code
=====================================
.. module:: codeop
:synopsis: Compile (possibly incomplete) Python code.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
.. sectionauthor:: Michael Hudson <mwh@python.net>
The :mod:`codeop` module provides utilities upon which the Python
read-eval-print loop can be emulated, as is done in the :mod:`code` module. As
a result, you probably don't want to use the module directly; if you want to
include such a loop in your program you probably want to use the :mod:`code`
module instead.
There are two parts to this job:
#. Being able to tell if a line of input completes a Python statement: in
short, telling whether to print '``>>>``' or '``...``' next.
#. Remembering which future statements the user has entered, so subsequent
input can be compiled with these in effect.
The :mod:`codeop` module provides a way of doing each of these things, and a way
of doing them both.
To do just the former:
.. function:: compile_command(source, filename="<input>", symbol="single")
2007-08-15 11:28:22 -03:00
Tries to compile *source*, which should be a string of Python code and return a
code object if *source* is valid Python code. In that case, the filename
attribute of the code object will be *filename*, which defaults to
``'<input>'``. Returns ``None`` if *source* is *not* valid Python code, but is a
prefix of valid Python code.
If there is a problem with *source*, an exception will be raised.
:exc:`SyntaxError` is raised if there is invalid Python syntax, and
:exc:`OverflowError` or :exc:`ValueError` if there is an invalid literal.
The *symbol* argument determines whether *source* is compiled as a statement
Merged revisions 59259-59274 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r59260 | lars.gustaebel | 2007-12-01 22:02:12 +0100 (Sat, 01 Dec 2007) | 5 lines Issue #1531: Read fileobj from the current offset, do not seek to the start. (will backport to 2.5) ........ r59262 | georg.brandl | 2007-12-01 23:24:47 +0100 (Sat, 01 Dec 2007) | 4 lines Document PyEval_* functions from ceval.c. Credits to Michael Sloan from GHOP. ........ r59263 | georg.brandl | 2007-12-01 23:27:56 +0100 (Sat, 01 Dec 2007) | 2 lines Add a few refcount data entries. ........ r59264 | georg.brandl | 2007-12-01 23:38:48 +0100 (Sat, 01 Dec 2007) | 4 lines Add test suite for cmd module. Written by Michael Schneider for GHOP. ........ r59265 | georg.brandl | 2007-12-01 23:42:46 +0100 (Sat, 01 Dec 2007) | 3 lines Add examples to the ElementTree documentation. Written by h4wk.cz for GHOP. ........ r59266 | georg.brandl | 2007-12-02 00:12:45 +0100 (Sun, 02 Dec 2007) | 3 lines Add "Using Python on Windows" document, by Robert Lehmann. Written for GHOP. ........ r59271 | georg.brandl | 2007-12-02 15:34:34 +0100 (Sun, 02 Dec 2007) | 3 lines Add example to mmap docs. Written for GHOP by Rafal Rawicki. ........ r59272 | georg.brandl | 2007-12-02 15:37:29 +0100 (Sun, 02 Dec 2007) | 2 lines Convert bdb.rst line endings to Unix style. ........ r59274 | georg.brandl | 2007-12-02 15:58:50 +0100 (Sun, 02 Dec 2007) | 4 lines Add more entries to the glossary. Written by Jeff Wheeler for GHOP. ........
2007-12-02 11:22:16 -04:00
(``'single'``, the default) or as an :term:`expression` (``'eval'``). Any
other value will cause :exc:`ValueError` to be raised.
2007-08-15 11:28:22 -03:00
.. note::
2009-01-03 17:18:54 -04:00
It is possible (but not likely) that the parser stops parsing with a
successful outcome before reaching the end of the source; in this case,
trailing symbols may be ignored instead of causing an error. For example,
a backslash followed by two newlines may be followed by arbitrary garbage.
This will be fixed once the API for the parser is better.
2007-08-15 11:28:22 -03:00
.. class:: Compile()
Instances of this class have :meth:`__call__` methods identical in signature to
the built-in function :func:`compile`, but with the difference that if the
instance compiles program text containing a :mod:`__future__` statement, the
instance 'remembers' and compiles all subsequent program texts with the
statement in force.
.. class:: CommandCompiler()
Instances of this class have :meth:`__call__` methods identical in signature to
:func:`compile_command`; the difference is that if the instance compiles program
text containing a ``__future__`` statement, the instance 'remembers' and
compiles all subsequent program texts with the statement in force.