0-2 13:67 +ˆl–Ým_JJh¥² ¸È®41hß ƒx-‹_‡I|¥ŠèªÂÁØ:mod:`shelve` --- Python object persistence =========================================== .. module:: shelve :synopsis: Python object persistence. .. index:: module: pickle **Source code:** :source:`Lib/shelve.py` -------------- 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. Because of Python semantics, a shelf cannot know when a mutable persistent-dictionary entry is modified. By default modified objects are written *only* when assigned to the shelf (see :ref:`shelve-example`). If the optional *writeback* parameter is set to *True*, all entries accessed are also cached in memory, and written back on :meth:`~Shelf.sync` and :meth:`~Shelf.close`; 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). Like file objects, shelve objects should be closed explicitly to ensure that the persistent data is flushed to disk. Since the :mod:`shelve` module stores objects using :mod:`pickle`, the same security precautions apply. Accordingly, you should avoid loading a shelf from an untrusted source. Shelf objects support all methods supported by dictionaries. This eases the transition from dictionary based scripts to those requiring persistent storage. Two additional methods are supported: .. method:: Shelf.sync() Write back all entries in the cache if the shelf was opened with *writeback* set to :const:`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`. .. method:: Shelf.close() Synchronize and close the persistent *dict* object. Operations on a closed shelf will fail with a :exc:`ValueError`. .. seealso:: `Persistent dictionary recipe `_ with widely supported storage formats and having the speed of native dictionaries. 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. * 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 o