Skip to content

gh-67377: Document that PyErr_SetString, etc. chain exceptions #20329

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

Open
wants to merge 6 commits into
base: main
Choose a base branch
from

Conversation

cjerdonek
Copy link
Member

@cjerdonek cjerdonek commented May 23, 2020

@cjerdonek cjerdonek closed this May 23, 2020
@cjerdonek cjerdonek reopened this May 23, 2020
@cjerdonek cjerdonek closed this May 23, 2020
@cjerdonek cjerdonek reopened this May 23, 2020
@cjerdonek cjerdonek closed this May 24, 2020
@cjerdonek cjerdonek reopened this May 24, 2020
@serhiy-storchaka
Copy link
Member

serhiy-storchaka commented May 25, 2020

It is not clear what "caught" mean. The rough equivalent of the Python code:

try:
    ...
except AttributeError:
    raises TypeError

is the C code:

...
if (result == NULL) {
    if (PyErr_ExceptionMatches(PyExc_AttributeError)) {
        PyErr_SetNone(PyExc_TypeError);
    }
    return NULL;
}

Is an AttributeError exception caught here?

@cjerdonek
Copy link
Member Author

The precise condition inside _PyErr_SetObject is if _PyErr_GetTopmostException returns a non-None value:

cpython/Python/errors.c

Lines 117 to 119 in be63019

exc_value = _PyErr_GetTopmostException(tstate)->exc_value;
if (exc_value != NULL && exc_value != Py_None) {
/* Implicit exception chaining */

However, this is a private function.

So some other ways to say this (without reference to C functions) are (1) if there's an "active exception" (the wording in do_raise()'s RuntimeError message), (2) if an exception is currently being handled (anywhere on the stack), or (3) if sys.exc_info() would return an exception.

sys.exc_info()'s documentation
https://docs.python.org/3/library/sys.html#sys.exc_info

Do you have a preference?

@JelleZijlstra JelleZijlstra changed the title bpo-23188: Document that PyErr_SetString, etc. chain exceptions gh-67377: Document that PyErr_SetString, etc. chain exceptions Apr 14, 2022
@JelleZijlstra
Copy link
Member

I would say "active exception". Could you make that change? In that case, I can merge this PR unless @serhiy-storchaka has further comments.

@serhiy-storchaka
Copy link
Member

Is the term "active exception" explained anywhere? Should not a link be added?

@JelleZijlstra
Copy link
Member

The term used by the PyErr_Occurred docs is "the error indicator is set".

@serhiy-storchaka serhiy-storchaka added needs backport to 3.10 only security fixes needs backport to 3.11 only security fixes and removed needs backport to 3.9 only security fixes labels May 20, 2022
@hugovk hugovk removed the needs backport to 3.10 only security fixes label Apr 7, 2023
@furkanonder
Copy link
Contributor

LGTM. @serhiy-storchaka Can you review it?

@hugovk hugovk added the needs backport to 3.12 only security fixes label Sep 11, 2023
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
@@ -124,7 +124,10 @@ Raising exceptions

These functions help you set the current thread's error indicator.
For convenience, some of these functions will always return a
``NULL`` pointer for use in a ``return`` statement.
``NULL`` pointer for use in a ``return`` statement. Also, for all of the
functions in this subsection, if an exception has already been caught,
Copy link
Member

Choose a reason for hiding this comment

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

@serhiy-storchaka raised an issue with this terminology, I don't think the previous reviewers' comments have been addressed: #20329 (comment)

@hugovk hugovk removed the needs backport to 3.11 only security fixes label Apr 11, 2024
@serhiy-storchaka serhiy-storchaka added the needs backport to 3.13 bugs and security fixes label May 9, 2024
@hugovk hugovk removed the needs backport to 3.12 only security fixes label Apr 10, 2025
@python-cla-bot
Copy link

python-cla-bot bot commented Apr 18, 2025

All commit authors signed the Contributor License Agreement.

CLA signed

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
awaiting changes docs Documentation in the Doc dir needs backport to 3.13 bugs and security fixes
Projects
Status: Todo
Development

Successfully merging this pull request may close these issues.