Add sys.get_caller() function

[markshannon]

def get_caller(level = 1) -> types.FunctionType:
     "Gets the nth caller of the caller"

e.g.

def bar():
    return sys.get_caller()
def foo():
    return bar()

>>> foo()
<function foo...>

def bar():
    return sys.get_caller(0)

>>> bar()
<function bar...>

We can then use this wherever we currently use sys.getframe() to avoid creating frame objects.
E.g sys._getframe(3).f_globals can be replaced with sys.get_caller(2).__globals__.

sys._getframe() is currently used in:

• asyncio (only for debugging, I think)
• logging
• warnings
• typing

And many tests.

The implementation is quite simple and cheap:

f = tstate->frame;  // Caller's frame.
for (i = 0; i < level; i++) {
    f = f->previous; // Need NULL check here with proper error handling.
}
return Py_INCREF(f->f_func);

[gvanrossum]

Oh, so this doesn't replace sys._getframe() everywhere, since it doesn't return the frame, only the function object. So if you want to look at the locals or the program counter you're out of luck.

[JelleZijlstra]

I'd be interested in helping out with this, I can put up a PR sometime this week.

[JelleZijlstra]

https://bugs.python.org/issue46543

[JelleZijlstra]

python/cpython#30950

[gvanrossum]

There are some interesting questions, what happens if the frame corresponds to a class or module. I guess we'll find out. :-)

[ericsnowcurrently]

FWIW, in 2011 I proposed adding something like f_func to frame objects (https://bugs.python.org/issue12857). I believe the idea and motivation are similar. So the discussion on that issue may be relevant.

There was also some discussion on python-ideas:

• (start) https://mail.python.org/pipermail/python-ideas/2011-August/011053.html
• (@gvanrossum's feedback) https://mail.python.org/pipermail/python-ideas/2011-August/011062.html

[markshannon]

The motivation is similar to https://bugs.python.org/issue12857, but this suggestion would skip the frame, so instead of sys._getframe(2).f_func, you would call sys.get_caller(1) and avoid materializing the frame.

I suspect that with a bit of tweaking of the temporary function created to build a module or class, we could provide all the information that people were after.

[markshannon]

The function for a module or class just wraps the code object, taking it's name from the code object, and it's globals and builtins from the class/module.

[gvanrossum]

Maybe the argument should have the same numerical value as the corresponding sys._getframe() call? We could make getcaller(0) return the current function. Having them be different would just be confusing.

[brandtbucher]

For anyone curious about modules or classes, they actually look fine:

from gc import get_referrers
from sys import _getframe
from types import FunctionType

def print_current_function() -> None:
    code = _getframe(1).f_code
    funcs = [o for o in get_referrers(code) if isinstance(o, FunctionType)]
    if not funcs:
        raise RuntimeError("No function for current frame!")
    if 1 < len(funcs):
        raise RuntimeError("Multiple candidate functions found!")
    print(funcs[0])

# This succeeds on 3.11, but raises "RuntimeError: No function for current frame!" on 3.10!
print_current_function()  # <function <module> at ...>

class C:
    print_current_function()  # <function C at ...>

[JelleZijlstra]

Interesting, I wonder whether we should be concerned about exposing these functions as they're arguably implementation details.

[gvanrossum]

No more than sys._getframe, right? Maybe name it sys._getcaller?

[brandtbucher]

We could do sys._getfunc. That way it's more intuitive that sys._getfunc(0) returns the current function (sys._getcaller(0) seems to me like it would return the calling function).

[cfbolz]

Yeah, while implementing getcaller would be relatively efficient for us, I would welcome using the name _getcaller to make clear that it's quite an implementation-dependant api (implicitly many things in sys are, but some are more implementation specific than others).

[JelleZijlstra]

I put up a draft PR at python/cpython#30950.

I was able to replace _getframe calls in collections, doctest, enum, and typing, which just need the globals of the callsites.

The asyncio and warnings callsites need f_lineno and f_back, which we can't get from sys._getfunc(). We could emulate f_back by doing sys._getfunc(i + 1), but that would be quadratic.

There are also some callsites (e.g., bdb) which pass the frame to a tracing API. I assume that also needs the full frame.

[markshannon]

I don't like "getfunc". What function? getcaller describes what function. I do get that it is a potential trap for off-by-one errors.
How about getfunc_forframe(n)?
Can we also drop the underscore prefix? All Python implementations should be able to implement this efficient, as it doesn't require materialization of frame objects, or even for frames to exist at all.

[gvanrossum]

I'd settle for sys._getcaller(n) where n has the same meaning as for sys._getframe(n). I'd like to keep the leading _ because even if this can be implemented efficiently, I worry about its over-use.

[warsaw]

For historical context on why I originally added sys._getframe() along with links to existing important use cases.