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() 方法调用。