Doc/lib/libshelve.tex

   1 \section{\module{shelve} ---
   2          Python object persistence}
   3
   4 \declaremodule{standard}{shelve}
   5 \modulesynopsis{Python object persistence.}
   6
   7
   8 A ``shelf'' is a persistent, dictionary-like object.  The difference
   9 with ``dbm'' databases is that the values (not the keys!) in a shelf
  10 can be essentially arbitrary Python objects --- anything that the
  11 \refmodule{pickle} module can handle.  This includes most class
  12 instances, recursive data types, and objects containing lots of shared
  13 sub-objects.  The keys are ordinary strings.
  14 \refstmodindex{pickle}
  15
  16 \begin{funcdesc}{open}{filename\optional{,flag='c'\optional{,protocol=\code{None}\optional{,writeback=\code{False}}}}}
  17 Open a persistent dictionary.  The filename specified is the base filename
  18 for the underlying database.  As a side-effect, an extension may be added to
  19 the filename and more than one file may be created.  By default, the
  20 underlying database file is opened for reading and writing.  The optional
  21 {}\var{flag} parameter has the same interpretation as the \var{flag}
  22 parameter of \function{anydbm.open}.
  23
  24 By default, version 0 pickles are used to serialize values.
  25 The version of the pickle protocol can be specified with the
  26 \var{protocol} parameter. \versionchanged[The \var{protocol}
  27 parameter was added]{2.3}
  28
  29 By default, mutations to persistent-dictionary mutable entries are not
  30 automatically written back.  If the optional \var{writeback} parameter
  31 is set to {}\var{True}, all entries accessed are cached in memory, and
  32 written back at close time; this can make it handier to mutate mutable
  33 entries in the persistent dictionary, but, if many entries are
  34 accessed, it can consume vast amounts of memory for the cache, and it
  35 can make the close operation very slow since all accessed entries are
  36 written back (there is no way to determine which accessed entries are
  37 mutable, nor which ones were actually mutated).
  38
  39 \end{funcdesc}
  40
  41 Shelve objects support all methods supported by dictionaries.  This eases
  42 the transition from dictionary based scripts to those requiring persistent
  43 storage.
  44
  45 One additional method is supported:
  46 \begin{methoddesc}[Shelf]{sync}{}
  47 Write back all entries in the cache if the shelf was opened with
  48 \var{writeback} set to \var{True}. Also empty the cache and synchronize
  49 the persistent dictionary on disk, if feasible.  This is called automatically
  50 when the shelf is closed with \method{close()}.
  51 \end{methoddesc}
  52
  53 \subsection{Restrictions}
  54
  55 \begin{itemize}
  56
  57 \item
  58 The choice of which database package will be used
  59 (such as \refmodule{dbm}, \refmodule{gdbm} or \refmodule{bsddb}) depends on
  60 which interface is available.  Therefore it is not safe to open the database
  61 directly using \refmodule{dbm}.  The database is also (unfortunately) subject
  62 to the limitations of \refmodule{dbm}, if it is used --- this means
  63 that (the pickled representation of) the objects stored in the
  64 database should be fairly small, and in rare cases key collisions may
  65 cause the database to refuse updates.
  66 \refbimodindex{dbm}
  67 \refbimodindex{gdbm}
  68 \refbimodindex{bsddb}
  69
  70 \item
  71 Depending on the implementation, closing a persistent dictionary may
  72 or may not be necessary to flush changes to disk.  The \method{__del__}
  73 method of the \class{Shelf} class calls the \method{close} method, so the
  74 programmer generally need not do this explicitly.
  75
  76 \item
  77 The \module{shelve} module does not support \emph{concurrent} read/write
  78 access to shelved objects.  (Multiple simultaneous read accesses are
  79 safe.)  When a program has a shelf open for writing, no other program
  80 should have it open for reading or writing.  \UNIX{} file locking can
  81 be used to solve this, but this differs across \UNIX{} versions and
  82 requires knowledge about the database implementation used.
  83
  84 \end{itemize}
  85
  86 \begin{classdesc}{Shelf}{dict\optional{, protocol=None\optional{, writeback=False}}}
  87 A subclass of \class{UserDict.DictMixin} which stores pickled values in the
  88 \var{dict} object.
  89
  90 By default, version 0 pickles are used to serialize values.  The
  91 version of the pickle protocol can be specified with the
  92 \var{protocol} parameter. See the \module{pickle} documentation for a
  93 discussion of the pickle protocols. \versionchanged[The \var{protocol}
  94 parameter was added]{2.3}
  95
  96 If the \var{writeback} parameter is \code{True}, the object will hold a
  97 cache of all entries accessed and write them back to the \var{dict} at
  98 sync and close times.  This allows natural operations on mutable entries,
  99 but can consume much more memory and make sync and close take a long time.
 100 \end{classdesc}
 101
 102 \begin{classdesc}{BsdDbShelf}{dict\optional{, protocol=None\optional{, writeback=False}}}
 103
 104 A subclass of \class{Shelf} which exposes \method{first},
 105 \method{next}, \method{previous}, \method{last} and
 106 \method{set_location} which are available in the \module{bsddb} module
 107 but not in other database modules.  The \var{dict} object passed to
 108 the constructor must support those methods.  This is generally
 109 accomplished by calling one of \function{bsddb.hashopen},
 110 \function{bsddb.btopen} or \function{bsddb.rnopen}.  The optional
 111 \var{protocol} and \var{writeback} parameters have the
 112 same interpretation as for the \class{Shelf} class.
 113
 114 \end{classdesc}
 115
 116 \begin{classdesc}{DbfilenameShelf}{filename\optional{, flag='c'\optional{, protocol=None\optional{, writeback=False}}}}
 117
 118 A subclass of \class{Shelf} which accepts a \var{filename} instead of
 119 a dict-like object.  The underlying file will be opened using
 120 {}\function{anydbm.open}.  By default, the file will be created and
 121 opened for both read and write.  The optional \var{flag} parameter has
 122 the same interpretation as for the \function{open} function.  The
 123 optional \var{protocol} and \var{writeback} parameters
 124 have the same interpretation as for the \class{Shelf} class.
 125
 126 \end{classdesc}
 127
 128 \subsection{Example}
 129
 130 To summarize the interface (\code{key} is a string, \code{data} is an
 131 arbitrary object):
 132
 133 \begin{verbatim}
 134 import shelve
 135
 136 d = shelve.open(filename) # open -- file may get suffix added by low-level
 137                           # library
 138
 139 d[key] = data   # store data at key (overwrites old data if
 140                 # using an existing key)
 141 data = d[key]   # retrieve a COPY of data at key (raise KeyError if no
 142                 # such key)
 143 del d[key]      # delete data stored at key (raises KeyError
 144                 # if no such key)
 145 flag = d.has_key(key)   # true if the key exists
 146 klist = d.keys() # a list of all existing keys (slow!)
 147
 148 # as d was opened WITHOUT writeback=True, beware:
 149 d['xx'] = range(4)  # this works as expected, but...
 150 d['xx'].append(5)   # *this doesn't!* -- d['xx'] is STILL range(4)!!!
 151
 152 # having opened d without writeback=True, you need to code carefully:
 153 temp = d['xx']      # extracts the copy
 154 temp.append(5)      # mutates the copy
 155 d['xx'] = temp      # stores the copy right back, to persist it
 156
 157 # or, d=shelve.open(filename,writeback=True) would let you just code
 158 # d['xx'].append(5) and have it work as expected, BUT it would also
 159 # consume more memory and make the d.close() operation slower.
 160
 161 d.close()       # close it
 162 \end{verbatim}
 163
 164 \begin{seealso}
 165   \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
 166   \seemodule{bsddb}{BSD \code{db} database interface.}
 167   \seemodule{dbhash}{Thin layer around the \module{bsddb} which provides an
 168   \function{open} function like the other database modules.}
 169   \seemodule{dbm}{Standard \UNIX{} database interface.}
 170   \seemodule{dumbdbm}{Portable implementation of the \code{dbm} interface.}
 171   \seemodule{gdbm}{GNU database interface, based on the \code{dbm} interface.}
 172   \seemodule{pickle}{Object serialization used by \module{shelve}.}
 173   \seemodule{cPickle}{High-performance version of \refmodule{pickle}.}
 174 \end{seealso}