源代碼:?Lib/shelve.py

---

"Shelf" 是一種持久化的類似字典的對象。 與 "dbm" 數(shù)據(jù)庫的區(qū)別在于 Shelf 中的值（不是鍵！）實際上可以為任意 Python 對象 --- 即?pickle?模塊能夠處理的任何東西。 這包括大部分類實例、遞歸數(shù)據(jù)類型，以及包含大量共享子對象的對象。 鍵則為普通的字符串。

shelve.open(filename,?flag='c',?protocol=None,?writeback=False)

打開一個持久化字典。 filename 指定下層數(shù)據(jù)庫的基準(zhǔn)文件名。 作為附帶效果，會為 filename 添加一個擴(kuò)展名并且可能創(chuàng)建更多的文件。 默認(rèn)情況下，下層數(shù)據(jù)庫會以讀寫模式打開。 可選的?flag?形參具有與?dbm.open()?flag?形參相同的含義。

在默認(rèn)情況下，會使用以?pickle.DEFAULT_PROTOCOL?創(chuàng)建的 pickle 來序列化值。 pickle 協(xié)議的版本可通過?protocol?形參來指定。

由于 Python 語義的限制，Shelf 對象無法確定一個可變的持久化字典條目在何時被修改。 默認(rèn)情況下?只有?在被修改對象再賦值給 shelf 時才會寫入該對象 (參見?示例)。 如果可選的?writeback?形參設(shè)為?True，則所有被訪問的條目都將在內(nèi)存中被緩存，并會在?sync()?和?close()?時被寫入；這可以使得對持久化字典中可變條目的修改更方便，但是如果訪問的條目很多，這會消耗大量內(nèi)存作為緩存，并會使得關(guān)閉操作變得非常緩慢，因為所有被訪問的條目都需要寫回到字典（無法確定被訪問的條目中哪個是可變的，也無法確定哪個被實際修改了）。

在 3.10 版更改:?pickle.DEFAULT_PROTOCOL?現(xiàn)在會被用作默認(rèn)的 pickle 協(xié)議。

在 3.11 版更改:?接受?path-like object?作為文件名。

備注

請不要依賴于 Shelf 的自動關(guān)閉功能；當(dāng)你不再需要時應(yīng)當(dāng)總是顯式地調(diào)用?close()，或者使用?shelve.open()?作為上下文管理器:

with shelve.open('spam') as db:db['eggs'] = 'eggs'

警告

由于?shelve?模塊需要?pickle?的支持，因此從不可靠的來源載入 shelf 是不安全的。 與 pickle 一樣，載入 Shelf 時可以執(zhí)行任意代碼。

Shelf 對象支持字典所支持的大多數(shù)方法和運算（除了拷貝、構(gòu)造器以及?|?和?|=?運算符）。 這樣就能方便地將基于字典的腳本轉(zhuǎn)換為要求持久化存儲的腳本。

額外支持的兩個方法：

Shelf.sync()

如果 Shelf 打開時將?writeback?設(shè)為?True?則寫回緩存中的所有條目。 如果可行還會清空緩存并將持久化字典同步到磁盤。 此方法會在使用?close()?關(guān)閉 Shelf 時自動被調(diào)用。

Shelf.close()

同步并關(guān)閉持久化?dict?對象。 對已關(guān)閉 Shelf 的操作將失敗并引發(fā)?ValueError。

參見

持久化字典方案，使用了廣泛支持的存儲格式并具有原生字典的速度。

限制

• 可選擇使用哪種數(shù)據(jù)庫包 (例如?dbm.ndbm?或?dbm.gnu) 取決于支持哪種接口。 因此使用?dbm?直接打開數(shù)據(jù)庫是不安全的。 如果使用了?dbm，數(shù)據(jù)庫同樣會（不幸地）受限于它 --- 這意味著存儲在數(shù)據(jù)庫中的（封存形式的）對象尺寸應(yīng)當(dāng)較小，并且在少數(shù)情況下鍵沖突有可能導(dǎo)致數(shù)據(jù)庫拒絕更新。

• shelve?模塊不支持對 Shelf 對象的?并發(fā)?讀/寫訪問。 （多個同時讀取訪問則是安全的。） 當(dāng)一個程序打開一個 shelve 對象來寫入時，不應(yīng)再有其他程序同時打開它來讀取或?qū)懭搿?Unix 文件鎖定可被用來解決此問題，但這在不同 Unix 版本上會存在差異，并且需要有關(guān)所用數(shù)據(jù)庫實現(xiàn)的細(xì)節(jié)知識。

class?shelve.Shelf(dict,?protocol=None,?writeback=False,?keyencoding='utf-8')

collections.abc.MutableMapping?的一個子類，它會將封存的值保存在?dict?對象中。

在默認(rèn)情況下，會使用以?pickle.DEFAULT_PROTOCOL?創(chuàng)建的 pickle 來序列化值。 pickle 協(xié)議的版本可通過?protocol?形參來指定。 請參閱?pickle?文檔來查看 pickle 協(xié)議的相關(guān)討論。

如果?writeback?形參為?True，對象將為所有訪問過的條目保留緩存并在同步和關(guān)閉時將它們寫回到?dict。 這允許對可變的條目執(zhí)行自然操作，但是會消耗更多內(nèi)存并讓同步和關(guān)閉花費更長時間。

keyencoding?形參是在下層字典被使用之前用于編碼鍵的編碼格式。

Shelf?對象還可以被用作上下文管理器，在這種情況下它將在?with?語句塊結(jié)束時自動被關(guān)閉。

在 3.2 版更改:?添加了?keyencoding?形參；之前，鍵總是使用 UTF-8 編碼。

在 3.4 版更改:?添加了上下文管理器支持。

在 3.10 版更改:?pickle.DEFAULT_PROTOCOL?現(xiàn)在會被用作默認(rèn)的 pickle 協(xié)議。

class?shelve.BsdDbShelf(dict,?protocol=None,?writeback=False,?keyencoding='utf-8')

Shelf?的一個子類，它對外公開了?first(),?next(),?previous(),?last()?和?set_location()?方法。 這在來自?pybsddb?的第三方模塊?bsddb?中可用，但在其他數(shù)據(jù)庫模塊中不可用。 傳給構(gòu)造器的?dict?對象必須支持這些方法。 這一般是通過調(diào)用?bsddb.hashopen(),?bsddb.btopen()?或?bsddb.rnopen()?中的一個來完成的。 可選的?protocol,?writeback?和?keyencoding?形參具有與?Shelf?類的對應(yīng)形參相同的含義。

class?shelve.DbfilenameShelf(filename,?flag='c',?protocol=None,?writeback=False)

Shelf?的一個子類，它接受一個?filename?而非字典類對象。 下層文件將使用?dbm.open()?來打開。 默認(rèn)情況下，文件將以讀寫模式打開。 可選的?flag?形參具有與?open()?函數(shù)相同的含義。 可選的?protocol?和?writeback?形參具有與?Shelf?類相同的含義。

示例

對接口的總結(jié)如下 (key?為字符串，data?為任意對象):

import shelved = 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)
del d[key]                 # delete data stored at key (raises KeyError# if no such key)flag = key in d            # true if the key exists
klist = 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 copy
temp.append(5)             # mutates the copy
d['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

參見

模塊?dbm

dbm?風(fēng)格數(shù)據(jù)庫的泛型接口。

模塊?pickle

shelve?所使用的對象序列化。