| \section{\module{codeop} --- |
| Compile Python code} |
| |
| % LaTeXed from excellent doc-string. |
| |
| \declaremodule{standard}{codeop} |
| \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} |
| \sectionauthor{Michael Hudson}{mwh@python.net} |
| \modulesynopsis{Compile (possibly incomplete) Python code.} |
| |
| The \module{codeop} module provides utilities upon which the Python |
| read-eval-print loop can be emulated -- as in the \refmodule{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 \refmodule{code} instead. |
| |
| There are two parts to this job: |
| |
| \begin{list} |
| \listitem Being able to tell if a line of input completes a Python |
| statement -- in short telling whether to print ``>>> '' or |
| ``... '' next. |
| \listitem Remembering which future statements the user has entered, so |
| subsequent input can be compiled wiht these in effect. |
| \end{list} |
| |
| The \module{codeop} module provides a way of doing each of these |
| things, and a way of doing them both. |
| |
| To do just the former: |
| |
| \begin{funcdesc}{compile_command} |
| {source\optional{, filename\optional{, symbol}}} |
| Tries to compile \var{source}, which should be a string of Python |
| code and return a code object if \var{source} is valid |
| Python code. In that case, the filename attribute of the code object |
| will be \var{filename}, which defaults to \code{'<input>'}. |
| Returns \code{None} if \var{source} is \emph{not} valid Python |
| code, but is a prefix of valid Python code. |
| |
| If there is a problem with \var{source}, an exception will be raised. |
| \exception{SyntaxError} is raised if there is invalid Python syntax, |
| and \exception{OverflowError} or \exception{ValueError} if there is an |
| invalid literal. |
| |
| The \var{symbol} argument determines whether \var{source} is compiled |
| as a statement (\code{'single'}, the default) or as an expression |
| (\code{'eval'}). Any other value will cause \exception{ValueError} to |
| be raised. |
| |
| \strong{Caveat:} |
| 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. |
| \end{funcdesc} |
| |
| \begin{classdesc}{Compile}{} |
| Instances of this class have \method{__call__} methods indentical in |
| signature to the built-in function \function{compile}, but with the |
| difference that if the instance compiles program text containing a |
| \module{__future__} statement, the instance 'remembers' and compiles |
| all subsequent program texts with the statement in force. |
| \end{classdesc} |
| |
| \begin{classdesc}{CommandCompiler}{} |
| Instances of this class have \method{__call__} methods identical in |
| signature to \function{compile_command}; the difference is that if the |
| instance compiles program text containing a \method{__future__} |
| statement, the instance 'remembers' and compiles all subsequent |
| program texts with the statement in force. |
| \end{classdesc} |
| |
| A note on version compatibility: the \class{Compile} and |
| \class{CommandCompiler} are new in Python 2.2. If you want to enable |
| the future-tracking features of 2.2 but also retain compatibility with |
| 2.1 and earlier versions of Python you can either write |
| |
| \begin{verbatim} |
| try: |
| from codeop import CommandCompiler |
| compile_command = CommandCompiler() |
| del CommandCompiler |
| except ImportError: |
| from codeop import compile_command |
| \end{verbatim} |
| |
| which is a low-impact change, but introduces possibly unwanted global |
| state into your program, or you can write: |
| |
| \begin{verbatim} |
| try: |
| from codeop import CommandCompiler |
| except ImportError: |
| def CommandCompiler(): |
| from codeop import compile_command |
| return compile_comamnd |
| \end{verbatim} |
| |
| and then call \code{CommandCompiler} every time you need a fresh |
| compiler object. |