[Python-checkins] python/dist/src/Doc/lib libshelve.tex,1.19,1.20
loewis@users.sourceforge.net
loewis@users.sourceforge.net
Sat, 19 Apr 2003 13:59:04 -0700
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv7812/Doc/lib
Modified Files:
libshelve.tex
Log Message:
Patch #553171: Add writeback parameter. Also add protocol parameter.
Index: libshelve.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libshelve.tex,v
retrieving revision 1.19
retrieving revision 1.20
diff -C2 -d -r1.19 -r1.20
*** libshelve.tex 21 Jan 2003 01:52:39 -0000 1.19
--- libshelve.tex 19 Apr 2003 20:59:02 -0000 1.20
***************
*** 14,18 ****
\refstmodindex{pickle}
! \begin{funcdesc}{open}{filename\optional{,flag='c'\optional{,binary=\code{False}}}}
Open a persistent dictionary. The filename specified is the base filename
for the underlying database. As a side-effect, an extension may be added to
--- 14,18 ----
\refstmodindex{pickle}
! \begin{funcdesc}{open}{filename\optional{,flag='c'\optional{,protocol=\code{None}\optional{,writeback=\code{False}\optional{,binary=\code{None}}}}}}
Open a persistent dictionary. The filename specified is the base filename
for the underlying database. As a side-effect, an extension may be added to
***************
*** 20,26 ****
underlying database file is opened for reading and writing. The optional
{}\var{flag} pararameter has the same interpretation as the \var{flag}
! parameter of \function{anydbm.open}. 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}
--- 20,41 ----
underlying database file is opened for reading and writing. The optional
{}\var{flag} pararameter has the same interpretation as the \var{flag}
! parameter of \function{anydbm.open}.
!
! By default, version 0 pickles are used to serialize values.
! The version of the pickle protocol can be specified with the
! \var{protocol} parameter. \versionchanged[The \var{protocol}
! parameter was added. The \var{binary} parameter is deprecated
! and provided for backwards compatibility only]{2.3}
!
! By default, mutations to persistent-dictionary mutable entries are not
! automatically written back. If the optional \var{writeback} parameter
! is set to {}\var{True}, all entries accessed are cached in memory, and
! written back at close time; this can make it handier to mutate mutable
! entries in the persistent dictionary, but, if many entries are
! accessed, it can consume vast amounts of memory for the cache, and it
! can make the close operation very slow since all accessed entries are
! written back (there is no way to determine which accessed entries are
! mutable, nor which ones were actually mutated).
!
\end{funcdesc}
***************
*** 62,92 ****
\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 \code{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 database.
\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}{filename\optional{, flag='c'\optional{, binary=False}}}
! A subclass of \class{Shelf} which accepts a \var{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{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}
--- 77,121 ----
\end{itemize}
! \begin{classdesc}{Shelf}{dict\optional{, protocol=None\optional{, writeback=False\optional{, binary=None}}}}
A subclass of \class{UserDict.DictMixin} which stores pickled values in the
! \var{dict} object.
!
! By default, version 0 pickles are used to serialize values. The
! version of the pickle protocol can be specified with the
! \var{protocol} parameter. See the \module{pickle} documentation for a
! discussion of the pickle protocols. \versionchanged[The \var{protocol}
! parameter was added. The \var{binary} parameter is deprecated and
! provided for backwards compatibility only]{2.3}
!
! If the \var{writeback} parameter is \code{True}, the object will hold a
! cache of all entries accessed and write them back to the \var{dict} at
! sync and close times. This allows natural operations on mutable entries,
! but can consume much more memory and make sync and close take a long time.
\end{classdesc}
! \begin{classdesc}{BsdDbShelf}{dict\optional{, protocol=None\optional{, writeback=False\optional{, binary=None}}}}
!
! 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{protocol}, \var{writeback}, and \var{binary} parameters have the
! same interpretation as for the \class{Shelf} class.
!
\end{classdesc}
! \begin{classdesc}{DbfilenameShelf}{filename\optional{, flag='c'\optional{, protocol=None\optional{, writeback=False\optional{, binary=None}}}}}
! A subclass of \class{Shelf} which accepts a \var{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{flag} parameter has
! the same interpretation as for the \function{open} function. The
! optional \var{protocol}, \var{writeback}, and \var{binary} parameters
! have the same interpretation as for the \class{Shelf} class.
!
\end{classdesc}
***************
*** 104,108 ****
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
--- 133,137 ----
d[key] = data # store data at key (overwrites old data if
# using an existing key)
! data = d[key] # retrieve a COPY of data at key (raise KeyError if no
# such key)
del d[key] # delete data stored at key (raises KeyError
***************
*** 110,113 ****
--- 139,153 ----
flag = d.has_key(key) # true if the key exists
list = d.keys() # a list of all existing keys (slow!)
+
+ # as d was opened WITHOUT writeback=True, beware:
+ d['xx'] = range(4) # this works as expected, but...
+ d['xx'].append(5) # *this doesn't!* -- d['xx'] is STILL range(4)!!!
+ # having opened d without writeback=True, you need to code carefully:
+ temp = d['xx'] # extracts the copy
+ temp.append(5) # mutates the copy
+ d['xx'] = temp # stores the copy right back, to persist it
+ # or, d=shelve.open(filename,writeback=True) would let you just code
+ # d['xx'].append(5) and have it work as expected, BUT it would also
+ # consume more memory and make the d.close() operation slower.
d.close() # close it