From 5342ffcfd7f4eda2322b1c19f854bdacd31e7391 Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Wed, 31 Jan 2024 16:39:03 -0600 Subject: [PATCH 01/10] clean up Doc/c-api/exceptions.rst --- Doc/c-api/exceptions.rst | 12 ++++++------ Doc/c-api/sys.rst | 4 ++-- Doc/tools/.nitignore | 1 - 3 files changed, 8 insertions(+), 9 deletions(-) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index c7e3cd9463e5d7..26fed4d3242c3e 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -396,7 +396,7 @@ an error value). .. c:function:: int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...) Function similar to :c:func:`PyErr_WarnFormat`, but *category* is - :exc:`ResourceWarning` and it passes *source* to :func:`warnings.WarningMessage`. + :exc:`ResourceWarning` and it passes *source* to :class:`!warnings.WarningMessage`. .. versionadded:: 3.6 @@ -732,7 +732,7 @@ Exception Classes This creates a class object derived from :exc:`Exception` (accessible in C as :c:data:`PyExc_Exception`). - The :attr:`__module__` attribute of the new class is set to the first part (up + The :attr:`!__module__` attribute of the new class is set to the first part (up to the last dot) of the *name* argument, and the class name is set to the last part (after the last dot). The *base* argument can be used to specify alternate base classes; it can either be only one class or a tuple of classes. The *dict* @@ -904,7 +904,7 @@ because the :ref:`call protocol ` takes care of recursion handling. Marks a point where a recursive C-level call is about to be performed. - If :c:macro:`USE_STACKCHECK` is defined, this function checks if the OS + If :c:macro:`!USE_STACKCHECK` is defined, this function checks if the OS stack overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it sets a :exc:`MemoryError` and returns a nonzero value. @@ -1158,11 +1158,11 @@ These are compatibility aliases to :c:data:`PyExc_OSError`: +-------------------------------------+----------+ | C Name | Notes | +=====================================+==========+ -| :c:data:`PyExc_EnvironmentError` | | +| :c:data:`!PyExc_EnvironmentError` | | +-------------------------------------+----------+ -| :c:data:`PyExc_IOError` | | +| :c:data:`!PyExc_IOError` | | +-------------------------------------+----------+ -| :c:data:`PyExc_WindowsError` | [2]_ | +| :c:data:`!PyExc_WindowsError` | [2]_ | +-------------------------------------+----------+ .. versionchanged:: 3.3 diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst index e3c54b075114ff..6bbe0c815de5f8 100644 --- a/Doc/c-api/sys.rst +++ b/Doc/c-api/sys.rst @@ -98,9 +98,9 @@ Operating System Utilities .. c:function:: int PyOS_CheckStack() Return true when the interpreter runs out of stack space. This is a reliable - check, but is only available when :c:macro:`USE_STACKCHECK` is defined (currently + check, but is only available when :c:macro:`!USE_STACKCHECK` is defined (currently on certain versions of Windows using the Microsoft Visual C++ compiler). - :c:macro:`USE_STACKCHECK` will be defined automatically; you should never + :c:macro:`!USE_STACKCHECK` will be defined automatically; you should never change the definition in your own code. diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 7eacb46d6299b3..852542f3f961eb 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -3,7 +3,6 @@ # Keep lines sorted lexicographically to help avoid merge conflicts. Doc/c-api/descriptor.rst -Doc/c-api/exceptions.rst Doc/c-api/float.rst Doc/c-api/gcsupport.rst Doc/c-api/init.rst From d8a1b7a547cd24b7e20082a64f081ea8cc9dde0c Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Thu, 8 Feb 2024 11:00:14 -0600 Subject: [PATCH 02/10] typo caught by serhiy --- Doc/c-api/exceptions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 26fed4d3242c3e..519c2a96c2bbef 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -905,7 +905,7 @@ because the :ref:`call protocol ` takes care of recursion handling. Marks a point where a recursive C-level call is about to be performed. If :c:macro:`!USE_STACKCHECK` is defined, this function checks if the OS - stack overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it + stack overflowed using :c:func:`PyOS_CheckStack`. If this is the case, it sets a :exc:`MemoryError` and returns a nonzero value. The function then checks if the recursion limit is reached. If this is the From 384f1c687f72129b2c6fa566097a5018bf012533 Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Thu, 8 Feb 2024 11:20:24 -0600 Subject: [PATCH 03/10] + USE_STACKCHECK index entry, type defs for PyOS_sighandler_t and Py_AuditHookFunction --- Doc/c-api/sys.rst | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst index 6bbe0c815de5f8..9167b49f33808e 100644 --- a/Doc/c-api/sys.rst +++ b/Doc/c-api/sys.rst @@ -5,6 +5,16 @@ Operating System Utilities ========================== +.. c:type:: PyOS_sighandler_t + + ``PyOS_sighandler_t`` is a typedef alias for :c:expr:`void (\*)(int)`. + + +.. c:type:: Py_AuditHookFunction + + ``Py_AuditHookFunction`` is a typedef alias for :c:expr:`int(\*) (const char \*, PyObject \*, void \*)`. + + .. c:function:: PyObject* PyOS_FSPath(PyObject *path) Return the file system representation for *path*. If the object is a @@ -97,6 +107,8 @@ Operating System Utilities .. c:function:: int PyOS_CheckStack() + .. index:: single: USE_STACKCHECK (C macro) + Return true when the interpreter runs out of stack space. This is a reliable check, but is only available when :c:macro:`!USE_STACKCHECK` is defined (currently on certain versions of Windows using the Microsoft Visual C++ compiler). @@ -108,16 +120,14 @@ Operating System Utilities Return the current signal handler for signal *i*. This is a thin wrapper around either :c:func:`!sigaction` or :c:func:`!signal`. Do not call those functions - directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:expr:`void - (\*)(int)`. + directly! .. c:function:: PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h) Set the signal handler for signal *i* to be *h*; return the old signal handler. This is a thin wrapper around either :c:func:`!sigaction` or :c:func:`!signal`. Do - not call those functions directly! :c:type:`PyOS_sighandler_t` is a typedef - alias for :c:expr:`void (\*)(int)`. + not call those functions directly! .. c:function:: wchar_t* Py_DecodeLocale(const char* arg, size_t *size) From e721a948078d01eab682cc9b3dcfab1e41facb02 Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Thu, 8 Feb 2024 14:13:47 -0600 Subject: [PATCH 04/10] feedback from Serhiy --- Doc/c-api/sys.rst | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst index 9167b49f33808e..18375f0c01fbaf 100644 --- a/Doc/c-api/sys.rst +++ b/Doc/c-api/sys.rst @@ -5,15 +5,6 @@ Operating System Utilities ========================== -.. c:type:: PyOS_sighandler_t - - ``PyOS_sighandler_t`` is a typedef alias for :c:expr:`void (\*)(int)`. - - -.. c:type:: Py_AuditHookFunction - - ``Py_AuditHookFunction`` is a typedef alias for :c:expr:`int(\*) (const char \*, PyObject \*, void \*)`. - .. c:function:: PyObject* PyOS_FSPath(PyObject *path) @@ -116,6 +107,9 @@ Operating System Utilities change the definition in your own code. +.. c:type:: void (*PyOS_sighandler_t)(int) + + .. c:function:: PyOS_sighandler_t PyOS_getsig(int i) Return the current signal handler for signal *i*. This is a thin wrapper around @@ -362,6 +356,8 @@ accessible to C code. They all work with the current interpreter thread's :ref:`audit events table `. Details are in each function's documentation. + .. c:type:: int (*Py_AuditHookFunction) (const char *, PyObject *, void *) + .. audit-event:: sys.addaudithook "" c.PySys_AddAuditHook If the interpreter is initialized, this function raises a auditing event From 0a428a3eb5ba459556fe20d70eeddda1a20aae37 Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Thu, 8 Feb 2024 16:14:11 -0600 Subject: [PATCH 05/10] move location and context, per Serhiy --- Doc/c-api/sys.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst index 18375f0c01fbaf..53c95fb3a0c6e2 100644 --- a/Doc/c-api/sys.rst +++ b/Doc/c-api/sys.rst @@ -346,6 +346,9 @@ accessible to C code. They all work with the current interpreter thread's silently abort the operation by raising an error subclassed from :class:`Exception` (other errors will not be silenced). + .. c:namespace:: NULL + .. c:type:: int (*Py_AuditHookFunction) (const char *, PyObject *, void *) + The hook function is of type :c:expr:`int (*)(const char *event, PyObject *args, void *userData)`, where *args* is guaranteed to be a :c:type:`PyTupleObject`. The hook function is always called with the GIL @@ -356,8 +359,6 @@ accessible to C code. They all work with the current interpreter thread's :ref:`audit events table `. Details are in each function's documentation. - .. c:type:: int (*Py_AuditHookFunction) (const char *, PyObject *, void *) - .. audit-event:: sys.addaudithook "" c.PySys_AddAuditHook If the interpreter is initialized, this function raises a auditing event From 2aa277105c1321cbb714c38d2ef6ed4017ec6aa6 Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Fri, 9 Feb 2024 13:40:37 -0600 Subject: [PATCH 06/10] tweak to eliminate duplicate, based on suggestion by Serhiy --- Doc/c-api/sys.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst index 53c95fb3a0c6e2..95f0f7d2775417 100644 --- a/Doc/c-api/sys.rst +++ b/Doc/c-api/sys.rst @@ -347,12 +347,14 @@ accessible to C code. They all work with the current interpreter thread's :class:`Exception` (other errors will not be silenced). .. c:namespace:: NULL - .. c:type:: int (*Py_AuditHookFunction) (const char *, PyObject *, void *) - - The hook function is of type :c:expr:`int (*)(const char *event, PyObject - *args, void *userData)`, where *args* is guaranteed to be a - :c:type:`PyTupleObject`. The hook function is always called with the GIL - held by the Python interpreter that raised the event. + .. c:type:: int (*Py_AuditHookFunction) (const char *event, PyObject *args, void *userData) + + The type of the hook function. + *event* is (the event argument passed to PySys_Audit() or PySys_AuditTuple()), + *args* is guaranteed to be a :c:type:`PyTupleObject`. The hook + function is always called with the GIL held by the Python + interpreter that raised the event. + *userData* is the argument passed to PySys_AddAuditHook(). See :pep:`578` for a detailed description of auditing. Functions in the runtime and standard library that raise events are listed in the From bf7297c7d149cfa32a3e890db8024b2fad0d3aac Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Fri, 9 Feb 2024 16:02:00 -0600 Subject: [PATCH 07/10] maybe this is better --- Doc/c-api/sys.rst | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst index 95f0f7d2775417..7394cd8ccbd4a3 100644 --- a/Doc/c-api/sys.rst +++ b/Doc/c-api/sys.rst @@ -329,6 +329,15 @@ accessible to C code. They all work with the current interpreter thread's .. versionadded:: 3.13 +.. c:namespace:: NULL +.. c:type:: int (*Py_AuditHookFunction) (const char *event, PyObject *args, void *userData) + +The type of the hook function. +*event* is the C string event argument passed to :c:func:`PySys_Audit` or +:c:func:`PySys_AuditTuple`. +*args* is guaranteed to be a :c:type:`PyTupleObject`. +*userData* is the argument passed to PySys_AddAuditHook(). + .. c:function:: int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData) Append the callable *hook* to the list of active auditing hooks. @@ -346,15 +355,8 @@ accessible to C code. They all work with the current interpreter thread's silently abort the operation by raising an error subclassed from :class:`Exception` (other errors will not be silenced). - .. c:namespace:: NULL - .. c:type:: int (*Py_AuditHookFunction) (const char *event, PyObject *args, void *userData) - - The type of the hook function. - *event* is (the event argument passed to PySys_Audit() or PySys_AuditTuple()), - *args* is guaranteed to be a :c:type:`PyTupleObject`. The hook - function is always called with the GIL held by the Python - interpreter that raised the event. - *userData* is the argument passed to PySys_AddAuditHook(). + The hook function is always called with the GIL held by the Python + interpreter that raised the event. See :pep:`578` for a detailed description of auditing. Functions in the runtime and standard library that raise events are listed in the From 30427f5bc99d106bea31ed8f6dd41ec818c61c5c Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Fri, 9 Feb 2024 16:06:40 -0600 Subject: [PATCH 08/10] better ordering? --- Doc/c-api/sys.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst index 7394cd8ccbd4a3..1080696e52db6b 100644 --- a/Doc/c-api/sys.rst +++ b/Doc/c-api/sys.rst @@ -329,15 +329,6 @@ accessible to C code. They all work with the current interpreter thread's .. versionadded:: 3.13 -.. c:namespace:: NULL -.. c:type:: int (*Py_AuditHookFunction) (const char *event, PyObject *args, void *userData) - -The type of the hook function. -*event* is the C string event argument passed to :c:func:`PySys_Audit` or -:c:func:`PySys_AuditTuple`. -*args* is guaranteed to be a :c:type:`PyTupleObject`. -*userData* is the argument passed to PySys_AddAuditHook(). - .. c:function:: int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData) Append the callable *hook* to the list of active auditing hooks. @@ -365,14 +356,23 @@ The type of the hook function. .. audit-event:: sys.addaudithook "" c.PySys_AddAuditHook - If the interpreter is initialized, this function raises a auditing event - ``sys.addaudithook`` with no arguments. If any existing hooks raise an - exception derived from :class:`Exception`, the new hook will not be - added and the exception is cleared. As a result, callers cannot assume - that their hook has been added unless they control all existing hooks. + If the interpreter is initialized, this function raises an auditing event + ``sys.addaudithook`` with no arguments. If any existing hooks raise an + exception derived from :class:`Exception`, the new hook will not be + added and the exception is cleared. As a result, callers cannot assume + that their hook has been added unless they control all existing hooks. .. versionadded:: 3.8 +.. c:namespace:: NULL +.. c:type:: int (*Py_AuditHookFunction) (const char *event, PyObject *args, void *userData) + +The type of the hook function. +*event* is the C string event argument passed to :c:func:`PySys_Audit` or +:c:func:`PySys_AuditTuple`. +*args* is guaranteed to be a :c:type:`PyTupleObject`. +*userData* is the argument passed to PySys_AddAuditHook(). + .. _processcontrol: From bba6ff64257bd389e0ae5433680f3ff4ce2a6aba Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Sat, 10 Feb 2024 13:22:59 -0600 Subject: [PATCH 09/10] undoing some indentation, I clearly don't understand how the nesting works --- Doc/c-api/sys.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst index 1080696e52db6b..10d4b81b7865f3 100644 --- a/Doc/c-api/sys.rst +++ b/Doc/c-api/sys.rst @@ -356,22 +356,22 @@ accessible to C code. They all work with the current interpreter thread's .. audit-event:: sys.addaudithook "" c.PySys_AddAuditHook - If the interpreter is initialized, this function raises an auditing event - ``sys.addaudithook`` with no arguments. If any existing hooks raise an - exception derived from :class:`Exception`, the new hook will not be - added and the exception is cleared. As a result, callers cannot assume - that their hook has been added unless they control all existing hooks. + If the interpreter is initialized, this function raises an auditing event + ``sys.addaudithook`` with no arguments. If any existing hooks raise an + exception derived from :class:`Exception`, the new hook will not be + added and the exception is cleared. As a result, callers cannot assume + that their hook has been added unless they control all existing hooks. - .. versionadded:: 3.8 + .. c:namespace:: NULL + .. c:type:: int (*Py_AuditHookFunction) (const char *event, PyObject *args, void *userData) -.. c:namespace:: NULL -.. c:type:: int (*Py_AuditHookFunction) (const char *event, PyObject *args, void *userData) + The type of the hook function. + *event* is the C string event argument passed to :c:func:`PySys_Audit` or + :c:func:`PySys_AuditTuple`. + *args* is guaranteed to be a :c:type:`PyTupleObject`. + *userData* is the argument passed to PySys_AddAuditHook(). -The type of the hook function. -*event* is the C string event argument passed to :c:func:`PySys_Audit` or -:c:func:`PySys_AuditTuple`. -*args* is guaranteed to be a :c:type:`PyTupleObject`. -*userData* is the argument passed to PySys_AddAuditHook(). + .. versionadded:: 3.8 .. _processcontrol: From 67c1ac2b7f77af1b4145ed02a1769e88388b8738 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Sun, 11 Feb 2024 20:43:48 +0200 Subject: [PATCH 10/10] Update .nitignore --- Doc/tools/.nitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 852542f3f961eb..d797c142c0cba3 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -10,7 +10,6 @@ Doc/c-api/init_config.rst Doc/c-api/intro.rst Doc/c-api/module.rst Doc/c-api/stable.rst -Doc/c-api/sys.rst Doc/c-api/type.rst Doc/c-api/typeobj.rst Doc/extending/extending.rst