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() 返回的物件支援與 dict 相同的功能；可以儲存、檢索和刪除鍵及其對應的值，並且可以使用 in 運算子和 keys() 方法，以及 get() 和 setdefault() 方法。

鍵和值始終儲存為 bytes。這意味著當使用字串時，它們在儲存之前會隱式轉換為預設編碼。

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

在 3.2 版本中更改: get() 和 setdefault() 方法現在可用於所有 dbm 後端。

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

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

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

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 資料庫。返回的物件行為類似於 對映，實現了一個 close() 方法，並透過 with 關鍵字支援“關閉”上下文管理器。

引數：

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

  • flag (str) –

    • 'r'（預設）：開啟現有資料庫進行只讀。

    • 'w'：開啟現有資料庫進行讀寫。

    • 'c'：開啟資料庫進行讀寫，如果不存在則建立它。

    • 'n'：始終建立一個新的空資料庫，開啟進行讀寫。

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

dbm.gnu — GNU 資料庫管理器

原始碼： Lib/dbm/gnu.py

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

注意

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

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

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

異常 dbm.gnu.error

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

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 接受 路徑類物件。

dbm.gnu.open_flags

open() 的 flag 引數支援的字元字串。

gdbm 物件的行為類似於 對映，但不支援 items() 和 values() 方法。還提供了以下方法

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()

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

gdbm.close()

關閉 GDBM 資料庫。

gdbm.clear()

從 GDBM 資料庫中刪除所有項。

在 3.13 版本中新增。

dbm.ndbm — 新資料庫管理器

原始碼： Lib/dbm/ndbm.py

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

注意

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

警告

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

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

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

異常 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），僅在必須建立資料庫時使用。

ndbm 物件的行為類似於 對映，但不支援 items() 和 values() 方法。還提供了以下方法

3.11 版本更改: 接受檔名使用路徑類物件。

ndbm.close()

關閉 NDBM 資料庫。

ndbm.clear()

刪除 NDBM 資料庫中的所有項。

在 3.13 版本中新增。

dbm.dumb — 可移植的 DBM 實現

原始碼: Lib/dbm/dumb.py

注意

當沒有更強大的模組可用時，dbm.dumb 模組旨在作為 dbm 模組的最後手段。 dbm.dumb 模組不是為了速度而編寫的，使用頻率遠不如其他資料庫模組。

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

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

exception dbm.dumb.error

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

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

開啟一個 dbm.dumb 資料庫。 返回的資料庫物件的行為類似於 對映，此外還提供 sync() 和 close() 方法。

引數：

  • 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 接受 路徑類物件。

除了 collections.abc.MutableMapping 類提供的方法之外，還提供了以下方法

dumbdbm.sync()

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

dumbdbm.close()

關閉資料庫。