Skip to content

Docs, sys.unraisablehook: emphasize warning and add accurate markups #108105

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 1 commit into from
Aug 18, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 21 additions & 17 deletions Doc/library/sys.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1811,35 +1811,39 @@ always available.

The *unraisable* argument has the following attributes:

* *exc_type*: Exception type.
* *exc_value*: Exception value, can be ``None``.
* *exc_traceback*: Exception traceback, can be ``None``.
* *err_msg*: Error message, can be ``None``.
* *object*: Object causing the exception, can be ``None``.
* :attr:`!exc_type`: Exception type.
* :attr:`!exc_value`: Exception value, can be ``None``.
* :attr:`!exc_traceback`: Exception traceback, can be ``None``.
* :attr:`!err_msg`: Error message, can be ``None``.
* :attr:`!object`: Object causing the exception, can be ``None``.

The default hook formats *err_msg* and *object* as:
The default hook formats :attr:`!err_msg` and :attr:`!object` as:
``f'{err_msg}: {object!r}'``; use "Exception ignored in" error message
if *err_msg* is ``None``.
if :attr:`!err_msg` is ``None``.

:func:`sys.unraisablehook` can be overridden to control how unraisable
exceptions are handled.

Storing *exc_value* using a custom hook can create a reference cycle. It
should be cleared explicitly to break the reference cycle when the
exception is no longer needed.
.. seealso::

:func:`excepthook` which handles uncaught exceptions.

.. warning::

Storing *object* using a custom hook can resurrect it if it is set to an
object which is being finalized. Avoid storing *object* after the custom
hook completes to avoid resurrecting objects.
Storing :attr:`!exc_value` using a custom hook can create a reference cycle.
It should be cleared explicitly to break the reference cycle when the
exception is no longer needed.

See also :func:`excepthook` which handles uncaught exceptions.
Storing :attr:`!object` using a custom hook can resurrect it if it is set to an
object which is being finalized. Avoid storing :attr:`!object` after the custom
hook completes to avoid resurrecting objects.

.. audit-event:: sys.unraisablehook hook,unraisable sys.unraisablehook

Raise an auditing event ``sys.unraisablehook`` with arguments
``hook``, ``unraisable`` when an exception that cannot be handled occurs.
The ``unraisable`` object is the same as what will be passed to the hook.
If no hook has been set, ``hook`` may be ``None``.
*hook*, *unraisable* when an exception that cannot be handled occurs.
The *unraisable* object is the same as what will be passed to the hook.
If no hook has been set, *hook* may be ``None``.

.. versionadded:: 3.8

Expand Down