_getframe(): New sys module function for getting at the stack frame.

Implements and closes SF patch #102106, with Guido's suggested
documentation changes.

1 files changed, 11 insertions, 0 deletions

diff --git a/Doc/lib/libsys.tex b/Doc/lib/libsys.tex
index 8199b1b..2fda26e 100644
--- a/Doc/lib/libsys.tex
+++ b/Doc/lib/libsys.tex
@@ -161,6 +161,17 @@ from causing an overflow of the C stack and crashing Python.  It can
 be set by \function{setrecursionlimit()}.
 \end{funcdesc}
 
+\begin{funcdesc}{_getframe}{\optional{depth}}
+Return a frame object from the call stack.  If optional integer
+\var{depth} is given, return the frame object that many calls below
+the top of the stack.  If that is deeper than the call stack,
+\exception{ValueError} is raised.  The default for \var{depth} is
+zero, returning the frame at the top of the call stack.
+
+This function should be used for internal and specialized
+purposes only.
+\end{funcdesc}
+
 \begin{datadesc}{hexversion}
 The version number encoded as a single integer.  This is guaranteed to
 increase with each version, including proper support for