[3.11] gh-115172: Fix explicit index extries for the C API (GH-115173) (GH-115293)

(cherry picked from commit 573acb3)

Author: serhiy-storchaka

Doc/c-api/buffer.rst

@@ -29,7 +29,7 @@ without intermediate copying.
 Python provides such a facility at the C level in the form of the :ref:`buffer
 protocol <bufferobjects>`.  This protocol has two sides:
 
-.. index:: single: PyBufferProcs
+.. index:: single: PyBufferProcs (C type)
 
 - on the producer side, a type can export a "buffer interface" which allows
   objects of that type to expose information about their underlying buffer.

Doc/c-api/exceptions.rst

@@ -148,7 +148,7 @@ For convenience, some of these functions will always return a
 
 .. c:function:: PyObject* PyErr_SetFromErrno(PyObject *type)
 
-   .. index:: single: strerror()
+   .. index:: single: strerror (C function)
 
    This is a convenience function to raise an exception when a C library function
    has returned an error and set the C variable :c:data:`errno`.  It constructs a
@@ -550,7 +550,7 @@ Signal Handling
 
    .. index::
       pair: module; signal
-      single: SIGINT
+      single: SIGINT (C macro)
       single: KeyboardInterrupt (built-in exception)
 
    This function interacts with Python's signal handling.
@@ -581,7 +581,7 @@ Signal Handling
 
    .. index::
       pair: module; signal
-      single: SIGINT
+      single: SIGINT (C macro)
       single: KeyboardInterrupt (built-in exception)
 
    Simulate the effect of a :c:macro:`!SIGINT` signal arriving.
@@ -861,59 +861,59 @@ All standard Python exceptions are available as global variables whose names are
 the variables:
 
 .. index::
-   single: PyExc_BaseException
-   single: PyExc_Exception
-   single: PyExc_ArithmeticError
-   single: PyExc_AssertionError
-   single: PyExc_AttributeError
-   single: PyExc_BlockingIOError
-   single: PyExc_BrokenPipeError
-   single: PyExc_BufferError
-   single: PyExc_ChildProcessError
-   single: PyExc_ConnectionAbortedError
-   single: PyExc_ConnectionError
-   single: PyExc_ConnectionRefusedError
-   single: PyExc_ConnectionResetError
-   single: PyExc_EOFError
-   single: PyExc_FileExistsError
-   single: PyExc_FileNotFoundError
-   single: PyExc_FloatingPointError
-   single: PyExc_GeneratorExit
-   single: PyExc_ImportError
-   single: PyExc_IndentationError
-   single: PyExc_IndexError
-   single: PyExc_InterruptedError
-   single: PyExc_IsADirectoryError
-   single: PyExc_KeyError
-   single: PyExc_KeyboardInterrupt
-   single: PyExc_LookupError
-   single: PyExc_MemoryError
-   single: PyExc_ModuleNotFoundError
-   single: PyExc_NameError
-   single: PyExc_NotADirectoryError
-   single: PyExc_NotImplementedError
-   single: PyExc_OSError
-   single: PyExc_OverflowError
-   single: PyExc_PermissionError
-   single: PyExc_ProcessLookupError
-   single: PyExc_RecursionError
-   single: PyExc_ReferenceError
-   single: PyExc_RuntimeError
-   single: PyExc_StopAsyncIteration
-   single: PyExc_StopIteration
-   single: PyExc_SyntaxError
-   single: PyExc_SystemError
-   single: PyExc_SystemExit
-   single: PyExc_TabError
-   single: PyExc_TimeoutError
-   single: PyExc_TypeError
-   single: PyExc_UnboundLocalError
-   single: PyExc_UnicodeDecodeError
-   single: PyExc_UnicodeEncodeError
-   single: PyExc_UnicodeError
-   single: PyExc_UnicodeTranslateError
-   single: PyExc_ValueError
-   single: PyExc_ZeroDivisionError
+   single: PyExc_BaseException (C var)
+   single: PyExc_Exception (C var)
+   single: PyExc_ArithmeticError (C var)
+   single: PyExc_AssertionError (C var)
+   single: PyExc_AttributeError (C var)
+   single: PyExc_BlockingIOError (C var)
+   single: PyExc_BrokenPipeError (C var)
+   single: PyExc_BufferError (C var)
+   single: PyExc_ChildProcessError (C var)
+   single: PyExc_ConnectionAbortedError (C var)
+   single: PyExc_ConnectionError (C var)
+   single: PyExc_ConnectionRefusedError (C var)
+   single: PyExc_ConnectionResetError (C var)
+   single: PyExc_EOFError (C var)
+   single: PyExc_FileExistsError (C var)
+   single: PyExc_FileNotFoundError (C var)
+   single: PyExc_FloatingPointError (C var)
+   single: PyExc_GeneratorExit (C var)
+   single: PyExc_ImportError (C var)
+   single: PyExc_IndentationError (C var)
+   single: PyExc_IndexError (C var)
+   single: PyExc_InterruptedError (C var)
+   single: PyExc_IsADirectoryError (C var)
+   single: PyExc_KeyError (C var)
+   single: PyExc_KeyboardInterrupt (C var)
+   single: PyExc_LookupError (C var)
+   single: PyExc_MemoryError (C var)
+   single: PyExc_ModuleNotFoundError (C var)
+   single: PyExc_NameError (C var)
+   single: PyExc_NotADirectoryError (C var)
+   single: PyExc_NotImplementedError (C var)
+   single: PyExc_OSError (C var)
+   single: PyExc_OverflowError (C var)
+   single: PyExc_PermissionError (C var)
+   single: PyExc_ProcessLookupError (C var)
+   single: PyExc_RecursionError (C var)
+   single: PyExc_ReferenceError (C var)
+   single: PyExc_RuntimeError (C var)
+   single: PyExc_StopAsyncIteration (C var)
+   single: PyExc_StopIteration (C var)
+   single: PyExc_SyntaxError (C var)
+   single: PyExc_SystemError (C var)
+   single: PyExc_SystemExit (C var)
+   single: PyExc_TabError (C var)
+   single: PyExc_TimeoutError (C var)
+   single: PyExc_TypeError (C var)
+   single: PyExc_UnboundLocalError (C var)
+   single: PyExc_UnicodeDecodeError (C var)
+   single: PyExc_UnicodeEncodeError (C var)
+   single: PyExc_UnicodeError (C var)
+   single: PyExc_UnicodeTranslateError (C var)
+   single: PyExc_ValueError (C var)
+   single: PyExc_ZeroDivisionError (C var)
 
 +-----------------------------------------+---------------------------------+----------+
 | C Name                                  | Python Name                     | Notes    |
@@ -1044,9 +1044,9 @@ the variables:
 These are compatibility aliases to :c:data:`PyExc_OSError`:
 
 .. index::
-   single: PyExc_EnvironmentError
-   single: PyExc_IOError
-   single: PyExc_WindowsError
+   single: PyExc_EnvironmentError (C var)
+   single: PyExc_IOError (C var)
+   single: PyExc_WindowsError (C var)
 
 +-------------------------------------+----------+
 | C Name                              | Notes    |
@@ -1081,17 +1081,17 @@ names are ``PyExc_`` followed by the Python exception name. These have the type
 the variables:
 
 .. index::
-   single: PyExc_Warning
-   single: PyExc_BytesWarning
-   single: PyExc_DeprecationWarning
-   single: PyExc_FutureWarning
-   single: PyExc_ImportWarning
-   single: PyExc_PendingDeprecationWarning
-   single: PyExc_ResourceWarning
-   single: PyExc_RuntimeWarning
-   single: PyExc_SyntaxWarning
-   single: PyExc_UnicodeWarning
-   single: PyExc_UserWarning
+   single: PyExc_Warning (C var)
+   single: PyExc_BytesWarning (C var)
+   single: PyExc_DeprecationWarning (C var)
+   single: PyExc_FutureWarning (C var)
+   single: PyExc_ImportWarning (C var)
+   single: PyExc_PendingDeprecationWarning (C var)
+   single: PyExc_ResourceWarning (C var)
+   single: PyExc_RuntimeWarning (C var)
+   single: PyExc_SyntaxWarning (C var)
+   single: PyExc_UnicodeWarning (C var)
+   single: PyExc_UserWarning (C var)
 
 +------------------------------------------+---------------------------------+----------+
 | C Name                                   | Python Name                     | Notes    |

Doc/c-api/file.rst

@@ -96,7 +96,7 @@ the :mod:`io` APIs instead.
 
 .. c:function:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
 
-   .. index:: single: Py_PRINT_RAW
+   .. index:: single: Py_PRINT_RAW (C macro)
 
    Write object *obj* to file object *p*.  The only supported flag for *flags* is
    :c:macro:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written

Doc/c-api/init.rst

@@ -237,9 +237,9 @@ Initializing and finalizing the interpreter
       pair: module; __main__
       pair: module; sys
       triple: module; search; path
-      single: PySys_SetArgv()
-      single: PySys_SetArgvEx()
-      single: Py_FinalizeEx()
+      single: PySys_SetArgv (C function)
+      single: PySys_SetArgvEx (C function)
+      single: Py_FinalizeEx (C function)
 
    Initialize the Python interpreter.  In an application embedding  Python,
    this should be called before using any other Python/C API functions; see
@@ -740,7 +740,7 @@ operations could cause problems in a multi-threaded program: for example, when
 two threads simultaneously increment the reference count of the same object, the
 reference count could end up being incremented only once instead of twice.
 
-.. index:: single: setswitchinterval() (in module sys)
+.. index:: single: setswitchinterval (in module sys)
 
 Therefore, the rule exists that only the thread that has acquired the
 :term:`GIL` may operate on Python objects or call Python/C API functions.
@@ -750,8 +750,7 @@ released around potentially blocking I/O operations like reading or writing
 a file, so that other Python threads can run in the meantime.
 
 .. index::
-   single: PyThreadState
-   single: PyThreadState
+   single: PyThreadState (C type)
 
 The Python interpreter keeps some thread-specific bookkeeping information
 inside a data structure called :c:type:`PyThreadState`.  There's also one
@@ -777,8 +776,8 @@ This is so common that a pair of macros exists to simplify it::
    Py_END_ALLOW_THREADS
 
 .. index::
-   single: Py_BEGIN_ALLOW_THREADS
-   single: Py_END_ALLOW_THREADS
+   single: Py_BEGIN_ALLOW_THREADS (C macro)
+   single: Py_END_ALLOW_THREADS (C macro)
 
 The :c:macro:`Py_BEGIN_ALLOW_THREADS` macro opens a new block and declares a
 hidden local variable; the :c:macro:`Py_END_ALLOW_THREADS` macro closes the
@@ -793,8 +792,8 @@ The block above expands to the following code::
    PyEval_RestoreThread(_save);
 
 .. index::
-   single: PyEval_RestoreThread()
-   single: PyEval_SaveThread()
+   single: PyEval_RestoreThread (C function)
+   single: PyEval_SaveThread (C function)
 
 Here is how these functions work: the global interpreter lock is used to protect the pointer to the
 current thread state.  When releasing the lock and saving the thread state,
@@ -1417,8 +1416,8 @@ function. You can create and destroy them using the following functions:
    entry.)
 
    .. index::
-      single: Py_FinalizeEx()
-      single: Py_Initialize()
+      single: Py_FinalizeEx (C function)
+      single: Py_Initialize (C function)
 
    Extension modules are shared between (sub-)interpreters as follows:
 
@@ -1446,12 +1445,12 @@ function. You can create and destroy them using the following functions:
       As with multi-phase initialization, this means that only C-level static
       and global variables are shared between these modules.
 
-   .. index:: single: close() (in module os)
+   .. index:: single: close (in module os)
 
 
 .. c:function:: void Py_EndInterpreter(PyThreadState *tstate)
 
-   .. index:: single: Py_FinalizeEx()
+   .. index:: single: Py_FinalizeEx (C function)
 
    Destroy the (sub-)interpreter represented by the given thread state. The given
    thread state must be the current thread state.  See the discussion of thread
@@ -1501,8 +1500,6 @@ pointer and a void pointer argument.
 
 .. c:function:: int Py_AddPendingCall(int (*func)(void *), void *arg)
 
-   .. index:: single: Py_AddPendingCall()
-
    Schedule a function to be called from the main interpreter thread.  On
    success, ``0`` is returned and *func* is queued for being called in the
    main thread.  On failure, ``-1`` is returned without setting any exception.

Doc/c-api/intro.rst

@@ -325,8 +325,8 @@ objects that reference each other here; for now, the solution
 is "don't do that.")
 
 .. index::
-   single: Py_INCREF()
-   single: Py_DECREF()
+   single: Py_INCREF (C function)
+   single: Py_DECREF (C function)
 
 Reference counts are always manipulated explicitly.  The normal way is
 to use the macro :c:func:`Py_INCREF` to take a new reference to an
@@ -401,8 +401,8 @@ function, that function assumes that it now owns that reference, and you are not
 responsible for it any longer.
 
 .. index::
-   single: PyList_SetItem()
-   single: PyTuple_SetItem()
+   single: PyList_SetItem (C function)
+   single: PyTuple_SetItem (C function)
 
 Few functions steal references; the two notable exceptions are
 :c:func:`PyList_SetItem` and :c:func:`PyTuple_SetItem`, which  steal a reference
@@ -491,8 +491,8 @@ using :c:func:`PySequence_GetItem` (which happens to take exactly the same
 arguments), you do own a reference to the returned object.
 
 .. index::
-   single: PyList_GetItem()
-   single: PySequence_GetItem()
+   single: PyList_GetItem (C function)
+   single: PySequence_GetItem (C function)
 
 Here is an example of how you could write a function that computes the sum of
 the items in a list of integers; once using  :c:func:`PyList_GetItem`, and once
@@ -587,7 +587,7 @@ caller, then to the caller's caller, and so on, until they reach the top-level
 interpreter, where they are reported to the  user accompanied by a stack
 traceback.
 
-.. index:: single: PyErr_Occurred()
+.. index:: single: PyErr_Occurred (C function)
 
 For C programmers, however, error checking always has to be explicit.  All
 functions in the Python/C API can raise exceptions, unless an explicit claim is
@@ -601,8 +601,8 @@ ambiguous return value, and require explicit testing for errors with
 :c:func:`PyErr_Occurred`.  These exceptions are always explicitly documented.
 
 .. index::
-   single: PyErr_SetString()
-   single: PyErr_Clear()
+   single: PyErr_SetString (C function)
+   single: PyErr_Clear (C function)
 
 Exception state is maintained in per-thread storage (this is  equivalent to
 using global storage in an unthreaded application).  A  thread can be in one of
@@ -624,7 +624,7 @@ an exception is being passed on between C functions until it reaches the Python
 bytecode interpreter's  main loop, which takes care of transferring it to
 ``sys.exc_info()`` and friends.
 
-.. index:: single: exc_info() (in module sys)
+.. index:: single: exc_info (in module sys)
 
 Note that starting with Python 1.5, the preferred, thread-safe way to access the
 exception state from Python code is to call the function :func:`sys.exc_info`,
@@ -709,9 +709,9 @@ Here is the corresponding C code, in all its glory::
 .. index:: single: incr_item()
 
 .. index::
-   single: PyErr_ExceptionMatches()
-   single: PyErr_Clear()
-   single: Py_XDECREF()
+   single: PyErr_ExceptionMatches (C function)
+   single: PyErr_Clear (C function)
+   single: Py_XDECREF (C function)
 
 This example represents an endorsed use of the ``goto`` statement  in C!
 It illustrates the use of :c:func:`PyErr_ExceptionMatches` and
@@ -735,7 +735,7 @@ the finalization, of the Python interpreter.  Most functionality of the
 interpreter can only be used after the interpreter has been initialized.
 
 .. index::
-   single: Py_Initialize()
+   single: Py_Initialize (C function)
    pair: module; builtins
    pair: module; __main__
    pair: module; sys
@@ -770,11 +770,11 @@ environment variable :envvar:`PYTHONHOME`, or insert additional directories in
 front of the standard path by setting :envvar:`PYTHONPATH`.
 
 .. index::
-   single: Py_SetProgramName()
-   single: Py_GetPath()
-   single: Py_GetPrefix()
-   single: Py_GetExecPrefix()
-   single: Py_GetProgramFullPath()
+   single: Py_SetProgramName (C function)
+   single: Py_GetPath (C function)
+   single: Py_GetPrefix (C function)
+   single: Py_GetExecPrefix (C function)
+   single: Py_GetProgramFullPath (C function)
 
 The embedding application can steer the search by calling
 ``Py_SetProgramName(file)`` *before* calling  :c:func:`Py_Initialize`.  Note that
@@ -784,7 +784,7 @@ control has to provide its own implementation of :c:func:`Py_GetPath`,
 :c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`, and
 :c:func:`Py_GetProgramFullPath` (all defined in :file:`Modules/getpath.c`).
 
-.. index:: single: Py_IsInitialized()
+.. index:: single: Py_IsInitialized (C function)
 
 Sometimes, it is desirable to "uninitialize" Python.  For instance,  the
 application may want to start over (make another call to