shelve --- Python object persistence¶
原始碼：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.
- shelve.open(filename,flag='c',protocol=None,writeback=False)¶
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 of
dbm.open().By default, pickles created with
pickle.DEFAULT_PROTOCOLare usedto serialize values. The version of the pickle protocol can be specifiedwith 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 (see範例). If theoptionalwriteback parameter is set to
True, 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).在 3.10 版的變更:
pickle.DEFAULT_PROTOCOLis now used as the default pickleprotocol.在 3.11 版的變更:Acceptspath-like object for filename.
備註
Do not rely on the shelf being closed automatically; always call
close()explicitly when you don't need it any more, oruseshelve.open()as a context manager:withshelve.open('spam')asdb:db['eggs']='eggs'
警告
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 most of methods and operations supported by dictionaries(except copying, constructors and operators| and|=). This eases thetransition from dictionary based scripts to those requiring persistent storage.
Two additional methods are supported:
- Shelf.sync()¶
Write back all entries in the cache if the shelf was opened withwritebackset to
True. Also empty the cache and synchronize the persistentdictionary on disk, if feasible. This is called automatically when the shelfis closed withclose().
- Shelf.close()¶
Synchronize and close the persistentdict object. Operations on a closedshelf will fail with a
ValueError.
也參考
Persistent dictionary recipewith widely supported storage formats and having the speed of nativedictionaries.
Restrictions¶
The choice of which database package will be used (such as
dbm.ndbmordbm.gnu) depends on which interface is available. Therefore it is notsafe to open the database directly usingdbm. The database is also(unfortunately) subject to the limitations ofdbm, if it is used ---this means that (the pickled representation of) the objects stored in thedatabase should be fairly small, and in rare cases key collisions may causethe database to refuse updates.The
shelvemodule does not supportconcurrent read/write access toshelved objects. (Multiple simultaneous read accesses are safe.) When aprogram has a shelf open for writing, no other program should have it open forreading or writing. Unix file locking can be used to solve this, but thisdiffers across Unix versions and requires knowledge about the databaseimplementation used.On macOS
dbm.ndbmcan silently corrupt the database file on updates,which can cause hard crashes when trying to read from the database.
- classshelve.Shelf(dict,protocol=None,writeback=False,keyencoding='utf-8')¶
A subclass of
collections.abc.MutableMappingwhich stores pickledvalues in thedict object.By default, pickles created with
pickle.DEFAULT_PROTOCOLare usedto serialize values. The version of the pickle protocol can be specifiedwith theprotocol parameter. See thepickledocumentation for adiscussion of the pickle protocols.If thewriteback parameter is
True, 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.
A
Shelfobject can also be used as a context manager, in whichcase it will be automatically closed when thewithblock ends.在 3.2 版的變更:Added thekeyencoding parameter; previously, keys were always encoded inUTF-8.
在 3.4 版的變更:新增情境管理器的支援。
在 3.10 版的變更:
pickle.DEFAULT_PROTOCOLis now used as the default pickleprotocol.
- classshelve.BsdDbShelf(dict,protocol=None,writeback=False,keyencoding='utf-8')¶
A subclass of
Shelfwhich exposesfirst(),next(),previous(),last()andset_location()methods.These are availablein the third-partybsddbmodule 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 theShelfclass.
- classshelve.DbfilenameShelf(filename,flag='c',protocol=None,writeback=False)¶
A subclass of
Shelfwhich 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 theShelfclass.
範例¶
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