linuxport: Merging in the fruits of my labors (Python VFS)
[xbmc:xbmc-antiquated.git] / xbmc / lib / libPython / Python / Doc / lib / libcodeop.tex
1 \section{\module{codeop} ---
2          Compile Python code}
3
4 % LaTeXed from excellent doc-string.
5
6 \declaremodule{standard}{codeop}
7 \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
8 \sectionauthor{Michael Hudson}{mwh@python.net}
9 \modulesynopsis{Compile (possibly incomplete) Python code.}
10
11 The \module{codeop} module provides utilities upon which the Python
12 read-eval-print loop can be emulated, as is done in the
13 \refmodule{code} module.  As a result, you probably don't want to use
14 the module directly; if you want to include such a loop in your
15 program you probably want to use the \refmodule{code} module instead.
16
17 There are two parts to this job: 
18
19 \begin{enumerate}
20   \item Being able to tell if a line of input completes a Python 
21         statement: in short, telling whether to print
22         `\code{>\code{>}>~}' or `\code{...~}' next.
23   \item Remembering which future statements the user has entered, so 
24         subsequent input can be compiled with these in effect.
25 \end{enumerate}
26
27 The \module{codeop} module provides a way of doing each of these
28 things, and a way of doing them both.
29
30 To do just the former:
31
32 \begin{funcdesc}{compile_command}
33                 {source\optional{, filename\optional{, symbol}}}
34 Tries to compile \var{source}, which should be a string of Python
35 code and return a code object if \var{source} is valid
36 Python code. In that case, the filename attribute of the code object
37 will be \var{filename}, which defaults to \code{'<input>'}.
38 Returns \code{None} if \var{source} is \emph{not} valid Python
39 code, but is a prefix of valid Python code.
40
41 If there is a problem with \var{source}, an exception will be raised.
42 \exception{SyntaxError} is raised if there is invalid Python syntax,
43 and \exception{OverflowError} or \exception{ValueError} if there is an
44 invalid literal.
45
46 The \var{symbol} argument determines whether \var{source} is compiled
47 as a statement (\code{'single'}, the default) or as an expression
48 (\code{'eval'}).  Any other value will cause \exception{ValueError} to 
49 be raised.
50
51 \strong{Caveat:}
52 It is possible (but not likely) that the parser stops parsing
53 with a successful outcome before reaching the end of the source;
54 in this case, trailing symbols may be ignored instead of causing an
55 error.  For example, a backslash followed by two newlines may be
56 followed by arbitrary garbage.  This will be fixed once the API
57 for the parser is better.
58 \end{funcdesc}
59
60 \begin{classdesc}{Compile}{}
61 Instances of this class have \method{__call__()} methods identical in
62 signature to the built-in function \function{compile()}, but with the
63 difference that if the instance compiles program text containing a
64 \module{__future__} statement, the instance 'remembers' and compiles
65 all subsequent program texts with the statement in force.
66 \end{classdesc}
67
68 \begin{classdesc}{CommandCompiler}{}
69 Instances of this class have \method{__call__()} methods identical in
70 signature to \function{compile_command()}; the difference is that if
71 the instance compiles program text containing a \code{__future__}
72 statement, the instance 'remembers' and compiles all subsequent
73 program texts with the statement in force.
74 \end{classdesc}
75
76 A note on version compatibility: the \class{Compile} and
77 \class{CommandCompiler} are new in Python 2.2.  If you want to enable
78 the future-tracking features of 2.2 but also retain compatibility with
79 2.1 and earlier versions of Python you can either write
80
81 \begin{verbatim}
82 try:
83     from codeop import CommandCompiler
84     compile_command = CommandCompiler()
85     del CommandCompiler
86 except ImportError:
87     from codeop import compile_command
88 \end{verbatim}
89
90 which is a low-impact change, but introduces possibly unwanted global
91 state into your program, or you can write:
92
93 \begin{verbatim}
94 try:
95     from codeop import CommandCompiler
96 except ImportError:
97     def CommandCompiler():
98         from codeop import compile_command
99         return compile_command
100 \end{verbatim}
101
102 and then call \code{CommandCompiler} every time you need a fresh
103 compiler object.