rest25/library/shelve.rst => rest262/library/shelve.rst
10
11A "shelf" is a persistent, dictionary-like object.  The difference with "dbm"
12databases is that the values (not the keys!) in a shelf can be essentially
13arbitrary Python objects --- anything that the :mod:`pickle` module can handle.
14This includes most class instances, recursive data types, and objects containing
15lots of shared  sub-objects.  The keys are ordinary strings.
16
17
n18-.. function:: open(filename[,flag='c'[,protocol=``None``[,writeback=``False``]]])
n18+.. function:: open(filename[, flag='c'[, protocol=None[, writeback=False]]])
19
20   Open a persistent dictionary.  The filename specified is the base filename for
21   the underlying database.  As a side-effect, an extension may be added to the
22   filename and more than one file may be created.  By default, the underlying
23   database file is opened for reading and writing.  The optional *flag* parameter
24   has the same interpretation as the *flag* parameter of :func:`anydbm.open`.
25
26   By default, version 0 pickles are used to serialize values.  The version of the
45
46
47.. method:: Shelf.sync()
48
49   Write back all entries in the cache if the shelf was opened with *writeback* set
50   to *True*. Also empty the cache and synchronize the persistent dictionary on
51   disk, if feasible.  This is called automatically when the shelf is closed with
52   :meth:`close`.
n53+ 
54+.. seealso::
55+ 
56+   `Persistent dictionary recipe <http://code.activestate.com/recipes/576642/>`_
57+   with widely supported storage formats and having the speed of native
58+   dictionaries.
53
54
55Restrictions
56------------
57
58  .. index::
59     module: dbm
60     module: gdbm
137                   # such key)
138   del d[key]      # delete data stored at key (raises KeyError
139                   # if no such key)
140   flag = d.has_key(key)   # true if the key exists
141   klist = d.keys() # a list of all existing keys (slow!)
142
143   # as d was opened WITHOUT writeback=True, beware:
144   d['xx'] = range(4)  # this works as expected, but...
t145-   d['xx'].append(5)   # *this doesn't!* -- d['xx'] is STILL range(4)!!!
t151+   d['xx'].append(5)   # *this doesn't!* -- d['xx'] is STILL range(4)!
146
147   # having opened d without writeback=True, you need to code carefully:
148   temp = d['xx']      # extracts the copy
149   temp.append(5)      # mutates the copy
150   d['xx'] = temp      # stores the copy right back, to persist it
151
152   # or, d=shelve.open(filename,writeback=True) would let you just code
153   # d['xx'].append(5) and have it work as expected, BUT it would also
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op