Skip to content

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

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.

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 11 commits into from
Feb 11, 2024
14 changes: 7 additions & 7 deletions Doc/c-api/exceptions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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*
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
29 changes: 19 additions & 10 deletions Doc/c-api/sys.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -342,10 +346,15 @@ 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.
.. 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()),
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wait, I used parentheses to denote that it is a preliminary text, and that you should rewrite it in good English. Perhaps it is even better to describe parameters not in terms of PySys_Audit() or PySys_AuditTuple(), but in more general terms. Look at sys.audit(). Perhaps "event is a C string identifying the event" is enough.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, I recognized "(...)" as a placeholder, not the more elaborate parenthesized phrasing. Will get back to it.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps "event is a C string identifying the event" is enough.

I thought about that, but am not familiar enough with the C API documentation to know that descriptions of function prototypes don't simply rely on the actual prototype.

*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
Expand Down
1 change: 0 additions & 1 deletion Doc/tools/.nitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down