summaryrefslogtreecommitdiffstats
path: root/Doc/lib/libcodeop.tex
diff options
context:
space:
mode:
authorMichael W. Hudson <mwh@python.net>2001-08-27 20:02:17 (GMT)
committerMichael W. Hudson <mwh@python.net>2001-08-27 20:02:17 (GMT)
commit53da3178011d5eaf143d6d9d76274a7530204179 (patch)
treefb925ca1fbd4b221068a84a2d0c81205c67abc46 /Doc/lib/libcodeop.tex
parent71b6af91d382a0e084b55f1d519aedc1b71a97d4 (diff)
downloadcpython-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.tex74
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.