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

源代码: Lib/dbm/__init__.py

dbm 是一种泛用接口，针对各种 DBM 数据库 --- 包括 dbm.gnu 或 dbm.ndbm。 如果未安装这些模块中的任何一种，则将使用 dbm.dumb 模块中慢速但简单的实现。 还有一个适用于 Oracle Berkeley DB 的 第三方接口。

exception dbm.error

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

dbm.whichdb(filename)

此函数会猜测各种简单数据库模块中的哪一个是可用的 --- dbm.gnu, dbm.ndbm 还是 dbm.dumb --- 应该被用来打开给定的文件。

返回下列值中的一个：

  • 如果文件因其不可读或不存在而无法打开则返回 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.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 数据库。

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 数据库。

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

关闭数据库。