From 4294a83fefb08a6a626d6e5dc681fd8f9b0e680e Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Mon, 16 Sep 2024 17:43:25 +0200 Subject: [PATCH] gh-118915: Add/fix docs entries for some new 3.13 C API - Add an entry for PyExc_PythonFinalizationError - Add formal entries for `PY_MONITORING_EVENT_*`, making them searchable and linkable with Intersphinx. - Use the "NULL namespace" for several macros that are documented below the functions that use them. This fixes their names in search results, and fixes linking using Intersphinx inventories. --- Doc/c-api/exceptions.rst | 3 +++ Doc/c-api/long.rst | 2 ++ Doc/c-api/module.rst | 2 ++ Doc/c-api/monitoring.rst | 34 +++++++++++++++++++++++++++++++--- 4 files changed, 38 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 372fc1dde8fc0d..05349590975160 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -1004,6 +1004,7 @@ the variables: single: PyExc_OverflowError (C var) single: PyExc_PermissionError (C var) single: PyExc_ProcessLookupError (C var) + single: PyExc_PythonFinalizationError (C var) single: PyExc_RecursionError (C var) single: PyExc_ReferenceError (C var) single: PyExc_RuntimeError (C var) @@ -1096,6 +1097,8 @@ the variables: +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_ProcessLookupError` | :exc:`ProcessLookupError` | | +-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_PythonFinalizationError` | :exc:`PythonFinalizationError` | | ++-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_RecursionError` | :exc:`RecursionError` | | +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | | diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst index 30133a9c5cfa2f..098a55c50e219a 100644 --- a/Doc/c-api/long.rst +++ b/Doc/c-api/long.rst @@ -509,6 +509,8 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. Currently, ``-1`` corresponds to ``Py_ASNATIVEBYTES_NATIVE_ENDIAN | Py_ASNATIVEBYTES_UNSIGNED_BUFFER``. + .. c:namespace:: NULL + ============================================= ====== Flag Value ============================================= ====== diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst index 3c779488813383..ec61be284caad9 100644 --- a/Doc/c-api/module.rst +++ b/Doc/c-api/module.rst @@ -421,6 +421,8 @@ The available slot types are: Specifies one of the following values: + .. c:namespace:: NULL + .. c:macro:: Py_MOD_GIL_USED The module depends on the presence of the global interpreter lock (GIL), diff --git a/Doc/c-api/monitoring.rst b/Doc/c-api/monitoring.rst index b34035b5548f02..4db26d82b9200d 100644 --- a/Doc/c-api/monitoring.rst +++ b/Doc/c-api/monitoring.rst @@ -133,7 +133,7 @@ Managing the Monitoring State Monitoring states can be managed with the help of monitoring scopes. A scope would typically correspond to a python function. -.. :c:function:: int PyMonitoring_EnterScope(PyMonitoringState *state_array, uint64_t *version, const uint8_t *event_types, Py_ssize_t length) +.. c:function:: int PyMonitoring_EnterScope(PyMonitoringState *state_array, uint64_t *version, const uint8_t *event_types, Py_ssize_t length) Enter a monitored scope. ``event_types`` is an array of the event IDs for events that may be fired from the scope. For example, the ID of a ``PY_START`` @@ -158,7 +158,35 @@ would typically correspond to a python function. execution is paused, such as when emulating a generator, the scope needs to be exited and re-entered. - -.. :c:function:: int PyMonitoring_ExitScope(void) + The macros for *event_types* are: + + .. c:namespace:: NULL + + .. The table is here to make the docs searchable, and to allow automatic + links to the identifiers. + + ================================================== ===================================== + Macro Event + ================================================== ===================================== + .. c:macro:: PY_MONITORING_EVENT_BRANCH :monitoring-event:`BRANCH` + .. c:macro:: PY_MONITORING_EVENT_CALL :monitoring-event:`CALL` + .. c:macro:: PY_MONITORING_EVENT_C_RAISE :monitoring-event:`C_RAISE` + .. c:macro:: PY_MONITORING_EVENT_C_RETURN :monitoring-event:`C_RETURN` + .. c:macro:: PY_MONITORING_EVENT_EXCEPTION_HANDLED :monitoring-event:`EXCEPTION_HANDLED` + .. c:macro:: PY_MONITORING_EVENT_INSTRUCTION :monitoring-event:`INSTRUCTION` + .. c:macro:: PY_MONITORING_EVENT_JUMP :monitoring-event:`JUMP` + .. c:macro:: PY_MONITORING_EVENT_LINE :monitoring-event:`LINE` + .. c:macro:: PY_MONITORING_EVENT_PY_RESUME :monitoring-event:`PY_RESUME` + .. c:macro:: PY_MONITORING_EVENT_PY_RETURN :monitoring-event:`PY_RETURN` + .. c:macro:: PY_MONITORING_EVENT_PY_START :monitoring-event:`PY_START` + .. c:macro:: PY_MONITORING_EVENT_PY_THROW :monitoring-event:`PY_THROW` + .. c:macro:: PY_MONITORING_EVENT_PY_UNWIND :monitoring-event:`PY_UNWIND` + .. c:macro:: PY_MONITORING_EVENT_PY_YIELD :monitoring-event:`PY_YIELD` + .. c:macro:: PY_MONITORING_EVENT_RAISE :monitoring-event:`RAISE` + .. c:macro:: PY_MONITORING_EVENT_RERAISE :monitoring-event:`RERAISE` + .. c:macro:: PY_MONITORING_EVENT_STOP_ITERATION :monitoring-event:`STOP_ITERATION` + ================================================== ===================================== + +.. c:function:: int PyMonitoring_ExitScope(void) Exit the last scope that was entered with ``PyMonitoring_EnterScope``.