Fred Drake | b742a42 | 1999-06-23 13:33:40 +0000 | [diff] [blame] | 1 | \section{\module{codeop} --- |
| 2 | Compile Python code} |
| 3 | |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 4 | % LaTeXed from excellent doc-string. |
| 5 | |
Fred Drake | b742a42 | 1999-06-23 13:33:40 +0000 | [diff] [blame] | 6 | \declaremodule{standard}{codeop} |
Fred Drake | 57657bc | 2000-12-01 15:25:23 +0000 | [diff] [blame] | 7 | \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} |
Michael W. Hudson | 53da317 | 2001-08-27 20:02:17 +0000 | [diff] [blame] | 8 | \sectionauthor{Michael Hudson}{mwh@python.net} |
Fred Drake | b742a42 | 1999-06-23 13:33:40 +0000 | [diff] [blame] | 9 | \modulesynopsis{Compile (possibly incomplete) Python code.} |
| 10 | |
Michael W. Hudson | 53da317 | 2001-08-27 20:02:17 +0000 | [diff] [blame] | 11 | The \module{codeop} module provides utilities upon which the Python |
Fred Drake | 5cb29a4 | 2001-08-28 14:25:03 +0000 | [diff] [blame] | 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. |
Fred Drake | b742a42 | 1999-06-23 13:33:40 +0000 | [diff] [blame] | 16 | |
Michael W. Hudson | 53da317 | 2001-08-27 20:02:17 +0000 | [diff] [blame] | 17 | There are two parts to this job: |
| 18 | |
Fred Drake | 5cb29a4 | 2001-08-28 14:25:03 +0000 | [diff] [blame] | 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 |
Michael W. Hudson | 9e151d1 | 2004-06-17 13:29:11 +0000 | [diff] [blame] | 22 | `\code{>\code{>}>~}' or `\code{...~}' next. |
Fred Drake | 5cb29a4 | 2001-08-28 14:25:03 +0000 | [diff] [blame] | 23 | \item Remembering which future statements the user has entered, so |
| 24 | subsequent input can be compiled with these in effect. |
| 25 | \end{enumerate} |
Michael W. Hudson | 53da317 | 2001-08-27 20:02:17 +0000 | [diff] [blame] | 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: |
Fred Drake | b742a42 | 1999-06-23 13:33:40 +0000 | [diff] [blame] | 31 | |
| 32 | \begin{funcdesc}{compile_command} |
| 33 | {source\optional{, filename\optional{, symbol}}} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 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 |
Fred Drake | b742a42 | 1999-06-23 13:33:40 +0000 | [diff] [blame] | 36 | Python code. In that case, the filename attribute of the code object |
| 37 | will be \var{filename}, which defaults to \code{'<input>'}. |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 38 | Returns \code{None} if \var{source} is \emph{not} valid Python |
Fred Drake | b742a42 | 1999-06-23 13:33:40 +0000 | [diff] [blame] | 39 | code, but is a prefix of valid Python code. |
| 40 | |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 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, |
Michael W. Hudson | 53da317 | 2001-08-27 20:02:17 +0000 | [diff] [blame] | 43 | and \exception{OverflowError} or \exception{ValueError} if there is an |
| 44 | invalid literal. |
Fred Drake | b742a42 | 1999-06-23 13:33:40 +0000 | [diff] [blame] | 45 | |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 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. |
Fred Drake | b742a42 | 1999-06-23 13:33:40 +0000 | [diff] [blame] | 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} |
Michael W. Hudson | 53da317 | 2001-08-27 20:02:17 +0000 | [diff] [blame] | 59 | |
| 60 | \begin{classdesc}{Compile}{} |
Fred Drake | 5cb29a4 | 2001-08-28 14:25:03 +0000 | [diff] [blame] | 61 | Instances of this class have \method{__call__()} methods indentical in |
| 62 | signature to the built-in function \function{compile()}, but with the |
Michael W. Hudson | 53da317 | 2001-08-27 20:02:17 +0000 | [diff] [blame] | 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}{} |
Fred Drake | 5cb29a4 | 2001-08-28 14:25:03 +0000 | [diff] [blame] | 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__} |
Michael W. Hudson | 53da317 | 2001-08-27 20:02:17 +0000 | [diff] [blame] | 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 |
Raymond Hettinger | a04c3d8 | 2002-09-04 15:12:07 +0000 | [diff] [blame] | 99 | return compile_command |
Michael W. Hudson | 53da317 | 2001-08-27 20:02:17 +0000 | [diff] [blame] | 100 | \end{verbatim} |
| 101 | |
| 102 | and then call \code{CommandCompiler} every time you need a fresh |
| 103 | compiler object. |