mirrors/cpython
0
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2024-11-24 10:24:35 +08:00
Code Issues Packages Projects Releases Wiki Activity

gh-101578: Amend exception docs (#102057)

Browse Source 
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
This commit is contained in:
Erlend E. Aasland 2023-02-21 09:15:49 +01:00 committed by GitHub
parent 6f25657b83
commit 02d9f1504b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 25 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
Doc/c-api/exceptions.rst
View File

@ -438,7 +438,9 @@ Querying the error indicator
.. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
As of 3.12, this function is deprecated. Use :c:func:`PyErr_GetRaisedException` instead.
.. deprecated:: 3.12
Use :c:func:`PyErr_GetRaisedException` instead.
Retrieve the error indicator into three variables whose addresses are passed.
If the error indicator is not set, set all three variables to ``NULL``. If it is
@ -447,8 +449,10 @@ Querying the error indicator
.. note::
This function is normally only used by code that needs to catch exceptions or
by code that needs to save and restore the error indicator temporarily, e.g.::
This function is normally only used by legacy code that needs to catch
exceptions or save and restore the error indicator temporarily.
For example::
{
PyObject *type, *value, *traceback;
@ -459,15 +463,17 @@ Querying the error indicator
PyErr_Restore(type, value, traceback);
}
.. deprecated:: 3.12
.. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)
As of 3.12, this function is deprecated. Use :c:func:`PyErr_SetRaisedException` instead.
.. deprecated:: 3.12
Set the error indicator from the three objects. If the error indicator is
already set, it is cleared first. If the objects are ``NULL``, the error
Use :c:func:`PyErr_SetRaisedException` instead.
Set the error indicator from the three objects,
*type*, *value*, and *traceback*,
clearing the existing exception if one is set.
If the objects are ``NULL``, the error
indicator is cleared. Do not pass a ``NULL`` type and non-``NULL`` value or
traceback. The exception type should be a class. Do not pass an invalid
exception type or value. (Violating these rules will cause subtle problems
@ -478,18 +484,17 @@ Querying the error indicator
.. note::
This function is normally only used by code that needs to save and restore the
error indicator temporarily. Use :c:func:`PyErr_Fetch` to save the current
error indicator.
.. deprecated:: 3.12
This function is normally only used by legacy code that needs to
save and restore the error indicator temporarily.
Use :c:func:`PyErr_Fetch` to save the current error indicator.
.. c:function:: void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb)
As of 3.12, this function is deprecated.
Use :c:func:`PyErr_GetRaisedException` instead of :c:func:`PyErr_Fetch` to avoid
any possible de-normalization.
.. deprecated:: 3.12
Use :c:func:`PyErr_GetRaisedException` instead,
to avoid any possible de-normalization.
Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below
can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is
@ -507,8 +512,6 @@ Querying the error indicator
PyException_SetTraceback(val, tb);
}
.. deprecated:: 3.12
.. c:function:: PyObject* PyErr_GetHandledException(void)
@ -756,14 +759,12 @@ Exception Objects
.. c:function:: PyObject* PyException_GetArgs(PyObject *ex)
Return args of the given exception as a new reference,
as accessible from Python through :attr:`args`.
Return :attr:`~BaseException.args` of exception *ex*.
.. c:function:: void PyException_SetArgs(PyObject *ex, PyObject *args)
Set the args of the given exception,
as accessible from Python through :attr:`args`.
Set :attr:`~BaseException.args` of exception *ex* to *args*.
.. _unicodeexceptions:

2
Doc/data/refcounts.dat
View File

@ -839,6 +839,8 @@ PyEval_EvalFrameEx:int:throwflag::
PyEval_MergeCompilerFlags:int:::
PyEval_MergeCompilerFlags:PyCompilerFlags*:cf::
PyException_GetArgs:PyObject*::+1:
PyException_GetCause:PyObject*::+1:
PyException_GetCause:PyObject*:ex:0: