[Python-checkins] python/dist/src/Doc/lib libshelve.tex,1.17,1.18

[montanaro@users.sourceforge.net]

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

Modified Files:
	libshelve.tex 
Log Message:
* document open() function
* promote the example and the documented restrictions to \subsection status
* document the flag parameter of the DbfilenameShelf class


Index: libshelve.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libshelve.tex,v
retrieving revision 1.17
retrieving revision 1.18
diff -C2 -d -r1.17 -r1.18
*** libshelve.tex	4 Jan 2003 01:53:38 -0000	1.17
--- libshelve.tex	21 Jan 2003 01:38:47 -0000	1.18
***************
*** 14,43 ****
  \refstmodindex{pickle}
  
! To summarize the interface (\code{key} is a string, \code{data} is an
! arbitrary object):
! 
! \begin{verbatim}
! 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
!                 # using an existing key)
! data = d[key]   # retrieve data at key (raise KeyError if no
!                 # such key)
! del d[key]      # delete data stored at key (raises KeyError
!                 # if no such key)
! flag = d.has_key(key)   # true if the key exists
! list = d.keys() # a list of all existing keys (slow!)
! 
! d.close()       # close it
! \end{verbatim}
  
! In addition to the above, shelve supports all methods that are
! supported by dictionaries.  This eases the transition from dictionary
! based scripts to those requiring persistent storage.
  
! Restrictions:
  
  \begin{itemize}
--- 14,31 ----
  \refstmodindex{pickle}
  
! \begin{funcdesc}{open}{filename\optional{,flag='c'\optional{,binary=\code{False}}}}
! Open a persistent dictionary.  By default, the underlying database file is
! opened for reading and writing.  The optional \var{flag} pararameter, if set
! to \code{'r'}, can be used to force the file to be opened in read-only mode.
! By default, ASCII pickles are used to serialize values.  If the optional
! {}\var{binary} parameter is set to \var{True}, binary pickles will be used
! instead.
! \end{funcdesc}
  
! Shelve objects support all methods supported by dictionaries.  This eases
! the transition from dictionary based scripts to those requiring persistent
! storage.
  
! \subsection{Restrictions}
  
  \begin{itemize}
***************
*** 45,51 ****
  \item
  The choice of which database package will be used
! (such as \refmodule{dbm} or \refmodule{gdbm}) depends on which interface
! is available.  Therefore it is not safe to open the database directly
! using \refmodule{dbm}.  The database is also (unfortunately) subject
  to the limitations of \refmodule{dbm}, if it is used --- this means
  that (the pickled representation of) the objects stored in the
--- 33,39 ----
  \item
  The choice of which database package will be used
! (such as \refmodule{dbm}, \refmodule{gdbm} or \refmodule{bsddb}) depends on
! which interface is available.  Therefore it is not safe to open the database
! directly using \refmodule{dbm}.  The database is also (unfortunately) subject
  to the limitations of \refmodule{dbm}, if it is used --- this means
  that (the pickled representation of) the objects stored in the
***************
*** 54,57 ****
--- 42,46 ----
  \refbimodindex{dbm}
  \refbimodindex{gdbm}
+ \refbimodindex{bsddb}
  
  \item
***************
*** 93,99 ****
--- 82,113 ----
  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{flag} parameter has the same interpretation as for the
+ \function{open} function.
  The optional \var{binary} parameter has the same interpretation as for the
  \class{Shelf} class.
  \end{classdesc}
+ 
+ \subsection{Example}
+ 
+ To summarize the interface (\code{key} is a string, \code{data} is an
+ arbitrary object):
+ 
+ \begin{verbatim}
+ 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
+                 # using an existing key)
+ data = d[key]   # retrieve data at key (raise KeyError if no
+                 # such key)
+ del d[key]      # delete data stored at key (raises KeyError
+                 # if no such key)
+ flag = d.has_key(key)   # true if the key exists
+ list = d.keys() # a list of all existing keys (slow!)
+ 
+ d.close()       # close it
+ \end{verbatim}
  
  \begin{seealso}