Source code: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 essentiallyarbitrary Python objects — anything that thepickle module can handle.This includes most class instances, recursive data types, and objects containinglots of shared sub-objects. The keys are ordinary strings.
Open a persistent dictionary. The filename specified is the base filename forthe underlying database. As a side-effect, an extension may be added to thefilename and more than one file may be created. By default, the underlyingdatabase file is opened for reading and writing. The optionalflag parameterhas the same interpretation as theflag parameter ofdbm.open().
By default, version 3 pickles are used to serialize values. The version of thepickle protocol can be specified with theprotocol parameter.
Because of Python semantics, a shelf cannot know when a mutablepersistent-dictionary entry is modified. By default modified objects arewrittenonly when assigned to the shelf (seeExample). If theoptionalwriteback parameter is set toTrue, all entries accessed are alsocached in memory, and written back onsync() andclose(); this can make it handier to mutate mutable entries inthe persistent dictionary, but, if many entries are accessed, it can consumevast amounts of memory for the cache, and it can make the close operationvery slow since all accessed entries are written back (there is no way todetermine which accessed entries are mutable, nor which ones were actuallymutated).
Note
Do not rely on the shelf being closed automatically; always callclose() explicitly when you don’t need it any more, or use awith statement withcontextlib.closing().
Warning
Because theshelve module is backed bypickle, it is insecureto load a shelf from an untrusted source. Like with pickle, loading a shelfcan execute arbitrary code.
Shelf objects support all methods supported by dictionaries. This eases thetransition from dictionary based scripts to those requiring persistent storage.
Two additional methods are supported:
Write back all entries in the cache if the shelf was opened withwritebackset toTrue. Also empty the cache and synchronize the persistentdictionary on disk, if feasible. This is called automatically when the shelfis closed withclose().
Synchronize and close the persistentdict object. Operations on a closedshelf will fail with aValueError.
See also
Persistent dictionary recipewith widely supported storage formats and having the speed of nativedictionaries.
A subclass ofcollections.abc.MutableMapping which stores pickledvalues in thedict object.
By default, version 0 pickles are used to serialize values. The version of thepickle protocol can be specified with theprotocol parameter. See thepickle documentation for a discussion of the pickle protocols.
If thewriteback parameter isTrue, the object will hold a cache of allentries accessed and write them back to thedict at sync and close times.This allows natural operations on mutable entries, but can consume much morememory and make sync and close take a long time.
Thekeyencoding parameter is the encoding used to encode keys before theyare used with the underlying dict.
New in version 3.2:Thekeyencoding parameter; previously, keys were always encoded inUTF-8.
A subclass ofShelf which exposesfirst(),next(),previous(),last() andset_location() which are availablein the third-partybsddb module frompybsddb but not in other databasemodules. Thedict object passed to the constructor must support thosemethods. This is generally accomplished by calling one ofbsddb.hashopen(),bsddb.btopen() orbsddb.rnopen(). Theoptionalprotocol,writeback, andkeyencoding parameters have the sameinterpretation as for theShelf class.
A subclass ofShelf which accepts afilename instead of a dict-likeobject. The underlying file will be opened usingdbm.open(). Bydefault, the file will be created and opened for both read and write. Theoptionalflag parameter has the same interpretation as for theopen()function. The optionalprotocol andwriteback parameters have the sameinterpretation as for theShelf class.
To summarize the interface (key is a string,data is an arbitraryobject):
importshelved=shelve.open(filename)# open -- file may get suffix added by low-level# libraryd[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)deld[key]# delete data stored at key (raises KeyError# if no such key)flag=keyind# true if the key existsklist=list(d.keys())# a list of all existing keys (slow!)# as d was opened WITHOUT writeback=True, beware:d['xx']=[0,1,2]# this works as expected, but...d['xx'].append(3)# *this doesn't!* -- d['xx'] is STILL [0, 1, 2]!# having opened d without writeback=True, you need to code carefully:temp=d['xx']# extracts the copytemp.append(5)# mutates the copyd['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
12.2.copyreg — Registerpickle support functions
12.4.marshal — Internal Python object serialization
Enter search terms or a module, class or function name.
