[Python-checkins] CVS: python/dist/src/Doc/lib libzlib.tex,1.26,1.27

[Jeremy Hylton]

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

Modified Files:
	libzlib.tex 
Log Message:
[ #403753 ] zlib decompress; uncontrollable memory usage

Mostly by Toby Dickenson and Titus Brown.

Add an optional argument to a decompression object's decompress()
method.  The argument specifies the maximum length of the return
value.  If the uncompressed data exceeds this length, the excess data
is stored as the unconsumed_tail attribute.  (Not to be confused with
unused_data, which is a separate issue.)

Difference from SF patch: Default value for unconsumed_tail is ""
rather than None.  It's simpler if the attribute is always a string.



Index: libzlib.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libzlib.tex,v
retrieving revision 1.26
retrieving revision 1.27
diff -C2 -d -r1.26 -r1.27
*** libzlib.tex	2001/10/15 13:45:49	1.26
--- libzlib.tex	2001/10/16 20:39:49	1.27
***************
*** 121,125 ****
  \end{methoddesc}
  
! Decompression objects support the following methods, and a single attribute:
  
  \begin{memberdesc}{unused_data}
--- 121,125 ----
  \end{methoddesc}
  
! Decompression objects support the following methods, and two attributes:
  
  \begin{memberdesc}{unused_data}
***************
*** 136,140 ****
  \end{memberdesc}
  
! \begin{methoddesc}[Decompress]{decompress}{string}
  Decompress \var{string}, returning a string containing the
  uncompressed data corresponding to at least part of the data in
--- 136,146 ----
  \end{memberdesc}
  
! \begin{memberdesc}{unconsumed_tail}
! A string that contains any data that was not consumed by the last
! \method{decompress} call because it exceeded the limit for the
! uncompressed data buffer.
! \end{memberdesc}
! 
! \begin{methoddesc}[Decompress]{decompress}{string}{\optional{max_length}}
  Decompress \var{string}, returning a string containing the
  uncompressed data corresponding to at least part of the data in
***************
*** 143,146 ****
--- 149,160 ----
  \method{decompress()} method.  Some of the input data may be preserved
  in internal buffers for later processing.
+ 
+ If the optional parameter \var{max_length} is supplied then the return value
+ will be no longer than \var{max_length}. This may mean that not all of the
+ compressed input can be processed; and unconsumed data will be stored
+ in the attribute \member{unconsumed_tail}. This string must be passed
+ to a subsequent call to \method{decompress()} if decompression is to
+ continue.  If \var{max_length} is not supplied then the whole input is
+ decompressed, and \member{unconsumed_tail} is an empty string.
  \end{methoddesc}