[Python-checkins] python/dist/src/Doc/lib libshelve.tex,1.15,1.16

[montanaro@users.sourceforge.net]

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

Modified Files:
	libshelve.tex 
Log Message:
Add support for binary pickles to the shelve module.  In some situations
this can result in significantly smaller files.  All classes as well as the
open function now accept an optional binary parameter, which defaults to
False for backward compatibility.  Added a small test suite, updated the
libref documentation (including documenting the exported classes and fixing
a few other nits) and added a note about the change to Misc/NEWS.



Index: libshelve.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libshelve.tex,v
retrieving revision 1.15
retrieving revision 1.16
diff -C2 -d -r1.15 -r1.16
*** libshelve.tex	15 Nov 2002 06:46:13 -0000	1.15
--- libshelve.tex	8 Dec 2002 18:36:23 -0000	1.16
***************
*** 20,24 ****
  import shelve
  
! d = shelve.open(filename) # open, with (g)dbm filename -- no suffix
  
  d[key] = data   # store data at key (overwrites old data if
--- 20,25 ----
  import shelve
  
! d = shelve.open(filename) # open -- file may get suffix added by low-level
!                           # library
  
  d[key] = data   # store data at key (overwrites old data if
***************
*** 55,60 ****
  
  \item
! Dependent on the implementation, closing a persistent dictionary may
! or may not be necessary to flush changes to disk.
  
  \item
--- 56,63 ----
  
  \item
! Depending on the implementation, closing a persistent dictionary may
! or may not be necessary to flush changes to disk.  The \method{__del__}
! method of the \class{Shelf} class calls the \method{close} method, so the
! programmer generally need not do this explicitly.
  
  \item
***************
*** 68,75 ****
  \end{itemize}
  
  
  \begin{seealso}
    \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
!   \seemodule{dbhash}{BSD \code{db} database interface.}
    \seemodule{dbm}{Standard \UNIX{} database interface.}
    \seemodule{dumbdbm}{Portable implementation of the \code{dbm} interface.}
--- 71,105 ----
  \end{itemize}
  
+ \begin{classdesc}{Shelf}{dict\optional{, binary=False}}
+ A subclass of \class{UserDict.DictMixin} which stores pickled values in the
+ \var{dict} object.  If the \var{binary} parameter is \constant{True}, binary
+ pickles will be used.  This can provide much more compact storage than plain
+ text pickles, depending on the nature of the objects stored in the databse.
+ \end{classdesc}
+ 
+ \begin{classdesc}{BsdDbShelf}{dict\optional{, binary=False}}
+ A subclass of \class{Shelf} which exposes \method{first}, \method{next},
+ {}\method{previous}, \method{last} and \method{set_location} which are
+ available in the \module{bsddb} module but not in other database modules.
+ The \var{dict} object passed to the constructor must support those methods.
+ This is generally accomplished by calling one of \function{bsddb.hashopen},
+ \function{bsddb.btopen} or \function{bsddb.rnopen}.  The optional
+ \var{binary} parameter has the same interpretation as for the \class{Shelf}
+ class. 
+ \end{classdesc}
+ 
+ \begin{classdesc}{DbfilenameShelf}{dict\optional{, flag='c'}\optional{, binary=False}}
+ A subclass of \class{Shelf} which accepts a filename instead of a dict-like
+ object.  The underlying file will be opened using \function{anydbm.open}.
+ By default, the file will be created and opened for both read and write.
+ The optional \var{binary} parameter has the same interpretation as for the
+ \class{Shelf} class.
+ \end{classdesc}
  
  \begin{seealso}
    \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
!   \seemodule{bsddb}{BSD \code{db} database interface.}
!   \seemodule{dbhash}{Thin layer around the \module{bsddb} which provides an
!   \function{open} function like the other database modules.}
    \seemodule{dbm}{Standard \UNIX{} database interface.}
    \seemodule{dumbdbm}{Portable implementation of the \code{dbm} interface.}