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 | |
| 112 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 113 | .. c:function:: int PyRun_InteractiveOne(FILE *fp, const char *filename) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 114 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 115 | This is a simplified interface to :c:func:`PyRun_InteractiveOneFlags` below, |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 116 | leaving *flags* set to *NULL*. |
| 117 | |
| 118 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 119 | .. c:function:: int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 120 | |
Georg Brandl | 12c695c | 2010-10-17 11:03:22 +0000 | [diff] [blame] | 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 |
Victor Stinner | 00676d1 | 2010-12-27 01:49:31 +0000 | [diff] [blame] | 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 |
Georg Brandl | 12c695c | 2010-10-17 11:03:22 +0000 | [diff] [blame] | 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.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 131 | |
| 132 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 133 | .. c:function:: int PyRun_InteractiveLoop(FILE *fp, const char *filename) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 134 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 135 | This is a simplified interface to :c:func:`PyRun_InteractiveLoopFlags` below, |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 136 | leaving *flags* set to *NULL*. |
| 137 | |
| 138 | |
Georg Brandl | 12c695c | 2010-10-17 11:03:22 +0000 | [diff] [blame] | 139 | .. c:function:: int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 140 | |
| 141 | Read and execute statements from a file associated with an interactive device |
Georg Brandl | 12c695c | 2010-10-17 11:03:22 +0000 | [diff] [blame] | 142 | 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] | 143 | ``sys.ps2``. *filename* is decoded from the filesystem encoding |
| 144 | (:func:`sys.getfilesystemencoding`). Returns ``0`` at EOF. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 145 | |
| 146 | |
Andrew Kuchling | 1e170ba | 2013-05-28 21:48:28 -0400 | [diff] [blame^] | 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 *, 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 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 170 | .. c:function:: struct _node* PyParser_SimpleParseString(const char *str, int start) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 171 | |
| 172 | This is a simplified interface to |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 173 | :c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 174 | to *NULL* and *flags* set to ``0``. |
| 175 | |
| 176 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 177 | .. 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] | 178 | |
| 179 | This is a simplified interface to |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 180 | :c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 181 | to *NULL*. |
| 182 | |
| 183 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 184 | .. 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] | 185 | |
| 186 | Parse Python source code from *str* using the start token *start* according to |
| 187 | the *flags* argument. The result can be used to create a code object which can |
| 188 | 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] | 189 | many times. *filename* is decoded from the filesystem encoding |
| 190 | (:func:`sys.getfilesystemencoding`). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 191 | |
| 192 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 193 | .. 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] | 194 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 195 | This is a simplified interface to :c:func:`PyParser_SimpleParseFileFlags` below, |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 196 | leaving *flags* set to ``0`` |
| 197 | |
| 198 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 199 | .. 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] | 200 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 201 | Similar to :c:func:`PyParser_SimpleParseStringFlagsFilename`, but the Python |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 202 | source code is read from *fp* instead of an in-memory string. |
| 203 | |
| 204 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 205 | .. 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] | 206 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 207 | This is a simplified interface to :c:func:`PyRun_StringFlags` below, leaving |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 208 | *flags* set to *NULL*. |
| 209 | |
| 210 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 211 | .. 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] | 212 | |
| 213 | Execute Python source code from *str* in the context specified by the |
| 214 | dictionaries *globals* and *locals* with the compiler flags specified by |
| 215 | *flags*. The parameter *start* specifies the start token that should be used to |
| 216 | parse the source code. |
| 217 | |
| 218 | Returns the result of executing the code as a Python object, or *NULL* if an |
| 219 | exception was raised. |
| 220 | |
| 221 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 222 | .. 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] | 223 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 224 | This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 225 | *closeit* set to ``0`` and *flags* set to *NULL*. |
| 226 | |
| 227 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 228 | .. 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] | 229 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 230 | This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 231 | *flags* set to *NULL*. |
| 232 | |
| 233 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 234 | .. 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] | 235 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 236 | This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 237 | *closeit* set to ``0``. |
| 238 | |
| 239 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 240 | .. 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] | 241 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 242 | 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] | 243 | *fp* instead of an in-memory string. *filename* should be the name of the file, |
| 244 | it is decoded from the filesystem encoding (:func:`sys.getfilesystemencoding`). |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 245 | 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] | 246 | returns. |
| 247 | |
| 248 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 249 | .. 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] | 250 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 251 | This is a simplified interface to :c:func:`Py_CompileStringFlags` below, leaving |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 252 | *flags* set to *NULL*. |
| 253 | |
| 254 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 255 | .. 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] | 256 | |
Georg Brandl | 8334fd9 | 2010-12-04 10:26:46 +0000 | [diff] [blame] | 257 | This is a simplified interface to :c:func:`Py_CompileStringExFlags` below, with |
| 258 | *optimize* set to ``-1``. |
| 259 | |
| 260 | |
| 261 | .. c:function:: PyObject* Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize) |
| 262 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 263 | Parse and compile the Python source code in *str*, returning the resulting code |
| 264 | object. The start token is given by *start*; this can be used to constrain the |
| 265 | code which can be compiled and should be :const:`Py_eval_input`, |
| 266 | :const:`Py_file_input`, or :const:`Py_single_input`. The filename specified by |
| 267 | *filename* is used to construct the code object and may appear in tracebacks or |
Victor Stinner | 00676d1 | 2010-12-27 01:49:31 +0000 | [diff] [blame] | 268 | :exc:`SyntaxError` exception messages, it is decoded from the filesystem |
| 269 | encoding (:func:`sys.getfilesystemencoding`). This returns *NULL* if the |
| 270 | code cannot be parsed or compiled. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 271 | |
Georg Brandl | 8334fd9 | 2010-12-04 10:26:46 +0000 | [diff] [blame] | 272 | The integer *optimize* specifies the optimization level of the compiler; a |
| 273 | value of ``-1`` selects the optimization level of the interpreter as given by |
| 274 | :option:`-O` options. Explicit levels are ``0`` (no optimization; |
| 275 | ``__debug__`` is true), ``1`` (asserts are removed, ``__debug__`` is false) |
| 276 | or ``2`` (docstrings are removed too). |
| 277 | |
| 278 | .. versionadded:: 3.2 |
| 279 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 280 | |
Martin v. Löwis | 4d0d471 | 2010-12-03 20:14:31 +0000 | [diff] [blame] | 281 | .. c:function:: PyObject* PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals) |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 282 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 283 | This is a simplified interface to :c:func:`PyEval_EvalCodeEx`, with just |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 284 | the code object, and the dictionaries of global and local variables. |
| 285 | The other arguments are set to *NULL*. |
| 286 | |
| 287 | |
Martin v. Löwis | 4d0d471 | 2010-12-03 20:14:31 +0000 | [diff] [blame] | 288 | .. c:function:: PyObject* PyEval_EvalCodeEx(PyObject *co, PyObject *globals, PyObject *locals, PyObject **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *closure) |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 289 | |
| 290 | Evaluate a precompiled code object, given a particular environment for its |
| 291 | evaluation. This environment consists of dictionaries of global and local |
| 292 | variables, arrays of arguments, keywords and defaults, and a closure tuple of |
| 293 | cells. |
| 294 | |
| 295 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 296 | .. c:function:: PyObject* PyEval_EvalFrame(PyFrameObject *f) |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 297 | |
| 298 | Evaluate an execution frame. This is a simplified interface to |
| 299 | PyEval_EvalFrameEx, for backward compatibility. |
| 300 | |
| 301 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 302 | .. c:function:: PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag) |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 303 | |
| 304 | This is the main, unvarnished function of Python interpretation. It is |
| 305 | literally 2000 lines long. The code object associated with the execution |
| 306 | frame *f* is executed, interpreting bytecode and executing calls as needed. |
| 307 | The additional *throwflag* parameter can mostly be ignored - if true, then |
| 308 | it causes an exception to immediately be thrown; this is used for the |
| 309 | :meth:`throw` methods of generator objects. |
| 310 | |
| 311 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 312 | .. c:function:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf) |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 313 | |
| 314 | This function changes the flags of the current evaluation frame, and returns |
| 315 | true on success, false on failure. |
| 316 | |
| 317 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 318 | .. c:var:: int Py_eval_input |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 319 | |
| 320 | .. index:: single: Py_CompileString() |
| 321 | |
| 322 | 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] | 323 | :c:func:`Py_CompileString`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 324 | |
| 325 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 326 | .. c:var:: int Py_file_input |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 327 | |
| 328 | .. index:: single: Py_CompileString() |
| 329 | |
| 330 | 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] | 331 | 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] | 332 | the symbol to use when compiling arbitrarily long Python source code. |
| 333 | |
| 334 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 335 | .. c:var:: int Py_single_input |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 336 | |
| 337 | .. index:: single: Py_CompileString() |
| 338 | |
| 339 | 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] | 340 | :c:func:`Py_CompileString`. This is the symbol used for the interactive |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 341 | interpreter loop. |
| 342 | |
| 343 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 344 | .. c:type:: struct PyCompilerFlags |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 345 | |
| 346 | This is the structure used to hold compiler flags. In cases where code is only |
| 347 | being compiled, it is passed as ``int flags``, and in cases where code is being |
| 348 | executed, it is passed as ``PyCompilerFlags *flags``. In this case, ``from |
| 349 | __future__ import`` can modify *flags*. |
| 350 | |
| 351 | Whenever ``PyCompilerFlags *flags`` is *NULL*, :attr:`cf_flags` is treated as |
| 352 | equal to ``0``, and any modification due to ``from __future__ import`` is |
| 353 | discarded. :: |
| 354 | |
| 355 | struct PyCompilerFlags { |
| 356 | int cf_flags; |
| 357 | } |
| 358 | |
| 359 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 360 | .. c:var:: int CO_FUTURE_DIVISION |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 361 | |
| 362 | This bit can be set in *flags* to cause division operator ``/`` to be |
| 363 | interpreted as "true division" according to :pep:`238`. |