Doc/api/veryhigh.tex

   1 \chapter{The Very High Level Layer \label{veryhigh}}
   2
   3
   4 The functions in this chapter will let you execute Python source code
   5 given in a file or a buffer, but they will not let you interact in a
   6 more detailed way with the interpreter.
   7
   8 Several of these functions accept a start symbol from the grammar as a
   9 parameter.  The available start symbols are \constant{Py_eval_input},
  10 \constant{Py_file_input}, and \constant{Py_single_input}.  These are
  11 described following the functions which accept them as parameters.
  12
  13 Note also that several of these functions take \ctype{FILE*}
  14 parameters.  On particular issue which needs to be handled carefully
  15 is that the \ctype{FILE} structure for different C libraries can be
  16 different and incompatible.  Under Windows (at least), it is possible
  17 for dynamically linked extensions to actually use different libraries,
  18 so care should be taken that \ctype{FILE*} parameters are only passed
  19 to these functions if it is certain that they were created by the same
  20 library that the Python runtime is using.
  21
  22
  23 \begin{cfuncdesc}{int}{Py_Main}{int argc, char **argv}
  24   The main program for the standard interpreter.  This is made
  25   available for programs which embed Python.  The \var{argc} and
  26   \var{argv} parameters should be prepared exactly as those which are
  27   passed to a C program's \cfunction{main()} function.  It is
  28   important to note that the argument list may be modified (but the
  29   contents of the strings pointed to by the argument list are not).
  30   The return value will be the integer passed to the
  31   \function{sys.exit()} function, \code{1} if the interpreter exits
  32   due to an exception, or \code{2} if the parameter list does not
  33   represent a valid Python command line.
  34 \end{cfuncdesc}
  35
  36 \begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *fp, const char *filename}
  37   This is a simplified interface to \cfunction{PyRun_AnyFileExFlags()}
  38   below, leaving \var{closeit} set to \code{0} and \var{flags} set to \NULL.
  39 \end{cfuncdesc}
  40
  41 \begin{cfuncdesc}{int}{PyRun_AnyFileFlags}{FILE *fp, const char *filename,
  42                                            PyCompilerFlags *flags}
  43   This is a simplified interface to \cfunction{PyRun_AnyFileExFlags()}
  44   below, leaving the \var{closeit} argument set to \code{0}.
  45 \end{cfuncdesc}
  46
  47 \begin{cfuncdesc}{int}{PyRun_AnyFileEx}{FILE *fp, const char *filename,
  48                                         int closeit}
  49   This is a simplified interface to \cfunction{PyRun_AnyFileExFlags()}
  50   below, leaving the \var{flags} argument set to \NULL.
  51 \end{cfuncdesc}
  52
  53 \begin{cfuncdesc}{int}{PyRun_AnyFileExFlags}{FILE *fp, const char *filename,
  54                                              int closeit,
  55                                              PyCompilerFlags *flags}
  56   If \var{fp} refers to a file associated with an interactive device
  57   (console or terminal input or \UNIX{} pseudo-terminal), return the
  58   value of \cfunction{PyRun_InteractiveLoop()}, otherwise return the
  59   result of \cfunction{PyRun_SimpleFile()}.  If \var{filename} is
  60   \NULL, this function uses \code{"???"} as the filename.
  61 \end{cfuncdesc}
  62
  63 \begin{cfuncdesc}{int}{PyRun_SimpleString}{const char *command}
  64   This is a simplified interface to \cfunction{PyRun_SimpleStringFlags()}
  65   below, leaving the \var{PyCompilerFlags*} argument set to NULL.
  66 \end{cfuncdesc}
  67
  68 \begin{cfuncdesc}{int}{PyRun_SimpleStringFlags}{const char *command,
  69                                                 PyCompilerFlags *flags}
  70   Executes the Python source code from \var{command} in the
  71   \module{__main__} module according to the \var{flags} argument.
  72   If \module{__main__} does not already exist, it is created.  Returns
  73   \code{0} on success or \code{-1} if an exception was raised.  If there
  74   was an error, there is no way to get the exception information.
  75   For the meaning of \var{flags}, see below.
  76 \end{cfuncdesc}
  77
  78 \begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *fp, const char *filename}
  79   This is a simplified interface to \cfunction{PyRun_SimpleFileExFlags()}
  80   below, leaving \var{closeit} set to \code{0} and \var{flags} set to
  81   \NULL.
  82 \end{cfuncdesc}
  83
  84 \begin{cfuncdesc}{int}{PyRun_SimpleFileFlags}{FILE *fp, const char *filename,
  85                                               PyCompilerFlags *flags}
  86   This is a simplified interface to \cfunction{PyRun_SimpleFileExFlags()}
  87   below, leaving \var{closeit} set to \code{0}.
  88 \end{cfuncdesc}
  89
  90 \begin{cfuncdesc}{int}{PyRun_SimpleFileEx}{FILE *fp, const char *filename,
  91                                            int closeit}
  92   This is a simplified interface to \cfunction{PyRun_SimpleFileExFlags()}
  93   below, leaving \var{flags} set to \NULL.
  94 \end{cfuncdesc}
  95
  96 \begin{cfuncdesc}{int}{PyRun_SimpleFileExFlags}{FILE *fp, const char *filename,
  97                                                 int closeit,
  98                                                 PyCompilerFlags *flags}
  99   Similar to \cfunction{PyRun_SimpleStringFlags()}, but the Python source
 100   code is read from \var{fp} instead of an in-memory string.
 101   \var{filename} should be the name of the file.  If \var{closeit} is
 102   true, the file is closed before PyRun_SimpleFileExFlags returns.
 103 \end{cfuncdesc}
 104
 105 \begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *fp, const char *filename}
 106   This is a simplified interface to \cfunction{PyRun_InteractiveOneFlags()}
 107   below, leaving \var{flags} set to \NULL.
 108 \end{cfuncdesc}
 109
 110 \begin{cfuncdesc}{int}{PyRun_InteractiveOneFlags}{FILE *fp,
 111                                                   const char *filename,
 112                                                   PyCompilerFlags *flags}
 113   Read and execute a single statement from a file associated with an
 114   interactive device according to the \var{flags} argument.  If
 115   \var{filename} is \NULL, \code{"???"} is used instead.  The user will
 116   be prompted using \code{sys.ps1} and \code{sys.ps2}.  Returns \code{0}
 117   when the input was executed successfully, \code{-1} if there was an
 118   exception, or an error code from the \file{errcode.h} include file
 119   distributed as part of Python if there was a parse error.  (Note that
 120   \file{errcode.h} is not included by \file{Python.h}, so must be included
 121   specifically if needed.)
 122 \end{cfuncdesc}
 123
 124 \begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *fp, const char *filename}
 125   This is a simplified interface to \cfunction{PyRun_InteractiveLoopFlags()}
 126   below, leaving \var{flags} set to \NULL.
 127 \end{cfuncdesc}
 128
 129 \begin{cfuncdesc}{int}{PyRun_InteractiveLoopFlags}{FILE *fp,
 130                                                    const char *filename,
 131                                                    PyCompilerFlags *flags}
 132   Read and execute statements from a file associated with an
 133   interactive device until \EOF{} is reached.  If \var{filename} is
 134   \NULL, \code{"???"} is used instead.  The user will be prompted
 135   using \code{sys.ps1} and \code{sys.ps2}.  Returns \code{0} at \EOF.
 136 \end{cfuncdesc}
 137
 138 \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseString}{const char *str,
 139                                                              int start}
 140   This is a simplified interface to
 141   \cfunction{PyParser_SimpleParseStringFlagsFilename()} below, leaving
 142   \var{filename} set to \NULL{} and \var{flags} set to \code{0}.
 143 \end{cfuncdesc}
 144
 145 \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseStringFlags}{
 146                                  const char *str, int start, int flags}
 147   This is a simplified interface to
 148   \cfunction{PyParser_SimpleParseStringFlagsFilename()} below, leaving
 149   \var{filename} set to \NULL.
 150 \end{cfuncdesc}
 151
 152 \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseStringFlagsFilename}{
 153                                  const char *str, const char *filename,
 154                                  int start, int flags}
 155   Parse Python source code from \var{str} using the start token
 156   \var{start} according to the \var{flags} argument.  The result can
 157   be used to create a code object which can be evaluated efficiently.
 158   This is useful if a code fragment must be evaluated many times.
 159 \end{cfuncdesc}
 160
 161 \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFile}{FILE *fp,
 162                                  const char *filename, int start}
 163   This is a simplified interface to \cfunction{PyParser_SimpleParseFileFlags()}
 164   below, leaving \var{flags} set to \code{0}
 165 \end{cfuncdesc}
 166
 167 \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFileFlags}{FILE *fp,
 168                                  const char *filename, int start, int flags}
 169   Similar to \cfunction{PyParser_SimpleParseStringFlagsFilename()}, but
 170   the Python source code is read from \var{fp} instead of an in-memory
 171   string.
 172 \end{cfuncdesc}
 173
 174 \begin{cfuncdesc}{PyObject*}{PyRun_String}{const char *str, int start,
 175                                            PyObject *globals,
 176                                            PyObject *locals}
 177   This is a simplified interface to \cfunction{PyRun_StringFlags()} below,
 178   leaving \var{flags} set to \NULL.
 179 \end{cfuncdesc}
 180
 181 \begin{cfuncdesc}{PyObject*}{PyRun_StringFlags}{const char *str, int start,
 182                                                 PyObject *globals,
 183                                                 PyObject *locals,
 184                                                 PyCompilerFlags *flags}
 185   Execute Python source code from \var{str} in the context specified
 186   by the dictionaries \var{globals} and \var{locals} with the compiler
 187   flags specified by \var{flags}.  The parameter \var{start} specifies
 188   the start token that should be used to parse the source code.
 189
 190   Returns the result of executing the code as a Python object, or
 191   \NULL{} if an exception was raised.
 192 \end{cfuncdesc}
 193
 194 \begin{cfuncdesc}{PyObject*}{PyRun_File}{FILE *fp, const char *filename,
 195                                          int start, PyObject *globals,
 196                                          PyObject *locals}
 197   This is a simplified interface to \cfunction{PyRun_FileExFlags()} below,
 198   leaving \var{closeit} set to \code{0} and \var{flags} set to \NULL.
 199 \end{cfuncdesc}
 200
 201 \begin{cfuncdesc}{PyObject*}{PyRun_FileEx}{FILE *fp, const char *filename,
 202                                          int start, PyObject *globals,
 203                                          PyObject *locals, int closeit}
 204   This is a simplified interface to \cfunction{PyRun_FileExFlags()} below,
 205   leaving \var{flags} set to \NULL.
 206 \end{cfuncdesc}
 207
 208 \begin{cfuncdesc}{PyObject*}{PyRun_FileFlags}{FILE *fp, const char *filename,
 209                                          int start, PyObject *globals,
 210                                          PyObject *locals,
 211                                          PyCompilerFlags *flags}
 212   This is a simplified interface to \cfunction{PyRun_FileExFlags()} below,
 213   leaving \var{closeit} set to \code{0}.
 214 \end{cfuncdesc}
 215
 216 \begin{cfuncdesc}{PyObject*}{PyRun_FileExFlags}{FILE *fp, const char *filename,
 217                                                 int start, PyObject *globals,
 218                                                 PyObject *locals, int closeit,
 219                                                 PyCompilerFlags *flags}
 220   Similar to \cfunction{PyRun_StringFlags()}, but the Python source code is
 221   read from \var{fp} instead of an in-memory string.
 222   \var{filename} should be the name of the file.
 223   If \var{closeit} is true, the file is closed before
 224   \cfunction{PyRun_FileExFlags()} returns.
 225 \end{cfuncdesc}
 226
 227 \begin{cfuncdesc}{PyObject*}{Py_CompileString}{const char *str,
 228                                                const char *filename,
 229                                                int start}
 230   This is a simplified interface to \cfunction{Py_CompileStringFlags()} below,
 231   leaving \var{flags} set to \NULL.
 232 \end{cfuncdesc}
 233
 234 \begin{cfuncdesc}{PyObject*}{Py_CompileStringFlags}{const char *str,
 235                                                     const char *filename,
 236                                                     int start,
 237                                                     PyCompilerFlags *flags}
 238   Parse and compile the Python source code in \var{str}, returning the
 239   resulting code object.  The start token is given by \var{start};
 240   this can be used to constrain the code which can be compiled and should
 241   be \constant{Py_eval_input}, \constant{Py_file_input}, or
 242   \constant{Py_single_input}.  The filename specified by
 243   \var{filename} is used to construct the code object and may appear
 244   in tracebacks or \exception{SyntaxError} exception messages.  This
 245   returns \NULL{} if the code cannot be parsed or compiled.
 246 \end{cfuncdesc}
 247
 248 \begin{cvardesc}{int}{Py_eval_input}
 249   The start symbol from the Python grammar for isolated expressions;
 250   for use with
 251   \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}.
 252 \end{cvardesc}
 253
 254 \begin{cvardesc}{int}{Py_file_input}
 255   The start symbol from the Python grammar for sequences of statements
 256   as read from a file or other source; for use with
 257   \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}.  This is
 258   the symbol to use when compiling arbitrarily long Python source code.
 259 \end{cvardesc}
 260
 261 \begin{cvardesc}{int}{Py_single_input}
 262   The start symbol from the Python grammar for a single statement; for
 263   use with \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}.
 264   This is the symbol used for the interactive interpreter loop.
 265 \end{cvardesc}
 266
 267 \begin{ctypedesc}[PyCompilerFlags]{struct PyCompilerFlags}
 268   This is the structure used to hold compiler flags.  In cases where
 269   code is only being compiled, it is passed as \code{int flags}, and in
 270   cases where code is being executed, it is passed as
 271   \code{PyCompilerFlags *flags}.  In this case, \code{from __future__
 272   import} can modify \var{flags}.
 273
 274   Whenever \code{PyCompilerFlags *flags} is \NULL, \member{cf_flags}
 275   is treated as equal to \code{0}, and any modification due to
 276   \code{from __future__ import} is discarded.
 277 \begin{verbatim}
 278 struct PyCompilerFlags {
 279     int cf_flags;
 280 }
 281 \end{verbatim}
 282 \end{ctypedesc}
 283
 284 \begin{cvardesc}{int}{CO_FUTURE_DIVISION}
 285   This bit can be set in \var{flags} to cause division operator \code{/}
 286   to be interpreted as ``true division'' according to \pep{238}.
 287 \end{cvardesc}