From 53da3178011d5eaf143d6d9d76274a7530204179 Mon Sep 17 00:00:00 2001 From: "Michael W. Hudson" Date: Mon, 27 Aug 2001 20:02:17 +0000 Subject: Docs for the PEP 264 changes. --- Doc/lib/libcode.tex | 5 ++-- Doc/lib/libcodeop.tex | 74 ++++++++++++++++++++++++++++++++++++++++++++++----- Doc/lib/libfuncs.tex | 21 ++++++++++++++- Doc/ref/refa1.tex | 34 +++++++++++++++-------- 4 files changed, 112 insertions(+), 22 deletions(-) diff --git a/Doc/lib/libcode.tex b/Doc/lib/libcode.tex index 36410b2..ff6bde2 100644 --- a/Doc/lib/libcode.tex +++ b/Doc/lib/libcode.tex @@ -60,9 +60,8 @@ Returns a code object (the same as \code{compile(\var{source}, \var{filename}, \var{symbol})}) if the command is complete and valid; \code{None} if the command is incomplete; raises \exception{SyntaxError} if the command is complete and contains a -syntax error, or raises \exception{OverflowError} if the command -includes a numeric constant which exceeds the range of the -appropriate numeric type. +syntax error, or raises \exception{OverflowError} or +\exception{ValueError} if the command cotains an invalid literal. \end{funcdesc} 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. diff --git a/Doc/lib/libfuncs.tex b/Doc/lib/libfuncs.tex index 12b7cf7..53970ee 100644 --- a/Doc/lib/libfuncs.tex +++ b/Doc/lib/libfuncs.tex @@ -118,7 +118,8 @@ class instances are callable if they have a \method{__call__()} method. operations. \end{funcdesc} -\begin{funcdesc}{compile}{string, filename, kind} +\begin{funcdesc}{compile}{string, filename, kind\optional{, + flags\optional{, dont_inherit}}} Compile the \var{string} into a code object. Code objects can be executed by an \keyword{exec} statement or evaluated by a call to \function{eval()}. The \var{filename} argument should @@ -130,6 +131,24 @@ class instances are callable if they have a \method{__call__()} method. expression, or \code{'single'} if it consists of a single interactive statement (in the latter case, expression statements that evaluate to something else than \code{None} will printed). + + The optional arguments \var{flags} and \optional{dont_inherit} + (which are new in Python 2.2) control which future statements (see + \pep{236}) affect the compilation of \var{string}. If neither is + present (or both are zero) the code is compiled with those future + statements that are in effect in the code that is calling compile. + If the \var{flags} argument is given and \var{dont_inherit} is not + (or is zero) then the future statements specified by the \var{flags} + argument are used in addition to those that would be used anyway. + If \var{dont_inherit} is a non-zero integer then the \var{flags} + argument is it -- the future statements in effect around the call to + compile are ignored. + + Future statemants are specified by bits which can be bitwise or-ed + together to specify multiple statements. The bitfield required to + specify a given feature can be found as the \member{compiler_flag} + attribute on the \class{_Feature} instance in the + \module{__future__} module. \end{funcdesc} \begin{funcdesc}{complex}{real\optional{, imag}} diff --git a/Doc/ref/refa1.tex b/Doc/ref/refa1.tex index 9a22513..bd3a38c 100644 --- a/Doc/ref/refa1.tex +++ b/Doc/ref/refa1.tex @@ -40,14 +40,17 @@ lines that can appear before a future statement are: \end{itemize} -The only feature recognized by Python 2.1 is \samp{nested_scopes}. - -A future statement is recognized and treated specially at compile time: -Changes to the semantics of core constructs are often implemented by -generating different code. It may even be the case that a new feature -introduces new incompatible syntax (such as a new reserved word), in -which case the compiler may need to parse the module differently. Such -decisions cannot be pushed off until runtime. +The features recognized by Python 2.2 are \samp{generators}, +\samp{division} and \samp{nested_scopes}. \samp{nested_scopes} +is redundant in 2.2 as the nested scopes feature is active by default. + +A future statement is recognized and treated specially at compile +time: Changes to the semantics of core constructs are often +implemented by generating different code. It may even be the case +that a new feature introduces new incompatible syntax (such as a new +reserved word), in which case the compiler may need to parse the +module differently. Such decisions cannot be pushed off until +runtime. For any given release, the compiler knows which feature names have been defined, and raises a compile-time error if a future statement contains @@ -72,8 +75,11 @@ no special semantics or syntax restrictions. Code compiled by an exec statement or calls to the builtin functions \function{compile()} and \function{execfile()} that occur in a module -\module{M} containing a future statement will use the new syntax or -semantics associated with the future statement. +\module{M} containing a future statement will, by default, use the new +syntax or semantics associated with the future statement. This can, +starting with Python 2.2 be controlled by optional arguments to +\function{compile()} --- see the documentation of that function in the +library reference for details. A future statement typed at an interactive interpreter prompt will take effect for the rest of the interpreter session. If an @@ -110,7 +116,8 @@ is executed. Each statment in \file{__future__.py} is of the form: \begin{verbatim} -FeatureName = "_Feature(" OptionalRelease "," MandatoryRelease ")" +FeatureName = "_Feature(" OptionalRelease "," MandatoryRelease "," + CompilerFlag ")" \end{verbatim} where, normally, OptionalRelease is less then MandatoryRelease, and @@ -143,6 +150,11 @@ feature got dropped. Instances of class \class{_Feature} have two corresponding methods, \method{getOptionalRelease()} and \method{getMandatoryRelease()}. +CompilerFlag is the (bitfield) flag that should be passed in the +fourth argument to the builtin function \function{compile()} to enable +the feature in dynamically compiled code. This flag is stored in the +\member{compiler_flag} attribute on \class{_Future} instances. + No feature description will ever be deleted from \module{__future__}. \section{Nested scopes \label{nested-scopes}} -- cgit v0.12