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