[Python Std Library] Data Persistence : shelve — Python object persistence

來源自 這裡
Preface :
A "shelve" is a persistent, dictionary-like object. The difference with "dbm" databases is that the values (not the keys!) in a shelve can be essentially arbitrary Python objects — anything that the 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.

Supported APIs :
Shelve objects support all methods supported by dictionaries. This eases the transition from dictionary based scripts to those requiring persistent storage. Besides, this module support below APIs :
- shelve.open(filename, flag='c', protocol=None, writeback=False)

Changed in version 2.3: The protocol parameter was added.
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 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.

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 Example). If the optional writeback parameter is set to True, all entries accessed are also cached in memory, and written back on sync()and 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.

- Shelve.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 close().

- Shelve.close()

Synchronize and close the persistent dict object. Operations on a closed shelf will fail with a ValueError.

Restrictions :
The 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.

Example :
To summarize the interface :

>>> import shelve
>>> pdict = shelve.open('persistDict') # open -- file may get suffix added by low-level
>>> list = ['john', 'ken']
>>> pdict['name'] = list # store data 'list' at key 'name' (overwrites old data if using an existing key)
>>> pdict['name']
['john', 'ken']
>>> map = {'name':'john', 'age':31}
>>> pdict['map'] = map
>>> del pdict['name'] # delete data stored at key 'name' (raises KeyError if no such key)
>>> 'name' in pdict # false if the key not exists
False
>>> 'map' in pdict # true if the key exists
True
>>> tmpList = [1]
>>> pdict['tmp'] = tmpList
>>> tmpList.append(2) # mutates the copy
>>> pdict['tmp'] # extracts the copy
[1] # Modify 'tmpList' doesn't affect pdict['tmp'] !
>>> tmpList
[1, 2]
>>> pdict['tmp'] = tmpList # stores the copy right back, to persist it
>>> pdict.close() # close it
>>> pdict = shelve.open('persistDict')
>>> pdict['tmp'] # The dictionary data successfully being restored!
[1, 2]

Supplement :
* Persistent dictionary recipe

Persistent dictionary recipe with widely supported storage formats and having the speed of native dictionaries...