gh-101100: Clean up Doc/c-api/exceptions.rst and Doc/c-api/sys.rst (GH-114825)

This commit is contained in:
Skip Montanaro 2024-02-11 12:51:07 -06:00 committed by GitHub
parent cc573c70b7
commit e1552fd19d
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 29 additions and 20 deletions

View File

@ -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,8 +904,8 @@ because the :ref:`call protocol <call>` 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
If :c:macro:`!USE_STACKCHECK` is defined, this function checks if the OS
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
@ -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

View File

@ -5,6 +5,7 @@
Operating System Utilities
==========================
.. c:function:: PyObject* PyOS_FSPath(PyObject *path)
Return the file system representation for *path*. If the object is a
@ -97,27 +98,30 @@ 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
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.
.. 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
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)
@ -342,10 +346,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).
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.
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
@ -354,12 +356,21 @@ 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 a auditing event
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.
.. 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().
.. versionadded:: 3.8

View File

@ -3,14 +3,12 @@
# 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/init.rst
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