diff options
Diffstat (limited to 'Doc/c-api/veryhigh.rst')
| -rw-r--r-- | Doc/c-api/veryhigh.rst | 181 |
1 files changed, 102 insertions, 79 deletions
diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst index 66789a9..26e0716 100644 --- a/Doc/c-api/veryhigh.rst +++ b/Doc/c-api/veryhigh.rst @@ -16,21 +16,21 @@ parameter. The available start symbols are :const:`Py_eval_input`, :const:`Py_file_input`, and :const:`Py_single_input`. These are described following the functions which accept them as parameters. -Note also that several of these functions take :ctype:`FILE\*` parameters. One -particular issue which needs to be handled carefully is that the :ctype:`FILE` +Note also that several of these functions take :c:type:`FILE\*` parameters. One +particular issue which needs to be handled carefully is that the :c:type:`FILE` structure for different C libraries can be different and incompatible. Under Windows (at least), it is possible for dynamically linked extensions to actually -use different libraries, so care should be taken that :ctype:`FILE\*` parameters +use different libraries, so care should be taken that :c:type:`FILE\*` parameters are only passed to these functions if it is certain that they were created by the same library that the Python runtime is using. -.. cfunction:: int Py_Main(int argc, wchar_t **argv) +.. c:function:: int Py_Main(int argc, wchar_t **argv) The main program for the standard interpreter. This is made available for programs which embed Python. The *argc* and *argv* parameters should be prepared exactly as those which are passed to - a C program's :cfunc:`main` function (converted to wchar_t + a C program's :c:func:`main` function (converted to wchar_t according to the user's locale). It is important to note that the argument list may be modified (but the contents of the strings pointed to by the argument list are not). The return value will be @@ -43,40 +43,41 @@ the same library that the Python runtime is using. ``Py_InspectFlag`` is not set. -.. cfunction:: int PyRun_AnyFile(FILE *fp, const char *filename) +.. c:function:: int PyRun_AnyFile(FILE *fp, const char *filename) - This is a simplified interface to :cfunc:`PyRun_AnyFileExFlags` below, leaving + This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving *closeit* set to ``0`` and *flags* set to *NULL*. -.. cfunction:: int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags) +.. c:function:: int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags) - This is a simplified interface to :cfunc:`PyRun_AnyFileExFlags` below, leaving + This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving the *closeit* argument set to ``0``. -.. cfunction:: int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit) +.. c:function:: int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit) - This is a simplified interface to :cfunc:`PyRun_AnyFileExFlags` below, leaving + This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving the *flags* argument set to *NULL*. -.. cfunction:: int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags) +.. c:function:: int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags) If *fp* refers to a file associated with an interactive device (console or terminal input or Unix pseudo-terminal), return the value of - :cfunc:`PyRun_InteractiveLoop`, otherwise return the result of - :cfunc:`PyRun_SimpleFile`. If *filename* is *NULL*, this function uses - ``"???"`` as the filename. + :c:func:`PyRun_InteractiveLoop`, otherwise return the result of + :c:func:`PyRun_SimpleFile`. *filename* is decoded from the filesystem + encoding (:func:`sys.getfilesystemencoding`). If *filename* is *NULL*, this + function uses ``"???"`` as the filename. -.. cfunction:: int PyRun_SimpleString(const char *command) +.. c:function:: int PyRun_SimpleString(const char *command) - This is a simplified interface to :cfunc:`PyRun_SimpleStringFlags` below, + This is a simplified interface to :c:func:`PyRun_SimpleStringFlags` below, leaving the *PyCompilerFlags\** argument set to NULL. -.. cfunction:: int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags) +.. c:function:: int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags) Executes the Python source code from *command* in the :mod:`__main__` module according to the *flags* argument. If :mod:`__main__` does not already exist, it @@ -89,103 +90,109 @@ the same library that the Python runtime is using. ``Py_InspectFlag`` is not set. -.. cfunction:: int PyRun_SimpleFile(FILE *fp, const char *filename) +.. c:function:: int PyRun_SimpleFile(FILE *fp, const char *filename) - This is a simplified interface to :cfunc:`PyRun_SimpleFileExFlags` below, + This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below, leaving *closeit* set to ``0`` and *flags* set to *NULL*. -.. cfunction:: int PyRun_SimpleFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags) +.. c:function:: int PyRun_SimpleFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags) - This is a simplified interface to :cfunc:`PyRun_SimpleFileExFlags` below, + This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below, leaving *closeit* set to ``0``. -.. cfunction:: int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit) +.. c:function:: int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit) - This is a simplified interface to :cfunc:`PyRun_SimpleFileExFlags` below, + This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below, leaving *flags* set to *NULL*. -.. cfunction:: int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags) +.. c:function:: int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags) - Similar to :cfunc:`PyRun_SimpleStringFlags`, but the Python source code is read - from *fp* instead of an in-memory string. *filename* should be the name of the - file. If *closeit* is true, the file is closed before PyRun_SimpleFileExFlags - returns. + Similar to :c:func:`PyRun_SimpleStringFlags`, but the Python source code is read + from *fp* instead of an in-memory string. *filename* should be the name of + the file, it is decoded from the filesystem encoding + (:func:`sys.getfilesystemencoding`). If *closeit* is true, the file is + closed before PyRun_SimpleFileExFlags returns. -.. cfunction:: int PyRun_InteractiveOne(FILE *fp, const char *filename) +.. c:function:: int PyRun_InteractiveOne(FILE *fp, const char *filename) - This is a simplified interface to :cfunc:`PyRun_InteractiveOneFlags` below, + This is a simplified interface to :c:func:`PyRun_InteractiveOneFlags` below, leaving *flags* set to *NULL*. -.. cfunction:: int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags) +.. c:function:: int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags) Read and execute a single statement from a file associated with an interactive device according to the *flags* argument. The user will be - prompted using ``sys.ps1`` and ``sys.ps2``. Returns ``0`` when the input was + prompted using ``sys.ps1`` and ``sys.ps2``. *filename* is decoded from the + filesystem encoding (:func:`sys.getfilesystemencoding`). + + Returns ``0`` when the input was executed successfully, ``-1`` if there was an exception, or an error code from the :file:`errcode.h` include file distributed as part of Python if there was a parse error. (Note that :file:`errcode.h` is not included by :file:`Python.h`, so must be included specifically if needed.) -.. cfunction:: int PyRun_InteractiveLoop(FILE *fp, const char *filename) +.. c:function:: int PyRun_InteractiveLoop(FILE *fp, const char *filename) - This is a simplified interface to :cfunc:`PyRun_InteractiveLoopFlags` below, + This is a simplified interface to :c:func:`PyRun_InteractiveLoopFlags` below, leaving *flags* set to *NULL*. -.. cfunction:: int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags) +.. c:function:: int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags) Read and execute statements from a file associated with an interactive device until EOF is reached. The user will be prompted using ``sys.ps1`` and - ``sys.ps2``. Returns ``0`` at EOF. + ``sys.ps2``. *filename* is decoded from the filesystem encoding + (:func:`sys.getfilesystemencoding`). Returns ``0`` at EOF. -.. cfunction:: struct _node* PyParser_SimpleParseString(const char *str, int start) +.. c:function:: struct _node* PyParser_SimpleParseString(const char *str, int start) This is a simplified interface to - :cfunc:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set + :c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set to *NULL* and *flags* set to ``0``. -.. cfunction:: struct _node* PyParser_SimpleParseStringFlags( const char *str, int start, int flags) +.. c:function:: struct _node* PyParser_SimpleParseStringFlags( const char *str, int start, int flags) This is a simplified interface to - :cfunc:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set + :c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set to *NULL*. -.. cfunction:: struct _node* PyParser_SimpleParseStringFlagsFilename( const char *str, const char *filename, int start, int flags) +.. c:function:: struct _node* PyParser_SimpleParseStringFlagsFilename( const char *str, const char *filename, int start, int flags) Parse Python source code from *str* using the start token *start* according to the *flags* argument. The result can be used to create a code object which can be evaluated efficiently. This is useful if a code fragment must be evaluated - many times. + many times. *filename* is decoded from the filesystem encoding + (:func:`sys.getfilesystemencoding`). -.. cfunction:: struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start) +.. c:function:: struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start) - This is a simplified interface to :cfunc:`PyParser_SimpleParseFileFlags` below, + This is a simplified interface to :c:func:`PyParser_SimpleParseFileFlags` below, leaving *flags* set to ``0`` -.. cfunction:: struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags) +.. c:function:: struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags) - Similar to :cfunc:`PyParser_SimpleParseStringFlagsFilename`, but the Python + Similar to :c:func:`PyParser_SimpleParseStringFlagsFilename`, but the Python source code is read from *fp* instead of an in-memory string. -.. cfunction:: PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals) +.. c:function:: PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals) - This is a simplified interface to :cfunc:`PyRun_StringFlags` below, leaving + This is a simplified interface to :c:func:`PyRun_StringFlags` below, leaving *flags* set to *NULL*. -.. cfunction:: PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags) +.. c:function:: PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags) Execute Python source code from *str* in the context specified by the dictionaries *globals* and *locals* with the compiler flags specified by @@ -196,57 +203,73 @@ the same library that the Python runtime is using. exception was raised. -.. cfunction:: PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals) +.. c:function:: PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals) - This is a simplified interface to :cfunc:`PyRun_FileExFlags` below, leaving + This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving *closeit* set to ``0`` and *flags* set to *NULL*. -.. cfunction:: PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit) +.. c:function:: PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit) - This is a simplified interface to :cfunc:`PyRun_FileExFlags` below, leaving + This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving *flags* set to *NULL*. -.. cfunction:: PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags) +.. c:function:: PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags) - This is a simplified interface to :cfunc:`PyRun_FileExFlags` below, leaving + This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving *closeit* set to ``0``. -.. cfunction:: PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags) +.. c:function:: PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags) - Similar to :cfunc:`PyRun_StringFlags`, but the Python source code is read from - *fp* instead of an in-memory string. *filename* should be the name of the file. - If *closeit* is true, the file is closed before :cfunc:`PyRun_FileExFlags` + Similar to :c:func:`PyRun_StringFlags`, but the Python source code is read from + *fp* instead of an in-memory string. *filename* should be the name of the file, + it is decoded from the filesystem encoding (:func:`sys.getfilesystemencoding`). + If *closeit* is true, the file is closed before :c:func:`PyRun_FileExFlags` returns. -.. cfunction:: PyObject* Py_CompileString(const char *str, const char *filename, int start) +.. c:function:: PyObject* Py_CompileString(const char *str, const char *filename, int start) - This is a simplified interface to :cfunc:`Py_CompileStringFlags` below, leaving + This is a simplified interface to :c:func:`Py_CompileStringFlags` below, leaving *flags* set to *NULL*. -.. cfunction:: PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags) +.. c:function:: PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags) + + This is a simplified interface to :c:func:`Py_CompileStringExFlags` below, with + *optimize* set to ``-1``. + + +.. c:function:: PyObject* Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize) Parse and compile the Python source code in *str*, returning the resulting code object. The start token is given by *start*; this can be used to constrain the code which can be compiled and should be :const:`Py_eval_input`, :const:`Py_file_input`, or :const:`Py_single_input`. The filename specified by *filename* is used to construct the code object and may appear in tracebacks or - :exc:`SyntaxError` exception messages. This returns *NULL* if the code cannot - be parsed or compiled. + :exc:`SyntaxError` exception messages, it is decoded from the filesystem + encoding (:func:`sys.getfilesystemencoding`). This returns *NULL* if the + code cannot be parsed or compiled. + + The integer *optimize* specifies the optimization level of the compiler; a + value of ``-1`` selects the optimization level of the interpreter as given by + :option:`-O` options. Explicit levels are ``0`` (no optimization; + ``__debug__`` is true), ``1`` (asserts are removed, ``__debug__`` is false) + or ``2`` (docstrings are removed too). + + .. versionadded:: 3.2 -.. cfunction:: PyObject* PyEval_EvalCode(PyCodeObject *co, PyObject *globals, PyObject *locals) +.. c:function:: PyObject* PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals) - This is a simplified interface to :cfunc:`PyEval_EvalCodeEx`, with just + This is a simplified interface to :c:func:`PyEval_EvalCodeEx`, with just the code object, and the dictionaries of global and local variables. The other arguments are set to *NULL*. -.. cfunction:: PyObject* PyEval_EvalCodeEx(PyCodeObject *co, PyObject *globals, PyObject *locals, PyObject **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *closure) +.. 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) Evaluate a precompiled code object, given a particular environment for its evaluation. This environment consists of dictionaries of global and local @@ -254,13 +277,13 @@ the same library that the Python runtime is using. cells. -.. cfunction:: PyObject* PyEval_EvalFrame(PyFrameObject *f) +.. c:function:: PyObject* PyEval_EvalFrame(PyFrameObject *f) Evaluate an execution frame. This is a simplified interface to PyEval_EvalFrameEx, for backward compatibility. -.. cfunction:: PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag) +.. c:function:: PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag) This is the main, unvarnished function of Python interpretation. It is literally 2000 lines long. The code object associated with the execution @@ -270,39 +293,39 @@ the same library that the Python runtime is using. :meth:`throw` methods of generator objects. -.. cfunction:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf) +.. c:function:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf) This function changes the flags of the current evaluation frame, and returns true on success, false on failure. -.. cvar:: int Py_eval_input +.. c:var:: int Py_eval_input .. index:: single: Py_CompileString() The start symbol from the Python grammar for isolated expressions; for use with - :cfunc:`Py_CompileString`. + :c:func:`Py_CompileString`. -.. cvar:: int Py_file_input +.. c:var:: int Py_file_input .. index:: single: Py_CompileString() The start symbol from the Python grammar for sequences of statements as read - from a file or other source; for use with :cfunc:`Py_CompileString`. This is + from a file or other source; for use with :c:func:`Py_CompileString`. This is the symbol to use when compiling arbitrarily long Python source code. -.. cvar:: int Py_single_input +.. c:var:: int Py_single_input .. index:: single: Py_CompileString() The start symbol from the Python grammar for a single statement; for use with - :cfunc:`Py_CompileString`. This is the symbol used for the interactive + :c:func:`Py_CompileString`. This is the symbol used for the interactive interpreter loop. -.. ctype:: struct PyCompilerFlags +.. c:type:: struct PyCompilerFlags This is the structure used to hold compiler flags. In cases where code is only being compiled, it is passed as ``int flags``, and in cases where code is being @@ -318,7 +341,7 @@ the same library that the Python runtime is using. } -.. cvar:: int CO_FUTURE_DIVISION +.. c:var:: int CO_FUTURE_DIVISION This bit can be set in *flags* to cause division operator ``/`` to be interpreted as "true division" according to :pep:`238`. |