源代碼:?Lib/shelve.py

---

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

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

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

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

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

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

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

備注

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

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

警告

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

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

額外支持的兩個(gè)方法：

Shelf.sync()

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

Shelf.close()

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

參見

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

限制

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

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

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

collections.abc.MutableMapping?的一個(gè)子類，它會(huì)將封存的值保存在?dict?對(duì)象中。

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

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

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

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

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

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

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

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

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

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

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

示例

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

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ù)庫(kù)的泛型接口。

模塊?pickle

shelve?所使用的對(duì)象序列化。