`dbm` --- Unix "数据库" 接口¶

dbm is a generic interface to variants of the DBM database:

dbm.sqlite3
dbm.gnu
dbm.ndbm

If none of these modules are installed, the slow-but-simple implementation in module dbm.dumb will be used. There is a third party interface to the Oracle Berkeley DB.

Availability: not WASI, not iOS.

This module does not work or is not available on WebAssembly platforms, or on iOS. See WebAssembly 平台 for more information on WASM availability; see iOS for more information on iOS availability.

exception dbm.error¶: 一个元组，其中包含每个受支持的模块可引发的异常，另外还有一个名为 dbm.error 的特殊异常作为第一项 --- 后者最在引发 dbm.error 时被使用。

dbm.whichdb(filename)¶

This function attempts to guess which of the several simple database modules available --- dbm.sqlite3, dbm.gnu, dbm.ndbm, or dbm.dumb --- should be used to open a given file.

返回下列值中的一个：

如果文件因其不可读或不存在而无法打开则返回 None
如果文件格式无法猜测则返回空字符串 ('')
包含所需模块名称的字符串，如 'dbm.ndbm' 或 'dbm.gnu'

在 3.11 版本发生变更: filename 接受一个 path-like object。

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

打开一个数据库并返回相应的数据库对象。

参数:

file (path-like object) -- 要打开的数据库文件。如果数据库文件已存在，则使用 whichdb() 来确定其类型和要使用的适当模块；如果文件不存在，则会使用上述可导入子模块中的第一个。
flag (str) --
- 'r' (default): Open existing database for reading only.
- 'w': Open existing database for reading and writing.
- 'c': Open database for reading and writing, creating it if it doesn't exist.
- 'n': Always create a new, empty database, open for reading and writing.
mode (int) -- The Unix file access mode of the file (default: octal 0o666), used only when the database has to be created.

在 3.11 版本发生变更: file 接受一个 path-like object。

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` --- SQLite backend for dbm¶

Added in version 3.13.

Source code: Lib/dbm/sqlite3.py

This module uses the standard library sqlite3 module to provide an SQLite backend for the dbm module. The files created by dbm.sqlite3 can thus be opened by sqlite3, or any other SQLite browser, including the SQLite CLI.

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

Open an SQLite database. The returned object behaves like a mapping, implements a close() method, and supports a "closing" context manager via the with keyword.

参数:

filename (path-like object) -- The path to the database to be opened.
flag (str) --
- 'r' (default): Open existing database for reading only.
- 'w': Open existing database for reading and writing.
- 'c': Open database for reading and writing, creating it if it doesn't exist.
- 'n': Always create a new, empty database, open for reading and writing.
mode -- The Unix file access mode of the file (default: octal 0o666), used only when the database has to be created.

`dbm.gnu` --- GNU 数据库管理器¶

源代码: Lib/dbm/gnu.py

dbm.gnu 模块提供了针对 GDBM 库的接口，类似于 dbm.ndbm 模块，但带有额外的功能如对崩溃的容忍。

备注

由 dbm.gnu 和 dbm.ndbm 创建的文件格式是不兼容的因而无法互换使用。

exception dbm.gnu.error¶: 针对 dbm.gnu 专属错误例如 I/O 错误引发。 KeyError 的引发则针对一般映射错误例如指定了不正确的键。

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

打开 GDBM 数据库并返回一个 gdbm 对象。

参数:

filename (path-like object) -- 要打开的数据库文件。
flag (str) --
- 'r' (default): Open existing database for reading only.
- 'w': Open existing database for reading and writing.
- 'c': Open database for reading and writing, creating it if it doesn't exist.
- 'n': Always create a new, empty database, open for reading and writing.
可以添加下列额外字符来控制数据库的打开方式：
- 'f': 以快速模式打开数据库。对数据库的写入将不是同步的。
- 's': 同步模式。对数据库的修改将立即写入到文件。
- 'u': 不锁定数据库。
并非所有旗标都对所有 GDBM 版本可用。请参阅 open_flags 成员获取受支持旗标字符的列表。
mode (int) -- The Unix file access mode of the file (default: octal 0o666), used only when the database has to be created.

抛出:

error -- 如果传入了不可用的 flag 参数。

在 3.11 版本发生变更: filename 接受一个 path-like object。

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()¶: Remove all items from the GDBM database.

Added in version 3.13.

`dbm.ndbm` --- 新数据库管理器¶

源代码: Lib/dbm/ndbm.py

dbm.ndbm 模块提供了对 NDBM 库的接口。此模块可与 "经典" NDBM 接口或 GDBM 兼容接口配合使用。

备注

由 dbm.gnu 和 dbm.ndbm 创建的文件格式是不兼容的因而无法互换使用。

警告

作为 macOS 的组成部分提供的 NDBM 库对值的大小有一个未写入文档的限制，当存储的值大于此限制时可能会导致数据库文件损坏。读取这种已损坏的文件可能会导致硬崩溃（段错误）。

exception dbm.ndbm.error¶: 针对 dbm.ndbm 专属错误例如 I/O 错误引发。 KeyError 的引发则针对一般映射错误例如指定了不正确的键。

dbm.ndbm.library¶: 所使用的 NDBM 实现库的名称。

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

打开 NDBM 数据库并返回一个 ndbm 对象。

参数:

filename (path-like object) -- 数据库文件的基本名（不带 .dir 或 .pag 扩展名）。
flag (str) --
- 'r' (default): Open existing database for reading only.
- 'w': Open existing database for reading and writing.
- 'c': Open database for reading and writing, creating it if it doesn't exist.
- 'n': Always create a new, empty database, open for reading and writing.
mode (int) -- The Unix file access mode of the file (default: octal 0o666), used only when the database has to be created.

ndbm 对象的行为类似于映射，但不支持 items() 和 values() 方法。还提供了以下方法：

在 3.11 版本发生变更: 接受 path-like object 作为文件名。

ndbm.close()¶: 关闭 NDBM 数据库。

ndbm.clear()¶: Remove all items from the NDBM database.

Added in version 3.13.

`dbm.dumb` --- 便携式 DBM 实现¶

源代码: Lib/dbm/dumb.py

备注

dbm.dumb 模块的目的是在更健壮的模块不可用时作为 dbm 模块的最终回退项。 dbm.dumb 不是为高速运行而编写的，也不像其他数据库模块一样被经常使用。

dbm.dumb 模块提供了一个完全以 Python 编写的持久化 dict 型接口。不同于其他 dbm 后端，例如 dbm.gnu，它不需要外部库。

dbm.dumb 模块定义了以下对象：

exception dbm.dumb.error¶: 针对 dbm.dumb 专属错误例如 I/O 错误引发。 KeyError 的引发则针对一般映射例如指定了不正确的键。

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

打开一个 dbm.dumb 数据库。返回的数据库对象的行为类似于 mapping，并额外提供 sync() 和 close() 等方法。

参数:

filename -- 数据库文件的基本名（不带扩展名）。新数据库将会创建以下文件: - filename.dat - filename.dir
flag (str) --
- 'r': Open existing database for reading only.
- 'w': Open existing database for reading and writing.
- 'c' (default): Open database for reading and writing, creating it if it doesn't exist.
- 'n': Always create a new, empty database, open for reading and writing.
mode (int) -- The Unix file access mode of the file (default: octal 0o666), used only when the database has to be created.

警告

当载入包含足够巨大/复杂条目的数据库时有可能导致 Python 解释器的崩溃，这是由于 Python AST 编译器有栈深度限制。

在 3.5 版本发生变更: open() 在 flag 为 'n' 时将总是创建一个新数据库。

在 3.8 版本发生变更: 如果 flag 为 'r' 则打开的数据库将为只读的。如果 flag 为 'r' 或 'w' 则当数据库不存在时不会自动创建它。

在 3.11 版本发生变更: filename 接受一个 path-like object。

在 collections.abc.MutableMapping 类所提供的方法之外，还提供了以下方法：

dumbdbm.sync()¶: 同步磁盘上的目录和数据文件。此方法会由 Shelve.sync() 方法来调用。

dumbdbm.close()¶: 关闭数据库。

`dbm` --- Unix "数据库" 接口¶

`dbm.sqlite3` --- SQLite backend for dbm¶

`dbm.gnu` --- GNU 数据库管理器¶

`dbm.ndbm` --- 新数据库管理器¶

`dbm.dumb` --- 便携式 DBM 实现¶

目录

上一主题

下一主题

当前页

dbm --- Unix "数据库" 接口¶

dbm.sqlite3 --- SQLite backend for dbm¶

dbm.gnu --- GNU 数据库管理器¶

dbm.ndbm --- 新数据库管理器¶

dbm.dumb --- 便携式 DBM 实现¶

`dbm` --- Unix "数据库" 接口¶

`dbm.sqlite3` --- SQLite backend for dbm¶

`dbm.gnu` --- GNU 数据库管理器¶

`dbm.ndbm` --- 新数据库管理器¶

`dbm.dumb` --- 便携式 DBM 实现¶