Skip to content

Commit

Permalink
Docs: emphasise warning and add accurate markups for sys.unraisableho…
Browse files Browse the repository at this point in the history
…ok (#108105)
  • Loading branch information
erlend-aasland authored Aug 18, 2023
1 parent 02079b0 commit cc58ec9
Showing 1 changed file with 21 additions and 17 deletions.
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

0 comments on commit cc58ec9

Please sign in to comment.