diff options
author | Michael W. Hudson <mwh@python.net> | 2001-08-27 20:02:17 (GMT) |
---|---|---|
committer | Michael W. Hudson <mwh@python.net> | 2001-08-27 20:02:17 (GMT) |
commit | 53da3178011d5eaf143d6d9d76274a7530204179 (patch) | |
tree | fb925ca1fbd4b221068a84a2d0c81205c67abc46 /Doc/lib/libcodeop.tex | |
parent | 71b6af91d382a0e084b55f1d519aedc1b71a97d4 (diff) | |
download | cpython-53da3178011d5eaf143d6d9d76274a7530204179.zip cpython-53da3178011d5eaf143d6d9d76274a7530204179.tar.gz cpython-53da3178011d5eaf143d6d9d76274a7530204179.tar.bz2 |
Docs for the PEP 264 changes.
Diffstat (limited to 'Doc/lib/libcodeop.tex')
-rw-r--r-- | Doc/lib/libcodeop.tex | 74 |
1 files changed, 67 insertions, 7 deletions
diff --git a/Doc/lib/libcodeop.tex b/Doc/lib/libcodeop.tex index 6b9f3cf..4f68160 100644 --- a/Doc/lib/libcodeop.tex +++ b/Doc/lib/libcodeop.tex @@ -5,14 +5,29 @@ \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 a function to compile Python code -with hints on whether it is certainly complete, possibly complete or -definitely incomplete. This is used by the \refmodule{code} module -and should not normally be used directly. +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. -The \module{codeop} module defines the following function: +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}}} @@ -25,8 +40,8 @@ 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} if there is an invalid numeric -constant. +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 @@ -41,3 +56,48 @@ 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. |