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)

Open a database and return the corresponding database object.

参数:

  • file (path-like object) --

    The database file to open.

    If the database file already exists, the whichdb() function is used to determine its type and the appropriate module is used; if it does not exist, the first submodule listed above that can be imported is used.

  • 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。

The object returned by open() supports the same basic functionality as a dict; keys and their corresponding values can be stored, retrieved, and deleted, and the in operator and the keys() method are available, as well as get() and setdefault() methods.

键和值总是被存储为 bytes。 这意味着当使用字符串时它们会在被存储之前隐式地转换至默认编码格式。

这些对象也支持在 with 语句中使用，当语句结束时将自动关闭它们。

在 3.2 版本发生变更: get() and setdefault() methods are now available for all dbm backends.

在 3.4 版本发生变更: Added native support for the context management protocol to the objects returned by open().

在 3.8 版本发生变更: Deleting a key from a read-only database raises a database module specific exception instead of 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 模块，但带有额外的功能如对崩溃的容忍。

gdbm 对象的行为类似于 映射，区别在于键和值总是会在存储之前被转换为 bytes，并且不支持 items() 和 values() 方法。

备注

The file formats created by dbm.gnu and dbm.ndbm are incompatible and can not be used interchangeably.

exception dbm.gnu.error

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

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

Open a GDBM database and return a gdbm object.

参数:

  • filename (path-like object) -- The database file to open.

  • 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.

    The following additional characters may be appended to control how the database is opened:

    • 'f': Open the database in fast mode. Writes to the database will not be synchronized.

    • 's': Synchronized mode. Changes to the database will be written immediately to the file.

    • 'u': Do not lock database.

    Not all flags are valid for all versions of GDBM. See the open_flags member for a list of supported flag characters.

  • mode (int) -- The Unix file access mode of the file (default: octal 0o666), used only when the database has to be created.

抛出:

error -- If an invalid flag argument is passed.

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

dbm.gnu.open_flags

A string of characters the flag parameter of open() supports.

In addition to the dictionary-like methods, gdbm objects have the following methods and attributes:

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 对象的行为类似于 映射，区别在于键和值总是被存储为 bytes，并且不支持 items() 和 values() 方法。

此模块可与 "经典" NDBM 接口或 GDBM 兼容接口一起使用。

备注

The file formats created by dbm.gnu and dbm.ndbm are incompatible and can not be used interchangeably.

警告

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

exception dbm.ndbm.error

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

dbm.ndbm.library

所使用的 NDBM 实现库的名称。

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

Open an NDBM database and return an ndbm object.

参数:

  • filename (path-like object) -- The basename of the database file (without the .dir or .pag extensions).

  • 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 对象还提供了下列方法：

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

ndbm.close()

关闭 NDBM 数据库。

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

源代码: Lib/dbm/dumb.py

备注

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

The dbm.dumb module provides a persistent dict-like interface which is written entirely in Python. Unlike other dbm backends, such as dbm.gnu, no external library is required. As with other dbm backends, the keys and values are always stored as bytes.

The dbm.dumb module defines the following:

exception dbm.dumb.error

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

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

Open a dbm.dumb database. The returned database object behaves similar to a mapping, in addition to providing sync() and close() methods.

参数:

  • filename --

    The basename of the database file (without extensions). A new database creates the following files:

    • 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() always creates a new database when flag is 'n'.

在 3.8 版本发生变更: A database opened read-only if flag is 'r'. A database is not created if it does not exist if flag is 'r' or 'w'.

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

In addition to the methods provided by the collections.abc.MutableMapping class, the following methods are provided:

dumbdbm.sync()

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

dumbdbm.close()

Close the database.