diff options
Diffstat (limited to 'Doc/lib/libfuncs.tex')
| -rw-r--r-- | Doc/lib/libfuncs.tex | 46 |
1 files changed, 40 insertions, 6 deletions
diff --git a/Doc/lib/libfuncs.tex b/Doc/lib/libfuncs.tex index f51f0d5..4dde065 100644 --- a/Doc/lib/libfuncs.tex +++ b/Doc/lib/libfuncs.tex @@ -178,7 +178,7 @@ class C: \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 + executed by a call to \function{exec()} or evaluated by a call to \function{eval()}. The \var{filename} argument should give the file from which the code was read; pass some recognizable value if it wasn't read from a file (\code{'<string>'} is commonly used). @@ -366,7 +366,7 @@ class C: compiled passing \code{'eval'} as the \var{kind} argument. Hints: dynamic execution of statements is supported by the - \keyword{exec} statement. Execution of statements from a file is + \function{exec()} function. Execution of statements from a file is supported by the \function{execfile()} function. The \function{globals()} and \function{locals()} functions returns the current global and local dictionary, respectively, which may be @@ -374,13 +374,47 @@ class C: \function{execfile()}. \end{funcdesc} + +\begin{funcdesc}{exec}{object\optional{, globals\optional{, locals}}} + This function supports dynamic execution of Python code. + \var{object} must be either a string, an open file object, or + a code object. If it is a string, the string is parsed as a suite of + Python statements which is then executed (unless a syntax error + occurs). If it is an open file, the file is parsed until \EOF{} and + executed. If it is a code object, it is simply executed. In all + cases, the code that's executed is expected to be valid as file + input (see the section ``File input'' in the Reference Manual). + Be aware that the \keyword{return} and \keyword{yield} statements may + not be used outside of function definitions even within the context of + code passed to the \function{exec()} function. + The return value is \code{None}. + + In all cases, if the optional parts are omitted, the code is executed + in the current scope. If only \var{globals} is provided, it must be + a dictionary, which will be used for both the global and the local + variables. If \var{globals} and \var{locals} are given, they are used + for the global and local variables, respectively. If provided, + \var{locals} can be any mapping object. + + If the \var{globals} dictionary does not contain a value for the + key \code{__builtins__}, a reference to the dictionary of the built-in + module \module{__builtin__} is inserted under that key. That way you + can control what builtins are available to the executed code by + inserting your own \code{__builtins__} dictionary into \var{globals} + before passing it to \function{exec()}. + + \note{The built-in functions \function{globals()} and \function{locals()} + return the current global and local dictionary, respectively, which + may be useful to pass around for use as the second and third + argument to \function{exec()}.} +\end{funcdesc} + \begin{funcdesc}{execfile}{filename\optional{, globals\optional{, locals}}} - This function is similar to the - \keyword{exec} statement, but parses a file instead of a string. It + This function is similar to the \function{exec()} function, but parses a + file given by the file name instead of a string. It is different from the \keyword{import} statement in that it does not use the module administration --- it reads the file unconditionally - and does not create a new module.\footnote{It is used relatively - rarely so does not warrant being made into a statement.} + and does not create a new module. The arguments are a file name and two optional dictionaries. The file is parsed and evaluated as a sequence of Python statements (similarly to a |