Home | History | Annotate | Download | only in c-api
      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 :c:type:`FILE\*` parameters.  One
     20 particular issue which needs to be handled carefully is that the :c:type:`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 :c:type:`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 .. c:function:: int Py_Main(int argc, wchar_t **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 :c:func:`main`
     33    function (converted to wchar_t according to the user's locale).  It is
     34    important to note that the argument list may be modified (but the contents of
     35    the strings pointed to by the argument list are not). The return value will
     36    be ``0`` if the interpreter exits normally (i.e., without an exception),
     37    ``1`` if the interpreter exits due to an exception, or ``2`` if the parameter
     38    list does not represent a valid Python command line.
     39 
     40    Note that if an otherwise unhandled :exc:`SystemExit` is raised, this
     41    function will not return ``1``, but exit the process, as long as
     42    ``Py_InspectFlag`` is not set.
     43 
     44 
     45 .. c:function:: int PyRun_AnyFile(FILE *fp, const char *filename)
     46 
     47    This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving
     48    *closeit* set to ``0`` and *flags* set to *NULL*.
     49 
     50 
     51 .. c:function:: int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
     52 
     53    This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving
     54    the *closeit* argument set to ``0``.
     55 
     56 
     57 .. c:function:: int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)
     58 
     59    This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving
     60    the *flags* argument set to *NULL*.
     61 
     62 
     63 .. c:function:: int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)
     64 
     65    If *fp* refers to a file associated with an interactive device (console or
     66    terminal input or Unix pseudo-terminal), return the value of
     67    :c:func:`PyRun_InteractiveLoop`, otherwise return the result of
     68    :c:func:`PyRun_SimpleFile`.  *filename* is decoded from the filesystem
     69    encoding (:func:`sys.getfilesystemencoding`).  If *filename* is *NULL*, this
     70    function uses ``"???"`` as the filename.
     71 
     72 
     73 .. c:function:: int PyRun_SimpleString(const char *command)
     74 
     75    This is a simplified interface to :c:func:`PyRun_SimpleStringFlags` below,
     76    leaving the *PyCompilerFlags\** argument set to NULL.
     77 
     78 
     79 .. c:function:: 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:`SystemExit` 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 .. c:function:: int PyRun_SimpleFile(FILE *fp, const char *filename)
     93 
     94    This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below,
     95    leaving *closeit* set to ``0`` and *flags* set to *NULL*.
     96 
     97 
     98 .. c:function:: int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)
     99 
    100    This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below,
    101    leaving *flags* set to *NULL*.
    102 
    103 
    104 .. c:function:: int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)
    105 
    106    Similar to :c:func:`PyRun_SimpleStringFlags`, but the Python source code is read
    107    from *fp* instead of an in-memory string. *filename* should be the name of
    108    the file, it is decoded from the filesystem encoding
    109    (:func:`sys.getfilesystemencoding`).  If *closeit* is true, the file is
    110    closed before PyRun_SimpleFileExFlags returns.
    111 
    112 
    113 .. c:function:: int PyRun_InteractiveOne(FILE *fp, const char *filename)
    114 
    115    This is a simplified interface to :c:func:`PyRun_InteractiveOneFlags` below,
    116    leaving *flags* set to *NULL*.
    117 
    118 
    119 .. c:function:: int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
    120 
    121    Read and execute a single statement from a file associated with an
    122    interactive device according to the *flags* argument.  The user will be
    123    prompted using ``sys.ps1`` and ``sys.ps2``.  *filename* is decoded from the
    124    filesystem encoding (:func:`sys.getfilesystemencoding`).
    125 
    126    Returns ``0`` when the input was
    127    executed successfully, ``-1`` if there was an exception, or an error code
    128    from the :file:`errcode.h` include file distributed as part of Python if
    129    there was a parse error.  (Note that :file:`errcode.h` is not included by
    130    :file:`Python.h`, so must be included specifically if needed.)
    131 
    132 
    133 .. c:function:: int PyRun_InteractiveLoop(FILE *fp, const char *filename)
    134 
    135    This is a simplified interface to :c:func:`PyRun_InteractiveLoopFlags` below,
    136    leaving *flags* set to *NULL*.
    137 
    138 
    139 .. c:function:: 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.  The user will be prompted using ``sys.ps1`` and
    143    ``sys.ps2``.  *filename* is decoded from the filesystem encoding
    144    (:func:`sys.getfilesystemencoding`).  Returns ``0`` at EOF.
    145 
    146 
    147 .. c:var:: int (*PyOS_InputHook)(void)
    148 
    149    Can be set to point to a function with the prototype
    150    ``int func(void)``.  The function will be called when Python's
    151    interpreter prompt is about to become idle and wait for user input
    152    from the terminal.  The return value is ignored.  Overriding this
    153    hook can be used to integrate the interpreter's prompt with other
    154    event loops, as done in the :file:`Modules/_tkinter.c` in the
    155    Python source code.
    156 
    157 
    158 .. c:var:: char* (*PyOS_ReadlineFunctionPointer)(FILE *, FILE *, const char *)
    159 
    160    Can be set to point to a function with the prototype
    161    ``char *func(FILE *stdin, FILE *stdout, char *prompt)``,
    162    overriding the default function used to read a single line of input
    163    at the interpreter's prompt.  The function is expected to output
    164    the string *prompt* if it's not *NULL*, and then read a line of
    165    input from the provided standard input file, returning the
    166    resulting string.  For example, The :mod:`readline` module sets
    167    this hook to provide line-editing and tab-completion features.
    168 
    169    The result must be a string allocated by :c:func:`PyMem_RawMalloc` or
    170    :c:func:`PyMem_RawRealloc`, or *NULL* if an error occurred.
    171 
    172    .. versionchanged:: 3.4
    173       The result must be allocated by :c:func:`PyMem_RawMalloc` or
    174       :c:func:`PyMem_RawRealloc`, instead of being allocated by
    175       :c:func:`PyMem_Malloc` or :c:func:`PyMem_Realloc`.
    176 
    177 
    178 .. c:function:: struct _node* PyParser_SimpleParseString(const char *str, int start)
    179 
    180    This is a simplified interface to
    181    :c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving  *filename* set
    182    to *NULL* and *flags* set to ``0``.
    183 
    184 
    185 .. c:function:: struct _node* PyParser_SimpleParseStringFlags( const char *str, int start, int flags)
    186 
    187    This is a simplified interface to
    188    :c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving  *filename* set
    189    to *NULL*.
    190 
    191 
    192 .. c:function:: struct _node* PyParser_SimpleParseStringFlagsFilename( const char *str, const char *filename, int start, int flags)
    193 
    194    Parse Python source code from *str* using the start token *start* according to
    195    the *flags* argument.  The result can be used to create a code object which can
    196    be evaluated efficiently. This is useful if a code fragment must be evaluated
    197    many times. *filename* is decoded from the filesystem encoding
    198    (:func:`sys.getfilesystemencoding`).
    199 
    200 
    201 .. c:function:: struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)
    202 
    203    This is a simplified interface to :c:func:`PyParser_SimpleParseFileFlags` below,
    204    leaving *flags* set to ``0``.
    205 
    206 
    207 .. c:function:: struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags)
    208 
    209    Similar to :c:func:`PyParser_SimpleParseStringFlagsFilename`, but the Python
    210    source code is read from *fp* instead of an in-memory string.
    211 
    212 
    213 .. c:function:: PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)
    214 
    215    This is a simplified interface to :c:func:`PyRun_StringFlags` below, leaving
    216    *flags* set to *NULL*.
    217 
    218 
    219 .. c:function:: PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
    220 
    221    Execute Python source code from *str* in the context specified by the
    222    objects *globals* and *locals* with the compiler flags specified by
    223    *flags*.  *globals* must be a dictionary; *locals* can be any object
    224    that implements the mapping protocol.  The parameter *start* specifies
    225    the start token that should be used to parse the source code.
    226 
    227    Returns the result of executing the code as a Python object, or *NULL* if an
    228    exception was raised.
    229 
    230 
    231 .. c:function:: PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)
    232 
    233    This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving
    234    *closeit* set to ``0`` and *flags* set to *NULL*.
    235 
    236 
    237 .. c:function:: PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)
    238 
    239    This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving
    240    *flags* set to *NULL*.
    241 
    242 
    243 .. c:function:: PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
    244 
    245    This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving
    246    *closeit* set to ``0``.
    247 
    248 
    249 .. c:function:: PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)
    250 
    251    Similar to :c:func:`PyRun_StringFlags`, but the Python source code is read from
    252    *fp* instead of an in-memory string. *filename* should be the name of the file,
    253    it is decoded from the filesystem encoding (:func:`sys.getfilesystemencoding`).
    254    If *closeit* is true, the file is closed before :c:func:`PyRun_FileExFlags`
    255    returns.
    256 
    257 
    258 .. c:function:: PyObject* Py_CompileString(const char *str, const char *filename, int start)
    259 
    260    This is a simplified interface to :c:func:`Py_CompileStringFlags` below, leaving
    261    *flags* set to *NULL*.
    262 
    263 
    264 .. c:function:: PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)
    265 
    266    This is a simplified interface to :c:func:`Py_CompileStringExFlags` below, with
    267    *optimize* set to ``-1``.
    268 
    269 
    270 .. c:function:: PyObject* Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)
    271 
    272    Parse and compile the Python source code in *str*, returning the resulting code
    273    object.  The start token is given by *start*; this can be used to constrain the
    274    code which can be compiled and should be :const:`Py_eval_input`,
    275    :const:`Py_file_input`, or :const:`Py_single_input`.  The filename specified by
    276    *filename* is used to construct the code object and may appear in tracebacks or
    277    :exc:`SyntaxError` exception messages.  This returns *NULL* if the code
    278    cannot be parsed or compiled.
    279 
    280    The integer *optimize* specifies the optimization level of the compiler; a
    281    value of ``-1`` selects the optimization level of the interpreter as given by
    282    :option:`-O` options.  Explicit levels are ``0`` (no optimization;
    283    ``__debug__`` is true), ``1`` (asserts are removed, ``__debug__`` is false)
    284    or ``2`` (docstrings are removed too).
    285 
    286    .. versionadded:: 3.4
    287 
    288 
    289 .. c:function:: PyObject* Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)
    290 
    291    Like :c:func:`Py_CompileStringObject`, but *filename* is a byte string
    292    decoded from the filesystem encoding (:func:`os.fsdecode`).
    293 
    294    .. versionadded:: 3.2
    295 
    296 .. c:function:: PyObject* PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)
    297 
    298    This is a simplified interface to :c:func:`PyEval_EvalCodeEx`, with just
    299    the code object, and global and local variables.  The other arguments are
    300    set to *NULL*.
    301 
    302 
    303 .. c:function:: PyObject* PyEval_EvalCodeEx(PyObject *co, PyObject *globals, PyObject *locals, PyObject **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *kwdefs, PyObject *closure)
    304 
    305    Evaluate a precompiled code object, given a particular environment for its
    306    evaluation.  This environment consists of a dictionary of global variables,
    307    a mapping object of local variables, arrays of arguments, keywords and
    308    defaults, a dictionary of default values for :ref:`keyword-only\
    309    <keyword-only_parameter>` arguments and a closure tuple of cells.
    310 
    311 
    312 .. c:type:: PyFrameObject
    313 
    314    The C structure of the objects used to describe frame objects. The
    315    fields of this type are subject to change at any time.
    316 
    317 
    318 .. c:function:: PyObject* PyEval_EvalFrame(PyFrameObject *f)
    319 
    320    Evaluate an execution frame.  This is a simplified interface to
    321    :c:func:`PyEval_EvalFrameEx`, for backward compatibility.
    322 
    323 
    324 .. c:function:: PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)
    325 
    326    This is the main, unvarnished function of Python interpretation.  It is
    327    literally 2000 lines long.  The code object associated with the execution
    328    frame *f* is executed, interpreting bytecode and executing calls as needed.
    329    The additional *throwflag* parameter can mostly be ignored - if true, then
    330    it causes an exception to immediately be thrown; this is used for the
    331    :meth:`~generator.throw` methods of generator objects.
    332 
    333    .. versionchanged:: 3.4
    334       This function now includes a debug assertion to help ensure that it
    335       does not silently discard an active exception.
    336 
    337 
    338 .. c:function:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)
    339 
    340    This function changes the flags of the current evaluation frame, and returns
    341    true on success, false on failure.
    342 
    343 
    344 .. c:var:: int Py_eval_input
    345 
    346    .. index:: single: Py_CompileString()
    347 
    348    The start symbol from the Python grammar for isolated expressions; for use with
    349    :c:func:`Py_CompileString`.
    350 
    351 
    352 .. c:var:: int Py_file_input
    353 
    354    .. index:: single: Py_CompileString()
    355 
    356    The start symbol from the Python grammar for sequences of statements as read
    357    from a file or other source; for use with :c:func:`Py_CompileString`.  This is
    358    the symbol to use when compiling arbitrarily long Python source code.
    359 
    360 
    361 .. c:var:: int Py_single_input
    362 
    363    .. index:: single: Py_CompileString()
    364 
    365    The start symbol from the Python grammar for a single statement; for use with
    366    :c:func:`Py_CompileString`. This is the symbol used for the interactive
    367    interpreter loop.
    368 
    369 
    370 .. c:type:: struct PyCompilerFlags
    371 
    372    This is the structure used to hold compiler flags.  In cases where code is only
    373    being compiled, it is passed as ``int flags``, and in cases where code is being
    374    executed, it is passed as ``PyCompilerFlags *flags``.  In this case, ``from
    375    __future__ import`` can modify *flags*.
    376 
    377    Whenever ``PyCompilerFlags *flags`` is *NULL*, :attr:`cf_flags` is treated as
    378    equal to ``0``, and any modification due to ``from __future__ import`` is
    379    discarded.  ::
    380 
    381       struct PyCompilerFlags {
    382           int cf_flags;
    383       }
    384 
    385 
    386 .. c:var:: int CO_FUTURE_DIVISION
    387 
    388    This bit can be set in *flags* to cause division operator ``/`` to be
    389    interpreted as "true division" according to :pep:`238`.
    390