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