Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 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` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 23 | use different libraries, so care should be taken that :c:type:`FILE\*` parameters |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 28 | .. c:function:: int Py_Main(int argc, wchar_t **argv) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 29 | |
Georg Brandl | 521143d | 2011-05-15 17:51:24 +0200 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 39 | |
Georg Brandl | 0b2489e | 2011-05-15 08:49:12 +0200 | [diff] [blame] | 40 | Note that if an otherwise unhandled :exc:`SystemExit` is raised, this |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 41 | function will not return ``1``, but exit the process, as long as |
| 42 | ``Py_InspectFlag`` is not set. |
| 43 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 44 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 45 | .. c:function:: int PyRun_AnyFile(FILE *fp, const char *filename) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 46 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 47 | This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 48 | *closeit* set to ``0`` and *flags* set to *NULL*. |
| 49 | |
| 50 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 51 | .. c:function:: int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 52 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 53 | This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 54 | the *closeit* argument set to ``0``. |
| 55 | |
| 56 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 57 | .. c:function:: int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 58 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 59 | This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 60 | the *flags* argument set to *NULL*. |
| 61 | |
| 62 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 63 | .. c:function:: int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 67 | :c:func:`PyRun_InteractiveLoop`, otherwise return the result of |
Victor Stinner | 00676d1 | 2010-12-27 01:49:31 +0000 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 71 | |
| 72 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 73 | .. c:function:: int PyRun_SimpleString(const char *command) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 74 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 75 | This is a simplified interface to :c:func:`PyRun_SimpleStringFlags` below, |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 76 | leaving the *PyCompilerFlags\** argument set to NULL. |
| 77 | |
| 78 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 79 | .. c:function:: int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 0b2489e | 2011-05-15 08:49:12 +0200 | [diff] [blame] | 87 | Note that if an otherwise unhandled :exc:`SystemExit` is raised, this |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 88 | function will not return ``-1``, but exit the process, as long as |
| 89 | ``Py_InspectFlag`` is not set. |
| 90 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 91 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 92 | .. c:function:: int PyRun_SimpleFile(FILE *fp, const char *filename) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 93 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 94 | This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below, |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 95 | leaving *closeit* set to ``0`` and *flags* set to *NULL*. |
| 96 | |
| 97 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 98 | .. c:function:: int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 99 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 100 | This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below, |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 101 | leaving *flags* set to *NULL*. |
| 102 | |
| 103 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 104 | .. c:function:: int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 105 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 106 | Similar to :c:func:`PyRun_SimpleStringFlags`, but the Python source code is read |
Victor Stinner | 00676d1 | 2010-12-27 01:49:31 +0000 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 111 | |
Inada Naoki | 10654c1 | 2019-04-01 18:35:20 +0900 | [diff] [blame^] | 112 | .. note:: |
| 113 | On Windows, *fp* should be opened as binary mode (e.g. ``fopen(filename, "rb")``. |
| 114 | Otherwise, Python may not handle script file with LF line ending correctly. |
| 115 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 116 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 117 | .. c:function:: int PyRun_InteractiveOne(FILE *fp, const char *filename) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 118 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 119 | This is a simplified interface to :c:func:`PyRun_InteractiveOneFlags` below, |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 120 | leaving *flags* set to *NULL*. |
| 121 | |
| 122 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 123 | .. c:function:: int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 124 | |
Georg Brandl | 12c695c | 2010-10-17 11:03:22 +0000 | [diff] [blame] | 125 | Read and execute a single statement from a file associated with an |
| 126 | interactive device according to the *flags* argument. The user will be |
Victor Stinner | 00676d1 | 2010-12-27 01:49:31 +0000 | [diff] [blame] | 127 | prompted using ``sys.ps1`` and ``sys.ps2``. *filename* is decoded from the |
| 128 | filesystem encoding (:func:`sys.getfilesystemencoding`). |
| 129 | |
| 130 | Returns ``0`` when the input was |
Georg Brandl | 12c695c | 2010-10-17 11:03:22 +0000 | [diff] [blame] | 131 | executed successfully, ``-1`` if there was an exception, or an error code |
| 132 | from the :file:`errcode.h` include file distributed as part of Python if |
| 133 | there was a parse error. (Note that :file:`errcode.h` is not included by |
| 134 | :file:`Python.h`, so must be included specifically if needed.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 135 | |
| 136 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 137 | .. c:function:: int PyRun_InteractiveLoop(FILE *fp, const char *filename) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 138 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 139 | This is a simplified interface to :c:func:`PyRun_InteractiveLoopFlags` below, |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 140 | leaving *flags* set to *NULL*. |
| 141 | |
| 142 | |
Georg Brandl | 12c695c | 2010-10-17 11:03:22 +0000 | [diff] [blame] | 143 | .. c:function:: int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 144 | |
| 145 | Read and execute statements from a file associated with an interactive device |
Georg Brandl | 12c695c | 2010-10-17 11:03:22 +0000 | [diff] [blame] | 146 | until EOF is reached. The user will be prompted using ``sys.ps1`` and |
Victor Stinner | 00676d1 | 2010-12-27 01:49:31 +0000 | [diff] [blame] | 147 | ``sys.ps2``. *filename* is decoded from the filesystem encoding |
xdegaye | e0582a3 | 2017-11-12 16:50:48 +0100 | [diff] [blame] | 148 | (:func:`sys.getfilesystemencoding`). Returns ``0`` at EOF or a negative |
| 149 | number upon failure. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 150 | |
| 151 | |
Andrew Kuchling | 1e170ba | 2013-05-28 21:48:28 -0400 | [diff] [blame] | 152 | .. c:var:: int (*PyOS_InputHook)(void) |
| 153 | |
| 154 | Can be set to point to a function with the prototype |
| 155 | ``int func(void)``. The function will be called when Python's |
| 156 | interpreter prompt is about to become idle and wait for user input |
| 157 | from the terminal. The return value is ignored. Overriding this |
| 158 | hook can be used to integrate the interpreter's prompt with other |
| 159 | event loops, as done in the :file:`Modules/_tkinter.c` in the |
| 160 | Python source code. |
| 161 | |
| 162 | |
Serhiy Storchaka | c679227 | 2013-10-19 21:03:34 +0300 | [diff] [blame] | 163 | .. c:var:: char* (*PyOS_ReadlineFunctionPointer)(FILE *, FILE *, const char *) |
Andrew Kuchling | 1e170ba | 2013-05-28 21:48:28 -0400 | [diff] [blame] | 164 | |
| 165 | Can be set to point to a function with the prototype |
| 166 | ``char *func(FILE *stdin, FILE *stdout, char *prompt)``, |
| 167 | overriding the default function used to read a single line of input |
| 168 | at the interpreter's prompt. The function is expected to output |
| 169 | the string *prompt* if it's not *NULL*, and then read a line of |
| 170 | input from the provided standard input file, returning the |
| 171 | resulting string. For example, The :mod:`readline` module sets |
| 172 | this hook to provide line-editing and tab-completion features. |
| 173 | |
Victor Stinner | 2fe9bac | 2013-10-10 16:18:20 +0200 | [diff] [blame] | 174 | The result must be a string allocated by :c:func:`PyMem_RawMalloc` or |
| 175 | :c:func:`PyMem_RawRealloc`, or *NULL* if an error occurred. |
| 176 | |
| 177 | .. versionchanged:: 3.4 |
| 178 | The result must be allocated by :c:func:`PyMem_RawMalloc` or |
| 179 | :c:func:`PyMem_RawRealloc`, instead of being allocated by |
| 180 | :c:func:`PyMem_Malloc` or :c:func:`PyMem_Realloc`. |
| 181 | |
Andrew Kuchling | 1e170ba | 2013-05-28 21:48:28 -0400 | [diff] [blame] | 182 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 183 | .. c:function:: struct _node* PyParser_SimpleParseString(const char *str, int start) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 184 | |
| 185 | This is a simplified interface to |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 186 | :c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 187 | to *NULL* and *flags* set to ``0``. |
| 188 | |
| 189 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 190 | .. c:function:: struct _node* PyParser_SimpleParseStringFlags( const char *str, int start, int flags) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 191 | |
| 192 | This is a simplified interface to |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 193 | :c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 194 | to *NULL*. |
| 195 | |
| 196 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 197 | .. c:function:: struct _node* PyParser_SimpleParseStringFlagsFilename( const char *str, const char *filename, int start, int flags) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 198 | |
| 199 | Parse Python source code from *str* using the start token *start* according to |
| 200 | the *flags* argument. The result can be used to create a code object which can |
| 201 | be evaluated efficiently. This is useful if a code fragment must be evaluated |
Victor Stinner | 00676d1 | 2010-12-27 01:49:31 +0000 | [diff] [blame] | 202 | many times. *filename* is decoded from the filesystem encoding |
| 203 | (:func:`sys.getfilesystemencoding`). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 204 | |
| 205 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 206 | .. c:function:: struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 207 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 208 | This is a simplified interface to :c:func:`PyParser_SimpleParseFileFlags` below, |
Martin Panter | d21e0b5 | 2015-10-10 10:36:22 +0000 | [diff] [blame] | 209 | leaving *flags* set to ``0``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 210 | |
| 211 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 212 | .. c:function:: struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 213 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 214 | Similar to :c:func:`PyParser_SimpleParseStringFlagsFilename`, but the Python |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 215 | source code is read from *fp* instead of an in-memory string. |
| 216 | |
| 217 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 218 | .. c:function:: PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 219 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 220 | This is a simplified interface to :c:func:`PyRun_StringFlags` below, leaving |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 221 | *flags* set to *NULL*. |
| 222 | |
| 223 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 224 | .. c:function:: PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 225 | |
| 226 | Execute Python source code from *str* in the context specified by the |
Berker Peksag | bd66435 | 2016-08-13 05:37:49 +0300 | [diff] [blame] | 227 | objects *globals* and *locals* with the compiler flags specified by |
| 228 | *flags*. *globals* must be a dictionary; *locals* can be any object |
| 229 | that implements the mapping protocol. The parameter *start* specifies |
| 230 | the start token that should be used to parse the source code. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 231 | |
| 232 | Returns the result of executing the code as a Python object, or *NULL* if an |
| 233 | exception was raised. |
| 234 | |
| 235 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 236 | .. c:function:: PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 237 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 238 | This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 239 | *closeit* set to ``0`` and *flags* set to *NULL*. |
| 240 | |
| 241 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 242 | .. c:function:: PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 243 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 244 | This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 245 | *flags* set to *NULL*. |
| 246 | |
| 247 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 248 | .. c:function:: PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 249 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 250 | This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 251 | *closeit* set to ``0``. |
| 252 | |
| 253 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 254 | .. c:function:: PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 255 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 256 | Similar to :c:func:`PyRun_StringFlags`, but the Python source code is read from |
Victor Stinner | 00676d1 | 2010-12-27 01:49:31 +0000 | [diff] [blame] | 257 | *fp* instead of an in-memory string. *filename* should be the name of the file, |
| 258 | it is decoded from the filesystem encoding (:func:`sys.getfilesystemencoding`). |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 259 | If *closeit* is true, the file is closed before :c:func:`PyRun_FileExFlags` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 260 | returns. |
| 261 | |
| 262 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 263 | .. c:function:: PyObject* Py_CompileString(const char *str, const char *filename, int start) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 264 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 265 | This is a simplified interface to :c:func:`Py_CompileStringFlags` below, leaving |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 266 | *flags* set to *NULL*. |
| 267 | |
| 268 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 269 | .. c:function:: PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 270 | |
Georg Brandl | 8334fd9 | 2010-12-04 10:26:46 +0000 | [diff] [blame] | 271 | This is a simplified interface to :c:func:`Py_CompileStringExFlags` below, with |
| 272 | *optimize* set to ``-1``. |
| 273 | |
| 274 | |
Victor Stinner | 14e461d | 2013-08-26 22:28:21 +0200 | [diff] [blame] | 275 | .. c:function:: PyObject* Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize) |
Georg Brandl | 8334fd9 | 2010-12-04 10:26:46 +0000 | [diff] [blame] | 276 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 277 | Parse and compile the Python source code in *str*, returning the resulting code |
| 278 | object. The start token is given by *start*; this can be used to constrain the |
| 279 | code which can be compiled and should be :const:`Py_eval_input`, |
| 280 | :const:`Py_file_input`, or :const:`Py_single_input`. The filename specified by |
| 281 | *filename* is used to construct the code object and may appear in tracebacks or |
Victor Stinner | 14e461d | 2013-08-26 22:28:21 +0200 | [diff] [blame] | 282 | :exc:`SyntaxError` exception messages. This returns *NULL* if the code |
| 283 | cannot be parsed or compiled. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 284 | |
Georg Brandl | 8334fd9 | 2010-12-04 10:26:46 +0000 | [diff] [blame] | 285 | The integer *optimize* specifies the optimization level of the compiler; a |
| 286 | value of ``-1`` selects the optimization level of the interpreter as given by |
| 287 | :option:`-O` options. Explicit levels are ``0`` (no optimization; |
| 288 | ``__debug__`` is true), ``1`` (asserts are removed, ``__debug__`` is false) |
| 289 | or ``2`` (docstrings are removed too). |
| 290 | |
Victor Stinner | 14e461d | 2013-08-26 22:28:21 +0200 | [diff] [blame] | 291 | .. versionadded:: 3.4 |
Georg Brandl | 8334fd9 | 2010-12-04 10:26:46 +0000 | [diff] [blame] | 292 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 293 | |
Victor Stinner | 14e461d | 2013-08-26 22:28:21 +0200 | [diff] [blame] | 294 | .. c:function:: PyObject* Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize) |
| 295 | |
Berker Peksag | ab39b09 | 2016-09-28 19:35:25 +0300 | [diff] [blame] | 296 | Like :c:func:`Py_CompileStringObject`, but *filename* is a byte string |
Victor Stinner | 14e461d | 2013-08-26 22:28:21 +0200 | [diff] [blame] | 297 | decoded from the filesystem encoding (:func:`os.fsdecode`). |
| 298 | |
| 299 | .. versionadded:: 3.2 |
| 300 | |
Martin v. Löwis | 4d0d471 | 2010-12-03 20:14:31 +0000 | [diff] [blame] | 301 | .. c:function:: PyObject* PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals) |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 302 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 303 | This is a simplified interface to :c:func:`PyEval_EvalCodeEx`, with just |
Berker Peksag | bd66435 | 2016-08-13 05:37:49 +0300 | [diff] [blame] | 304 | the code object, and global and local variables. The other arguments are |
| 305 | set to *NULL*. |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 306 | |
| 307 | |
Serhiy Storchaka | a5552f0 | 2017-12-15 13:11:11 +0200 | [diff] [blame] | 308 | .. c:function:: PyObject* PyEval_EvalCodeEx(PyObject *co, PyObject *globals, PyObject *locals, PyObject *const *args, int argcount, PyObject *const *kws, int kwcount, PyObject *const *defs, int defcount, PyObject *kwdefs, PyObject *closure) |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 309 | |
| 310 | Evaluate a precompiled code object, given a particular environment for its |
Berker Peksag | bd66435 | 2016-08-13 05:37:49 +0300 | [diff] [blame] | 311 | evaluation. This environment consists of a dictionary of global variables, |
| 312 | a mapping object of local variables, arrays of arguments, keywords and |
Serhiy Storchaka | 3f819ca | 2018-10-31 02:26:06 +0200 | [diff] [blame] | 313 | defaults, a dictionary of default values for :ref:`keyword-only |
Xiang Zhang | 6ad85bf | 2017-01-20 11:29:11 +0800 | [diff] [blame] | 314 | <keyword-only_parameter>` arguments and a closure tuple of cells. |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 315 | |
| 316 | |
Brett Cannon | abf797d | 2016-04-15 12:43:50 -0700 | [diff] [blame] | 317 | .. c:type:: PyFrameObject |
| 318 | |
| 319 | The C structure of the objects used to describe frame objects. The |
| 320 | fields of this type are subject to change at any time. |
| 321 | |
| 322 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 323 | .. c:function:: PyObject* PyEval_EvalFrame(PyFrameObject *f) |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 324 | |
| 325 | Evaluate an execution frame. This is a simplified interface to |
Brett Cannon | abf797d | 2016-04-15 12:43:50 -0700 | [diff] [blame] | 326 | :c:func:`PyEval_EvalFrameEx`, for backward compatibility. |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 327 | |
| 328 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 329 | .. c:function:: PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag) |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 330 | |
| 331 | This is the main, unvarnished function of Python interpretation. It is |
| 332 | literally 2000 lines long. The code object associated with the execution |
| 333 | frame *f* is executed, interpreting bytecode and executing calls as needed. |
| 334 | The additional *throwflag* parameter can mostly be ignored - if true, then |
| 335 | it causes an exception to immediately be thrown; this is used for the |
Serhiy Storchaka | 0b68a2d | 2013-10-09 13:26:17 +0300 | [diff] [blame] | 336 | :meth:`~generator.throw` methods of generator objects. |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 337 | |
Nick Coghlan | c0bc0b4 | 2014-02-09 12:00:01 +1000 | [diff] [blame] | 338 | .. versionchanged:: 3.4 |
| 339 | This function now includes a debug assertion to help ensure that it |
| 340 | does not silently discard an active exception. |
| 341 | |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 342 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 343 | .. c:function:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf) |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 344 | |
| 345 | This function changes the flags of the current evaluation frame, and returns |
| 346 | true on success, false on failure. |
| 347 | |
| 348 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 349 | .. c:var:: int Py_eval_input |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 350 | |
| 351 | .. index:: single: Py_CompileString() |
| 352 | |
| 353 | The start symbol from the Python grammar for isolated expressions; for use with |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 354 | :c:func:`Py_CompileString`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 355 | |
| 356 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 357 | .. c:var:: int Py_file_input |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 358 | |
| 359 | .. index:: single: Py_CompileString() |
| 360 | |
| 361 | The start symbol from the Python grammar for sequences of statements as read |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 362 | from a file or other source; for use with :c:func:`Py_CompileString`. This is |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 363 | the symbol to use when compiling arbitrarily long Python source code. |
| 364 | |
| 365 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 366 | .. c:var:: int Py_single_input |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 367 | |
| 368 | .. index:: single: Py_CompileString() |
| 369 | |
| 370 | The start symbol from the Python grammar for a single statement; for use with |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 371 | :c:func:`Py_CompileString`. This is the symbol used for the interactive |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 372 | interpreter loop. |
| 373 | |
| 374 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 375 | .. c:type:: struct PyCompilerFlags |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 376 | |
| 377 | This is the structure used to hold compiler flags. In cases where code is only |
| 378 | being compiled, it is passed as ``int flags``, and in cases where code is being |
| 379 | executed, it is passed as ``PyCompilerFlags *flags``. In this case, ``from |
| 380 | __future__ import`` can modify *flags*. |
| 381 | |
| 382 | Whenever ``PyCompilerFlags *flags`` is *NULL*, :attr:`cf_flags` is treated as |
| 383 | equal to ``0``, and any modification due to ``from __future__ import`` is |
| 384 | discarded. :: |
| 385 | |
| 386 | struct PyCompilerFlags { |
| 387 | int cf_flags; |
| 388 | } |
| 389 | |
| 390 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 391 | .. c:var:: int CO_FUTURE_DIVISION |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 392 | |
| 393 | This bit can be set in *flags* to cause division operator ``/`` to be |
| 394 | interpreted as "true division" according to :pep:`238`. |