Skip to content

Commit 07fff60

Browse files
authored
[3.11] gh-101100: Clean up Doc/c-api/exceptions.rst and Doc/c-api/sys.rst (GH-114825) (GH-115311)
(cherry picked from commit e1552fd)
1 parent 879d8c4 commit 07fff60

File tree

3 files changed

+28
-20
lines changed

3 files changed

+28
-20
lines changed

Doc/c-api/exceptions.rst

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -364,7 +364,7 @@ an error value).
364364
.. c:function:: int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...)
365365
366366
Function similar to :c:func:`PyErr_WarnFormat`, but *category* is
367-
:exc:`ResourceWarning` and it passes *source* to :func:`warnings.WarningMessage`.
367+
:exc:`ResourceWarning` and it passes *source* to :class:`!warnings.WarningMessage`.
368368
369369
.. versionadded:: 3.6
370370
@@ -647,7 +647,7 @@ Exception Classes
647647
This creates a class object derived from :exc:`Exception` (accessible in C as
648648
:c:data:`PyExc_Exception`).
649649
650-
The :attr:`__module__` attribute of the new class is set to the first part (up
650+
The :attr:`!__module__` attribute of the new class is set to the first part (up
651651
to the last dot) of the *name* argument, and the class name is set to the last
652652
part (after the last dot). The *base* argument can be used to specify alternate
653653
base classes; it can either be only one class or a tuple of classes. The *dict*
@@ -797,8 +797,8 @@ because the :ref:`call protocol <call>` takes care of recursion handling.
797797
798798
Marks a point where a recursive C-level call is about to be performed.
799799
800-
If :c:macro:`USE_STACKCHECK` is defined, this function checks if the OS
801-
stack overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it
800+
If :c:macro:`!USE_STACKCHECK` is defined, this function checks if the OS
801+
stack overflowed using :c:func:`PyOS_CheckStack`. If this is the case, it
802802
sets a :exc:`MemoryError` and returns a nonzero value.
803803
804804
The function then checks if the recursion limit is reached. If this is the
@@ -1051,11 +1051,11 @@ These are compatibility aliases to :c:data:`PyExc_OSError`:
10511051
+-------------------------------------+----------+
10521052
| C Name | Notes |
10531053
+=====================================+==========+
1054-
| :c:data:`PyExc_EnvironmentError` | |
1054+
| :c:data:`!PyExc_EnvironmentError` | |
10551055
+-------------------------------------+----------+
1056-
| :c:data:`PyExc_IOError` | |
1056+
| :c:data:`!PyExc_IOError` | |
10571057
+-------------------------------------+----------+
1058-
| :c:data:`PyExc_WindowsError` | [2]_ |
1058+
| :c:data:`!PyExc_WindowsError` | [2]_ |
10591059
+-------------------------------------+----------+
10601060
10611061
.. versionchanged:: 3.3

Doc/c-api/sys.rst

Lines changed: 21 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
Operating System Utilities
66
==========================
77

8+
89
.. c:function:: PyObject* PyOS_FSPath(PyObject *path)
910
1011
Return the file system representation for *path*. If the object is a
@@ -95,27 +96,30 @@ Operating System Utilities
9596
9697
.. c:function:: int PyOS_CheckStack()
9798
99+
.. index:: single: USE_STACKCHECK (C macro)
100+
98101
Return true when the interpreter runs out of stack space. This is a reliable
99-
check, but is only available when :c:macro:`USE_STACKCHECK` is defined (currently
102+
check, but is only available when :c:macro:`!USE_STACKCHECK` is defined (currently
100103
on certain versions of Windows using the Microsoft Visual C++ compiler).
101-
:c:macro:`USE_STACKCHECK` will be defined automatically; you should never
104+
:c:macro:`!USE_STACKCHECK` will be defined automatically; you should never
102105
change the definition in your own code.
103106
104107
108+
.. c:type:: void (*PyOS_sighandler_t)(int)
109+
110+
105111
.. c:function:: PyOS_sighandler_t PyOS_getsig(int i)
106112
107113
Return the current signal handler for signal *i*. This is a thin wrapper around
108114
either :c:func:`!sigaction` or :c:func:`!signal`. Do not call those functions
109-
directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:expr:`void
110-
(\*)(int)`.
115+
directly!
111116
112117
113118
.. c:function:: PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)
114119
115120
Set the signal handler for signal *i* to be *h*; return the old signal handler.
116121
This is a thin wrapper around either :c:func:`!sigaction` or :c:func:`!signal`. Do
117-
not call those functions directly! :c:type:`PyOS_sighandler_t` is a typedef
118-
alias for :c:expr:`void (\*)(int)`.
122+
not call those functions directly!
119123
120124
.. c:function:: wchar_t* Py_DecodeLocale(const char* arg, size_t *size)
121125
@@ -378,10 +382,8 @@ accessible to C code. They all work with the current interpreter thread's
378382
silently abort the operation by raising an error subclassed from
379383
:class:`Exception` (other errors will not be silenced).
380384
381-
The hook function is of type :c:expr:`int (*)(const char *event, PyObject
382-
*args, void *userData)`, where *args* is guaranteed to be a
383-
:c:type:`PyTupleObject`. The hook function is always called with the GIL
384-
held by the Python interpreter that raised the event.
385+
The hook function is always called with the GIL held by the Python
386+
interpreter that raised the event.
385387
386388
See :pep:`578` for a detailed description of auditing. Functions in the
387389
runtime and standard library that raise events are listed in the
@@ -390,12 +392,20 @@ accessible to C code. They all work with the current interpreter thread's
390392
391393
.. audit-event:: sys.addaudithook "" c.PySys_AddAuditHook
392394
393-
If the interpreter is initialized, this function raises a auditing event
395+
If the interpreter is initialized, this function raises an auditing event
394396
``sys.addaudithook`` with no arguments. If any existing hooks raise an
395397
exception derived from :class:`Exception`, the new hook will not be
396398
added and the exception is cleared. As a result, callers cannot assume
397399
that their hook has been added unless they control all existing hooks.
398400
401+
.. c:namespace:: NULL
402+
.. c:type:: int (*Py_AuditHookFunction) (const char *event, PyObject *args, void *userData)
403+
404+
The type of the hook function.
405+
*event* is the C string event argument passed to :c:func:`PySys_Audit`.
406+
*args* is guaranteed to be a :c:type:`PyTupleObject`.
407+
*userData* is the argument passed to PySys_AddAuditHook().
408+
399409
.. versionadded:: 3.8
400410
401411

Doc/tools/.nitignore

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@
33
# Keep lines sorted lexicographically to help avoid merge conflicts.
44

55
Doc/c-api/descriptor.rst
6-
Doc/c-api/exceptions.rst
76
Doc/c-api/float.rst
87
Doc/c-api/gcsupport.rst
98
Doc/c-api/init.rst
@@ -12,7 +11,6 @@ Doc/c-api/intro.rst
1211
Doc/c-api/module.rst
1312
Doc/c-api/stable.rst
1413
Doc/c-api/structures.rst
15-
Doc/c-api/sys.rst
1614
Doc/c-api/type.rst
1715
Doc/c-api/typeobj.rst
1816
Doc/extending/extending.rst

0 commit comments

Comments
 (0)