diff options
Diffstat (limited to 'Doc/library/shelve.rst')
| -rw-r--r-- | Doc/library/shelve.rst | 185 |
1 files changed, 185 insertions, 0 deletions
diff --git a/Doc/library/shelve.rst b/Doc/library/shelve.rst new file mode 100644 index 0000000..1776b7d --- /dev/null +++ b/Doc/library/shelve.rst @@ -0,0 +1,185 @@ + +:mod:`shelve` --- Python object persistence +=========================================== + +.. module:: shelve + :synopsis: Python object persistence. + + +.. index:: module: pickle + +A "shelf" is a persistent, dictionary-like object. The difference with "dbm" +databases is that the values (not the keys!) in a shelf can be essentially +arbitrary Python objects --- anything that the :mod:`pickle` module can handle. +This includes most class instances, recursive data types, and objects containing +lots of shared sub-objects. The keys are ordinary strings. + + +.. function:: open(filename[, flag='c'[, protocol=None[, writeback=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 the + filename and more than one file may be created. By default, the underlying + database file is opened for reading and writing. The optional *flag* parameter + has the same interpretation as the *flag* parameter of :func:`anydbm.open`. + + By default, version 0 pickles are used to serialize values. The version of the + pickle protocol can be specified with the *protocol* parameter. + + .. versionchanged:: 2.3 + The *protocol* parameter was added. + + By default, mutations to persistent-dictionary mutable entries are not + automatically written back. If the optional *writeback* parameter is set to + *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). + +Shelve objects support all methods supported by dictionaries. This eases the +transition from dictionary based scripts to those requiring persistent storage. + +One additional method is supported: + + +.. method:: Shelf.sync() + + Write back all entries in the cache if the shelf was opened with *writeback* set + to *True*. Also empty the cache and synchronize the persistent dictionary on + disk, if feasible. This is called automatically when the shelf is closed with + :meth:`close`. + + +Restrictions +------------ + + .. index:: + module: dbm + module: gdbm + module: bsddb + +* The choice of which database package will be used (such as :mod:`dbm`, + :mod:`gdbm` or :mod:`bsddb`) depends on which interface is available. Therefore + it is not safe to open the database directly using :mod:`dbm`. The database is + also (unfortunately) subject to the limitations of :mod:`dbm`, if it is used --- + this means that (the pickled representation of) the objects stored in the + database should be fairly small, and in rare cases key collisions may cause the + database to refuse updates. + +* Depending on the implementation, closing a persistent dictionary may or may + not be necessary to flush changes to disk. The :meth:`__del__` method of the + :class:`Shelf` class calls the :meth:`close` method, so the programmer generally + need not do this explicitly. + +* The :mod:`shelve` module does not support *concurrent* read/write access to + shelved objects. (Multiple simultaneous read accesses are safe.) When a + program has a shelf open for writing, no other program should have it open for + reading or writing. Unix file locking can be used to solve this, but this + differs across Unix versions and requires knowledge about the database + implementation used. + + +.. class:: Shelf(dict[, protocol=None[, writeback=False]]) + + A subclass of :class:`UserDict.DictMixin` which stores pickled values in the + *dict* object. + + By default, version 0 pickles are used to serialize values. The version of the + pickle protocol can be specified with the *protocol* parameter. See the + :mod:`pickle` documentation for a discussion of the pickle protocols. + + .. versionchanged:: 2.3 + The *protocol* parameter was added. + + If the *writeback* parameter is ``True``, the object will hold a cache of all + entries accessed and write them back to the *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. + + +.. class:: BsdDbShelf(dict[, protocol=None[, writeback=False]]) + + A subclass of :class:`Shelf` which exposes :meth:`first`, :meth:`next`, + :meth:`previous`, :meth:`last` and :meth:`set_location` which are available in + the :mod:`bsddb` module but not in other database modules. The *dict* object + passed to the constructor must support those methods. This is generally + accomplished by calling one of :func:`bsddb.hashopen`, :func:`bsddb.btopen` or + :func:`bsddb.rnopen`. The optional *protocol* and *writeback* parameters have + the same interpretation as for the :class:`Shelf` class. + + +.. class:: DbfilenameShelf(filename[, flag='c'[, protocol=None[, writeback=False]]]) + + A subclass of :class:`Shelf` which accepts a *filename* instead of a dict-like + object. The underlying file will be opened using :func:`anydbm.open`. By + default, the file will be created and opened for both read and write. The + optional *flag* parameter has the same interpretation as for the :func:`open` + function. The optional *protocol* and *writeback* parameters have the same + interpretation as for the :class:`Shelf` class. + + +Example +------- + +To summarize the interface (``key`` is a string, ``data`` is an arbitrary +object):: + + import shelve + + d = shelve.open(filename) # open -- file may get suffix added by low-level + # library + + 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 + # if no such key) + flag = d.has_key(key) # true if the key exists + klist = 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 + + +.. seealso:: + + Module :mod:`anydbm` + Generic interface to ``dbm``\ -style databases. + + Module :mod:`bsddb` + BSD ``db`` database interface. + + Module :mod:`dbhash` + Thin layer around the :mod:`bsddb` which provides an :func:`open` function like + the other database modules. + + Module :mod:`dbm` + Standard Unix database interface. + + Module :mod:`dumbdbm` + Portable implementation of the ``dbm`` interface. + + Module :mod:`gdbm` + GNU database interface, based on the ``dbm`` interface. + + Module :mod:`pickle` + Object serialization used by :mod:`shelve`. + + Module :mod:`cPickle` + High-performance version of :mod:`pickle`. + |