Doc/c-api/veryhigh.rst

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