Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 11, 2024
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Doc/c-api/buffer.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
140 changes: 70 additions & 70 deletions Doc/c-api/exceptions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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 |
Expand Down Expand Up @@ -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 |
Expand Down Expand Up @@ -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 |
Expand Down
2 changes: 1 addition & 1 deletion Doc/c-api/file.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
29 changes: 13 additions & 16 deletions Doc/c-api/init.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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,
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down
40 changes: 20 additions & 20 deletions Doc/c-api/intro.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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`,
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
Loading