Cython defines __Pyx_PyErr_GetTopmostException() in Cython/Utility/Exceptions.c which is a copy of Python PyErr_GetTopmostException(). It seems like Cython cannot use PyErr_GetActiveException() but would need a function taking a tstate parameter.

In python you can only access this exception, so it's sys.exception() but in the C api there are two exceptions we can access - the in-flight (raised) exception or this (caught) exception. So I think we need to be clear which one this is.

Is it clear (judging by name only) which exception is the "active" one? Raised/in-flight or caught? :)

Would it be possible to use the same wording in the documentation of functions added by this PR, in PyErr_GetExcInfo() and in sys.exception() documentation? My remark is about "the exception instance that is currently being handled" in sys.exception() doc:
https://docs.python.org/dev/library/sys.html#sys.exception

Maybe add also a link from PyErr_GetExcInfo() to PyErr_GetActiveException() in the doc.

Since this function is an unusal use case, maybe give it an even more explicit name? PyErr_GetCaughtException()?

How about GetHandledException()?

(I'm not sure Caught accurately describes the timeframe in which an exception is "active").

Would it be possible to use the same wording in the documentation of functions added by this PR, in PyErr_GetExcInfo() and in sys.exception() documentation? My remark is about "the exception instance that is currently being handled" in sys.exception() doc: https://docs.python.org/dev/library/sys.html#sys.exception

sys.exception is in python space, where you don't have access to any other exception so I think the c-level wording might just add confusion. I agree though that the current wording is not great, in particular I'm not sure we need to talk about the frame stack. How about I reword the sys.exception() doc like this:

This function, when called while an exception handler (such as an ``except`` or ``except*`` clause) is executing, returns the exception instance that was caught by this handler. When exception handlers are nested within one another, only the exception handled by the innermost handler is accessible.

If no exception handler is executing, this function returns None.

Maybe add also a link from PyErr_GetExcInfo() to PyErr_GetActiveException() in the doc.

Sure.

I made all the changes suggested in reviews so far (thanks!) except the name change.

I propose SetHandledException/GetHandledException. Does this sound good?

I propose SetHandledException/GetHandledException. Does this sound good?

IMO , that's easier to understand. +1

@vstinner @encukou @markshannon Any last thoughts on this? Should we include this in 3.11?

@pablogsal FYI.

@vstinner @encukou @markshannon Any last thoughts on this? Should we include this in 3.11?

@pablogsal FYI.

I'm fine including this into 3.11, but please merge it at least one week before the beta to allow to test it a bit.