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