/Doc/c-api/veryhigh.rst

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