Patch #553171: Add writeback parameter. Also add protocol parameter.

1 files changed, 65 insertions, 25 deletions

diff --git a/Doc/lib/libshelve.tex b/Doc/lib/libshelve.tex
index 996c79b..17ef3e5 100644
--- a/Doc/lib/libshelve.tex
+++ b/Doc/lib/libshelve.tex
@@ -13,15 +13,30 @@ instances, recursive data types, and objects containing lots of shared
 sub-objects.  The keys are ordinary strings.
 \refstmodindex{pickle}
 
-\begin{funcdesc}{open}{filename\optional{,flag='c'\optional{,binary=\code{False}}}}
+\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
 the filename and more than one file may be created.  By default, the
 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.
+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}
 
 Shelve objects support all methods supported by dictionaries.  This eases
@@ -61,33 +76,47 @@ requires knowledge about the database implementation used.
 
 \end{itemize}
 
-\begin{classdesc}{Shelf}{dict\optional{, binary=False}}
+\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.  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.
+\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{, 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},
+\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{binary} parameter has the same interpretation as for the \class{Shelf}
-class. 
+\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{, binary=False}}}
+\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{binary} parameter has the same interpretation as for the
-{}\class{Shelf} class.
+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}
 
 \subsection{Example}
@@ -103,13 +132,24 @@ d = shelve.open(filename) # open -- file may get suffix added by low-level
 
 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
+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
                 # if no such key)
 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
 \end{verbatim}