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

关闭数据库。