Doc/library/shelve.rst

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