# [Python-checkins] python/dist/src/Doc/lib libinspect.tex,1.14,1.15

fdrake at users.sourceforge.net fdrake at users.sourceforge.net
Thu Jan 1 02:21:16 EST 2004

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv14509

Modified Files:
libinspect.tex
Log Message:
in the section "The interpreter stack":
- rearranged a bit to avoid duplicated information
- provide more complete (and hopefully less confusing) descriptions of
the return values for most of these functions
(close SF bug #563298)

Index: libinspect.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libinspect.tex,v
retrieving revision 1.14
retrieving revision 1.15
diff -C2 -d -r1.14 -r1.15
*** libinspect.tex	31 Oct 2003 15:34:40 -0000	1.14
--- libinspect.tex	1 Jan 2004 07:21:14 -0000	1.15
***************
*** 305,312 ****
lines of context from the source code, and the index of the current
line within that list.
- The optional \var{context} argument specifies the number of lines of
- context to return, which are centered around the current line.

! \warning{Keeping references to frame objects, as found in
the first element of the frame records these functions return, can
cause your program to create reference cycles.  Once a reference cycle
--- 305,311 ----
lines of context from the source code, and the index of the current
line within that list.

! \begin{notice}[warning]
! Keeping references to frame objects, as found in
the first element of the frame records these functions return, can
cause your program to create reference cycles.  Once a reference cycle
***************
*** 316,336 ****
created, it is important to ensure they are explicitly broken to avoid
the delayed destruction of objects and increased memory consumption
! which occurs.}

\begin{funcdesc}{getframeinfo}{frame\optional{, context}}
Get information about a frame or traceback object.  A 5-tuple
is returned, the last five elements of the frame's frame record.
-   The optional second argument specifies the number of lines of context
-   to return, which are centered around the current line.
\end{funcdesc}

\begin{funcdesc}{getouterframes}{frame\optional{, context}}
!   Get a list of frame records for a frame and all higher (calling)
!   frames.
\end{funcdesc}

\begin{funcdesc}{getinnerframes}{traceback\optional{, context}}
!   Get a list of frame records for a traceback's frame and all lower
!   frames.
\end{funcdesc}

--- 315,358 ----
created, it is important to ensure they are explicitly broken to avoid
the delayed destruction of objects and increased memory consumption
! which occurs.
!
! Though the cycle detector will catch these, destruction of the frames
! (and local variables) can be made deterministic by removing the cycle
! in a \keyword{finally} clause.  This is also important if the cycle
! detector was disabled when Python was compiled or using
! \function{\refmodule{gc}.disable()}.  For example:
!
! \begin{verbatim}
! def handle_stackframe_without_leak():
!     frame = inspect.currentframe()
!     try:
!         # do something with the frame
!     finally:
!         del frame
! \end{verbatim}
! \end{notice}
!
! The optional \var{context} argument supported by most of these
! functions specifies the number of lines of context to return, which
! are centered around the current line.

\begin{funcdesc}{getframeinfo}{frame\optional{, context}}
Get information about a frame or traceback object.  A 5-tuple
is returned, the last five elements of the frame's frame record.
\end{funcdesc}

\begin{funcdesc}{getouterframes}{frame\optional{, context}}
!   Get a list of frame records for a frame and all outer frames.  These
!   frames represent the calls that lead to the creation of \var{frame}.
!   The first entry in the returned list represents \var{frame}; the
!   last entry represents the outermost call on \var{frame}'s stack.
\end{funcdesc}

\begin{funcdesc}{getinnerframes}{traceback\optional{, context}}
!   Get a list of frame records for a traceback's frame and all inner
!   frames.  These frames represent calls made as a consequence of
!   \var{frame}.  The first entry in the list represents
!   \var{traceback}; the last entry represents where the exception was
!   raised.
\end{funcdesc}

***************
*** 340,365 ****

\begin{funcdesc}{stack}{\optional{context}}
!   Return a list of frame records for the stack above the caller's
!   frame.
\end{funcdesc}

\begin{funcdesc}{trace}{\optional{context}}
!   Return a list of frame records for the stack below the current
!   exception.
\end{funcdesc}
-
- Stackframes stored directly or indirectly in local variables can
- easily cause reference cycles.  Though the cycle detector will catch
- these, destruction of the frames (and local variables) can be made
- deterministic by removing the cycle in a \keyword{finally} clause.
- This is also important if the cycle detector was disabled when Python
- was compiled or using \function{gc.disable()}.  For example:
-
- \begin{verbatim}
- def handle_stackframe_without_leak():
-     frame = inspect.currentframe()
-     try:
-         # do something with the frame
-     finally:
-         del frame
- \end{verbatim}
--- 362,374 ----

\begin{funcdesc}{stack}{\optional{context}}
!   Return a list of frame records for the caller's stack.  The first
!   entry in the returned list represents the caller; the last entry
!   represents the outermost call on the stack.
\end{funcdesc}

\begin{funcdesc}{trace}{\optional{context}}
!   Return a list of frame records for the stack between the current
!   frame and the frame in which an exception currently being handled
!   was raised in.  The first entry in the list represents the caller;
!   the last entry represents where the exception was raised.
\end{funcdesc}