Changeset 391 for python/trunk/Doc/c-api/veryhigh.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/c-api/veryhigh.rst (modified) (11 diffs)

python/trunk/Doc/c-api/veryhigh.rst

@@ -17 +17 @@
 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, char **argv)
+.. c:function:: int Py_Main(int argc, char **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`
+   prepared exactly as those which are passed to a C program's :c:func:`main`
    function.  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 the integer passed to the :func:`sys.exit` function, ``1`` if the
-   interpreter exits due to an exception, or ``2`` if the parameter list does not
-   represent a valid Python command line.
-
-   Note that if an otherwise unhandled :exc:`SystemError` is raised, this
+   value will be ``0`` if the interpreter exits normally (ie, without an
+   exception), ``1`` if the interpreter exits due to an exception, or ``2``
+   if the parameter list does not represent a valid Python command line.
+
+   Note that if an otherwise unhandled :exc:`SystemExit` is raised, this
    function will not return ``1``, but exit the process, as long as
    ``Py_InspectFlag`` is not set.
 
 
-.. cfunction:: int PyRun_AnyFile(FILE *fp, const char *filename)
-
-   This is a simplified interface to :cfunc:`PyRun_AnyFileExFlags` below, leaving
+.. c:function:: int PyRun_AnyFile(FILE *fp, const char *filename)
+
+   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)
-
-   This is a simplified interface to :cfunc:`PyRun_AnyFileExFlags` below, leaving
+.. c:function:: int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
+
+   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)
-
-   This is a simplified interface to :cfunc:`PyRun_AnyFileExFlags` below, leaving
+.. c:function:: int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)
+
+   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
+   :c:func:`PyRun_InteractiveLoop`, otherwise return the result of
+   :c:func:`PyRun_SimpleFile`.  If *filename* is *NULL*, this function uses
    ``"???"`` as the filename.
 
 
-.. cfunction:: int PyRun_SimpleString(const char *command)
-
-   This is a simplified interface to :cfunc:`PyRun_SimpleStringFlags` below,
+.. c:function:: int PyRun_SimpleString(const char *command)
+
+   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
@@ -83 +83 @@
    meaning of *flags*, see below.
 
-   Note that if an otherwise unhandled :exc:`SystemError` is raised, this
+   Note that if an otherwise unhandled :exc:`SystemExit` is raised, this
    function will not return ``-1``, but exit the process, as long as
    ``Py_InspectFlag`` is not set.
 
 
-.. cfunction:: int PyRun_SimpleFile(FILE *fp, const char *filename)
-
-   This is a simplified interface to :cfunc:`PyRun_SimpleFileExFlags` below,
+.. c:function:: int PyRun_SimpleFile(FILE *fp, const char *filename)
+
+   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)
-
-   This is a simplified interface to :cfunc:`PyRun_SimpleFileExFlags` below,
+.. c:function:: int PyRun_SimpleFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
+
+   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)
-
-   This is a simplified interface to :cfunc:`PyRun_SimpleFileExFlags` below,
+.. c:function:: int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)
+
+   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)
-
-   Similar to :cfunc:`PyRun_SimpleStringFlags`, but the Python source code is read
+.. c:function:: int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)
+
+   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.  If *closeit* is true, the file is closed before PyRun_SimpleFileExFlags
@@ -114 +114 @@
 
 
-.. cfunction:: int PyRun_InteractiveOne(FILE *fp, const char *filename)
-
-   This is a simplified interface to :cfunc:`PyRun_InteractiveOneFlags` below,
+.. c:function:: int PyRun_InteractiveOne(FILE *fp, const char *filename)
+
+   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)
-
-   Read and execute a single statement from a file associated with an interactive
-   device according to the *flags* argument.  If *filename* is *NULL*, ``"???"`` is
-   used instead.  The user will be prompted using ``sys.ps1`` and ``sys.ps2``.
-   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)
-
-   This is a simplified interface to :cfunc:`PyRun_InteractiveLoopFlags` below,
+.. 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
+   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.)
+
+
+.. c:function:: int PyRun_InteractiveLoop(FILE *fp, const char *filename)
+
+   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.  If *filename* is *NULL*, ``"???"`` is used instead.  The
-   user will be prompted using ``sys.ps1`` and ``sys.ps2``.  Returns ``0`` at EOF.
-
-
-.. cfunction:: struct _node* PyParser_SimpleParseString(const char *str, int start)
+   until EOF is reached.  The user will be prompted using ``sys.ps1`` and
+   ``sys.ps2``.  Returns ``0`` at EOF.
+
+
+.. 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
@@ -166 +166 @@
 
 
-.. cfunction:: struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)
-
-   This is a simplified interface to :cfunc:`PyParser_SimpleParseFileFlags` below,
+.. c:function:: struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)
+
+   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)
-
-   Similar to :cfunc:`PyParser_SimpleParseStringFlagsFilename`, but the Python
+.. c:function:: struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags)
+
+   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)
-
-   This is a simplified interface to :cfunc:`PyRun_StringFlags` below, leaving
+.. c:function:: PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)
+
+   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
@@ -195 +195 @@
 
 
-.. cfunction:: 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
+.. c:function:: PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)
+
+   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)
-
-   This is a simplified interface to :cfunc:`PyRun_FileExFlags` below, leaving
+.. c:function:: PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)
+
+   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)
-
-   This is a simplified interface to :cfunc:`PyRun_FileExFlags` below, leaving
+.. c:function:: PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
+
+   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)
-
-   Similar to :cfunc:`PyRun_StringFlags`, but the Python source code is read from
+.. c:function:: PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)
+
+   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.
-   If *closeit* is true, the file is closed before :cfunc:`PyRun_FileExFlags`
+   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)
-
-   This is a simplified interface to :cfunc:`Py_CompileStringFlags` below, leaving
+.. c:function:: PyObject* Py_CompileString(const char *str, const char *filename, int start)
+
+   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)
 
    Parse and compile the Python source code in *str*, returning the resulting code
@@ -238 +238 @@
 
 
-.. cfunction:: PyObject* PyEval_EvalCode(PyCodeObject *co, PyObject *globals, PyObject *locals)
-
-   This is a simplified interface to :cfunc:`PyEval_EvalCodeEx`, with just
+.. c:function:: PyObject* PyEval_EvalCode(PyCodeObject *co, PyObject *globals, PyObject *locals)
+
+   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(PyCodeObject *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
@@ -253 +253 @@
 
 
-.. cfunction:: PyObject* PyEval_EvalFrame(PyFrameObject *f)
+.. c:function:: PyObject* PyEval_EvalFrame(PyFrameObject *f)
 
    Evaluate an execution frame.  This is a simplified interface to
@@ -259 +259 @@
 
 
-.. 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
@@ -266 +266 @@
    The additional *throwflag* parameter can mostly be ignored - if true, then
    it causes an exception to immediately be thrown; this is used for the
-   :meth:`throw` methods of generator objects.
-
-
-.. cfunction:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)
+   :meth:`~generator.throw` methods of generator objects.
+
+
+.. c:function:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)
 
    This function changes the flags of the current evaluation frame, and returns
@@ -275 +275 @@
 
 
-.. 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`.
-
-
-.. cvar:: int Py_file_input
+   :c:func:`Py_CompileString`.
+
+
+.. 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
@@ -317 +317 @@
 
 
-.. cvar:: int CO_FUTURE_DIVISION
+.. c:var:: int CO_FUTURE_DIVISION
 
    This bit can be set in *flags* to cause division operator ``/`` to be