dbm — Unix“資料庫”介面

原始碼： Lib/dbm/__init__.py

dbm 是 DBM 資料庫變種的通用介面。

如果這些模組都沒有安裝，將會使用模組 dbm.dumb 中緩慢但簡單的實現。還有一個第三方介面可用於 Oracle Berkeley DB。

exception dbm.error

一個元組，包含了每個受支援模組可能引發的異常，其中第一個條目是一個同樣名為 dbm.error 的唯一異常 —— 當 dbm.error 被引發時會使用後者。

dbm.whichdb(filename)

該函式會嘗試猜測應該使用哪一個可用的簡單資料庫模組（dbm.sqlite3、dbm.gnu、dbm.ndbm 或 dbm.dumb）來開啟給定的檔案。

返回以下值之一

  • 如果檔案因不可讀或不存在而無法開啟，則返回 None。

  • 如果無法猜測檔案格式，則返回空字串（''）。

  • 包含所需模組名稱的字串，例如 'dbm.ndbm' 或 'dbm.gnu'。

在 3.11 版本發生變更: filename 接受一個類路徑物件。

dbm.open(file, flag='r', mode=0o666)

開啟一個數據庫並返回相應的資料庫物件。

引數:

  • file (類路徑物件) –

    要開啟的資料庫檔案。

    如果資料庫檔案已經存在，則使用 whichdb() 函式來確定其型別，並使用相應的模組；如果不存在，則使用上面列出的第一個可以匯入的子模組。

  • flag (str) –

    • 'r' (預設): 開啟現有資料庫用於只讀。

    • 'w': 開啟現有資料庫用於讀寫。

    • 'c': 開啟資料庫用於讀寫，如果不存在則建立它。

    • 'n': 總是建立一個新的空資料庫，用於讀寫。

  • mode (int) – 檔案的 Unix 檔案訪問模式（預設為八進位制 0o666），僅在需要建立資料庫時使用。

在 3.11 版本發生變更: file 接受一個類路徑物件。

open() 返回的物件支援可變對映的基本功能；鍵及其對應的值可以被儲存、檢索和刪除，並且支援迭代、in 運算子以及 keys(), get(), setdefault() 和 clear() 方法。 keys() 方法返回一個列表而不是檢視物件。 setdefault() 方法需要兩個引數。

鍵和值總是以 bytes 的形式儲存。這意味著當使用字串時，它們會在儲存前被隱式地轉換為預設編碼。

這些物件還支援在 with 語句中使用，這將在完成後自動關閉它們。

在 3.2 版本發生變更: get() 和 setdefault() 方法現在對所有 dbm 後端都可用。

在 3.4 版本發生變更: 為 open() 返回的物件增加了對上下文管理協議的原生支援。

在 3.8 版本發生變更: 從只讀資料庫中刪除一個鍵會引發一個特定於資料庫模組的異常，而不是 KeyError。

在 3.13 版本發生變更: clear() 方法現在對所有 dbm 後端都可用。

以下示例記錄了一些主機名和對應的標題，然後打印出資料庫的內容。

import dbm

# Open database, creating it if necessary.
with dbm.open('cache', 'c') as db:

    # Record some values
    db[b'hello'] = b'there'
    db['www.python.org'] = 'Python Website'
    db['www.cnn.com'] = 'Cable News Network'

    # Note that the keys are considered bytes now.
    assert db[b'www.python.org'] == b'Python Website'
    # Notice how the value is now in bytes.
    assert db['www.cnn.com'] == b'Cable News Network'

    # Often-used methods of the dict interface work too.
    print(db.get('python.org', b'not present'))

    # Storing a non-string key or value will raise an exception (most
    # likely a TypeError).
    db['www.yahoo.com'] = 4

# db is automatically closed when leaving the with statement.

參見

模組 shelve

儲存非字串資料的持久化模組。

各個子模組在以下章節中描述。

dbm.sqlite3 — dbm 的 SQLite 後端

在 3.13 版本加入。

原始碼： Lib/dbm/sqlite3.py

此模組使用標準庫 sqlite3 模組為 dbm 模組提供 SQLite 後端。因此，由 dbm.sqlite3 建立的檔案可以被 sqlite3 或任何其他 SQLite 瀏覽器（包括 SQLite CLI）開啟。

可用性：非 WASI。

此模組在 WebAssembly 上不起作用或不可用。有關更多資訊，請參閱 WebAssembly 平臺。

dbm.sqlite3.open(filename, /, flag='r', mode=0o666)

開啟一個 SQLite 資料庫。

引數:

  • filename (類路徑物件) – 要開啟的資料庫的路徑。

  • flag (str) –

    • 'r' (預設): 開啟現有資料庫用於只讀。

    • 'w': 開啟現有資料庫用於讀寫。

    • 'c': 開啟資料庫用於讀寫，如果不存在則建立它。

    • 'n': 總是建立一個新的空資料庫，用於讀寫。

  • mode – 檔案的 Unix 檔案訪問模式（預設為八進位制 0o666），僅在需要建立資料庫時使用。

返回的資料庫物件行為類似於一個可變對映，但 keys() 方法返回一個列表，並且 setdefault() 方法需要兩個引數。它還透過 with 關鍵字支援“關閉”上下文管理器。

還提供以下方法

sqlite3.close()

關閉 SQLite 資料庫。

dbm.gnu — GNU 資料庫管理器

原始碼： Lib/dbm/gnu.py

dbm.gnu 模組提供了對 GDBM 庫的介面，類似於 dbm.ndbm 模組，但具有額外的功能，如崩潰容錯。

備註

dbm.gnu 和 dbm.ndbm 建立的檔案格式不相容，不能互換使用。

可用性: 非 Android、非 iOS、非 WASI。

該模組在移動平臺或WebAssembly 平臺上不受支援。

exception dbm.gnu.error

在 dbm.gnu 特定錯誤（例如I/O錯誤）時引發。對於一般的對映錯誤，例如指定了不正確的鍵，會引發 KeyError。

dbm.gnu.open_flags

一個字串，包含 open() 的 flag 引數所支援的字元。

dbm.gnu.open(filename, flag='r', mode=0o666, /)

開啟一個 GDBM 資料庫並返回一個 gdbm 物件。

引數:

  • filename (類路徑物件) – 要開啟的資料庫檔案。

  • flag (str) –

    • 'r' (預設): 開啟現有資料庫用於只讀。

    • 'w': 開啟現有資料庫用於讀寫。

    • 'c': 開啟資料庫用於讀寫，如果不存在則建立它。

    • 'n': 總是建立一個新的空資料庫，用於讀寫。

    可以附加以下額外字元來控制資料庫的開啟方式：

    • 'f': 以快速模式開啟資料庫。對資料庫的寫入將不會被同步。

    • 's': 同步模式。對資料庫的更改將立即寫入檔案。

    • 'u': 不鎖定資料庫。

    並非所有標誌對所有版本的 GDBM 都有效。請參閱 open_flags 成員獲取支援的標誌字元列表。

  • mode (int) – 檔案的 Unix 檔案訪問模式（預設為八進位制 0o666），僅在需要建立資料庫時使用。

引發:

error – 如果傳遞了無效的 flag 引數。

在 3.11 版本發生變更: filename 接受一個類路徑物件。

gdbm 物件的行為類似於可變對映，但不支援 items(), values(), pop(), popitem() 和 update() 方法，keys() 方法返回一個列表，並且 setdefault() 方法需要兩個引數。它還透過 with 關鍵字支援“關閉”上下文管理器。

在 3.2 版本發生變更: 添加了 get() 和 setdefault() 方法。

在 3.13 版本發生變更: 添加了 clear() 方法。

還提供以下方法

gdbm.close()

關閉 GDBM 資料庫。

gdbm.firstkey()

使用此方法和 nextkey() 方法可以遍歷資料庫中的每個鍵。遍歷是按 GDBM 的內部雜湊值排序的，不會按鍵值排序。此方法返回起始鍵。

gdbm.nextkey(key)

返回遍歷中跟隨 key 的鍵。以下程式碼列印資料庫 db 中的每個鍵，而無需在記憶體中建立包含所有鍵的列表。

k = db.firstkey()
while k is not None:
    print(k)
    k = db.nextkey(k)
gdbm.reorganize()

如果您進行了大量刪除操作並希望縮小 GDBM 檔案使用的空間，此例程將重組資料庫。gdbm 物件不會縮短資料庫檔案的長度，除非使用此重組操作；否則，已刪除的檔案空間將被保留，並在新增新的（鍵，值）對時重用。

gdbm.sync()

當資料庫以快速模式開啟時，此方法會強制將任何未寫入的資料寫入磁碟。

dbm.ndbm — 新資料庫管理器

原始碼： Lib/dbm/ndbm.py

dbm.ndbm 模組提供了對 NDBM 庫的介面。此模組可與“經典” NDBM 介面或 GDBM 相容性介面一起使用。

備註

dbm.gnu 和 dbm.ndbm 建立的檔案格式不相容，不能互換使用。

警告

作為 macOS 一部分的 NDBM 庫對值的大小有一個未記錄的限制，當儲存大於此限制的值時，可能導致資料庫檔案損壞。讀取此類損壞的檔案可能會導致硬崩潰（段錯誤）。

可用性: 非 Android、非 iOS、非 WASI。

該模組在移動平臺或WebAssembly 平臺上不受支援。

exception dbm.ndbm.error

在 dbm.ndbm 特定錯誤（例如I/O錯誤）時引發。對於一般的對映錯誤，例如指定了不正確的鍵，會引發 KeyError。

dbm.ndbm.library

所使用的 NDBM 實現庫的名稱。

dbm.ndbm.open(filename, flag='r', mode=0o666, /)

開啟一個 NDBM 資料庫並返回一個 ndbm 物件。

引數:

  • filename (類路徑物件) – 資料庫檔案的基本名稱（不帶 .dir 或 .pag 副檔名）。

  • flag (str) –

    • 'r' (預設): 開啟現有資料庫用於只讀。

    • 'w': 開啟現有資料庫用於讀寫。

    • 'c': 開啟資料庫用於讀寫，如果不存在則建立它。

    • 'n': 總是建立一個新的空資料庫，用於讀寫。

  • mode (int) – 檔案的 Unix 檔案訪問模式（預設為八進位制 0o666），僅在需要建立資料庫時使用。

在 3.11 版本發生變更: filename 接受類路徑物件。

ndbm 物件的行為類似於可變對映，但不支援 items(), values(), pop(), popitem() 和 update() 方法，keys() 方法返回一個列表，並且 setdefault() 方法需要兩個引數。它還透過 with 關鍵字支援“關閉”上下文管理器。

在 3.2 版本發生變更: 添加了 get() 和 setdefault() 方法。

在 3.13 版本發生變更: 添加了 clear() 方法。

還提供以下方法

ndbm.close()

關閉 NDBM 資料庫。

dbm.dumb — 可移植的 DBM 實現

原始碼： Lib/dbm/dumb.py

備註

當沒有更強大的模組可用時，dbm.dumb 模組旨在作為 dbm 模組的最後備選方案。dbm.dumb 模組並非為速度而編寫，其使用頻率遠不及其他資料庫模組。

dbm.dumb 模組提供了一個完全用 Python 編寫的持久化dict類介面。與 dbm.gnu 等其他 dbm 後端不同，它不需要外部庫。

dbm.dumb 模組定義了以下內容

exception dbm.dumb.error

在 dbm.dumb 特定錯誤（例如I/O錯誤）時引發。對於一般的對映錯誤，例如指定了不正確的鍵，會引發 KeyError。

dbm.dumb.open(filename, flag='c', mode=0o666)

開啟一個 dbm.dumb 資料庫。

引數:

  • filename –

    資料庫檔案的基本名稱（不帶副檔名）。一個新的資料庫會建立以下檔案

    • filename.dat

    • filename.dir

  • flag (str) –

    • 'r': 開啟現有資料庫用於只讀。

    • 'w': 開啟現有資料庫用於讀寫。

    • 'c' (預設): 開啟資料庫用於讀寫，如果不存在則建立它。

    • 'n': 總是建立一個新的空資料庫，用於讀寫。

  • mode (int) – 檔案的 Unix 檔案訪問模式（預設為八進位制 0o666），僅在需要建立資料庫時使用。

警告

由於 Python AST 編譯器的堆疊深度限制，載入具有足夠大/複雜條目的資料庫時，可能會導致 Python 直譯器崩潰。

在 3.5 版本發生變更: 當 flag 為 'n' 時，open() 總是會建立一個新的資料庫。

在 3.8 版本發生變更: 如果 flag 為 'r'，則以只讀方式開啟資料庫。如果 flag 為 'r' 或 'w'，且資料庫不存在，則不會建立資料庫。

在 3.11 版本發生變更: filename 接受一個類路徑物件。

返回的資料庫物件行為類似於一個可變對映，但 keys() 和 items() 方法返回列表，並且 setdefault() 方法需要兩個引數。它還透過 with 關鍵字支援“關閉”上下文管理器。

還提供以下方法

dumbdbm.close()

關閉資料庫。

dumbdbm.sync()

同步磁碟上的目錄和資料檔案。此方法由 shelve.Shelf.sync() 方法呼叫。