[Python-checkins] python/dist/src/Doc/lib libinspect.tex, 1.13.10.1, 1.13.10.2

Thu Jan 1 02:22:48 EST 2004

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv14635
Modified Files:
 Tag: release23-maint
	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.13.10.1
retrieving revision 1.13.10.2
diff -C2 -d -r1.13.10.1 -r1.13.10.2
*** libinspect.tex	31 Oct 2003 15:34:16 -0000	1.13.10.1
--- libinspect.tex	1 Jan 2004 07:22:46 -0000	1.13.10.2
***************
*** 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}