[Python-checkins] python/dist/src/Doc/lib libshelve.tex,1.17,1.18
montanaro@users.sourceforge.net
montanaro@users.sourceforge.net
Mon, 20 Jan 2003 17:38:49 -0800
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}