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

源代码: Lib/dbm/__init__.py


dbm 是一种泛用接口,针对各种 DBM 数据库 --- 包括 dbm.gnudbm.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'

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

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

如果数据库文件已存在,则使用 whichdb() 函数来确定其类型和要使用的适当模块;如果文件不存在,则会使用上述可导入模块中的第一个。

可选的 flag 参数可以是:

含义

'r'

以只读方式打开现有数据库(默认)

'w'

以读写方式打开现有数据库

'c'

以读写方式打开数据库,如果不存在则创建它

'n'

始终创建一个新的空数据库,以读写方式打开

可选的 mode 参数是文件的 Unix 模式,仅在要创建数据库时才会被使用。 其默认值为八进制数 0o666 (并将被当前的 umask 所修改)。

open() 所返回的对象支持与字典相同的基本功能;可以存储、获取和删除键及其对应的值,并可使用 in 运算符和 keys() 方法,以及 get()setdefault()

在 3.2 版更改: 现在 get()setdefault() 在所有数据库模块中均可用。

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

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

在 3.4 版更改: open() 所返回的对象添加了上下文管理协议的原生支持。

以下示例记录了一些主机名和对应的标题,随后将数据库的内容打印出来。:

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 对 dbm 的重解析

源代码: Lib/dbm/gnu.py


此模块与 dbm 模块很相似,但是改用 GNU 库 gdbm 来提供某些附加功能。 请注意由 dbm.gnudbm.ndbm 所创建的文件格式是不兼容的。

dbm.gnu 模块提供了对 GNU DBM 库的接口。 dbm.gnu.gdbm 对象的行为类似于映射(字典),区别在于其键和值总是会在存储之前被转换为字节串。 打印 gdbm 对象不会打印出键和值,并且 items()values() 等方法也不受支持。

exception dbm.gnu.error

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

dbm.gnu.open(filename[, flag[, mode]])

打开一个 gdbm 数据库并返回 gdbm 对象。 filename 参数为数据库文件名称。

可选的 flag 参数可以是:

含义

'r'

以只读方式打开现有数据库(默认)

'w'

以读写方式打开现有数据库

'c'

以读写方式打开数据库,如果不存在则创建它

'n'

始终创建一个新的空数据库,以读写方式打开

下列附加字符可被添加至旗标以控制数据库的打开方式:

含义

'f'

以快速模式打开数据库。写入数据库将不会同步。

's'

同步模式。这将导致数据库的更改立即写入文件。

'u'

不要锁定数据库。

不是所有旗标都可用于所有版本的 gdbm。 模块常量 open_flags 为包含受支持旗标字符的字符串。 如果指定了无效的旗标则会引发 error

可选的 mode 参数是文件的 Unix 模式,仅在要创建数据库时才会被使用。 其默认值为八进制数 0o666

除了与字典类似的方法,gdbm 对象还有以下方法:

gdbm.firstkey()

使用此方法和 nextkey() 方法可以循环遍历数据库中的每个键。 遍历的顺序是按照 gdbm 的内部哈希值,而不会根据键的值排序。 此方法将返回起始键。

gdbm.nextkey(key)

在遍历中返回 key 之后的的下一个键。 以下代码将打印数据库 db 中的每个键,而不会在内存中创建一个包含所有键的列表:

k = db.firstkey()
while k != None:
    print(k)
    k = db.nextkey(k)
gdbm.reorganize()

如果你进行了大量删除操作并且想要缩减 gdbm 文件所使用的空间,此例程将可重新组织数据库。 除非使用此重组功能否则 gdbm 对象不会缩减数据库文件大小;在其他情况下,被删除的文件空间将会保留并在添加新的 (键, 值) 对时被重用。

gdbm.sync()

当以快速模式打开数据库时,此方法会将任何未写入数据强制写入磁盘。

gdbm.close()

关闭 gdbm 数据库。

dbm.ndbm --- 基于 ndbm 的接口

源代码: Lib/dbm/ndbm.py


The dbm.ndbm module provides an interface to the Unix "(n)dbm" library. Dbm objects behave like mappings (dictionaries), except that keys and values are always stored as bytes. Printing a dbm object doesn't print the keys and values, and the items() and values() methods are not supported.

This module can be used with the "classic" ndbm interface or the GNU GDBM compatibility interface. On Unix, the configure script will attempt to locate the appropriate header file to simplify building this module.

exception dbm.ndbm.error

Raised on dbm.ndbm-specific errors, such as I/O errors. KeyError is raised for general mapping errors like specifying an incorrect key.

dbm.ndbm.library

Name of the ndbm implementation library used.

dbm.ndbm.open(filename[, flag[, mode]])

Open a dbm database and return a ndbm object. The filename argument is the name of the database file (without the .dir or .pag extensions).

The optional flag argument must be one of these values:

含义

'r'

以只读方式打开现有数据库(默认)

'w'

以读写方式打开现有数据库

'c'

以读写方式打开数据库,如果不存在则创建它

'n'

始终创建一个新的空数据库,以读写方式打开

可选的 mode 参数是文件的 Unix 模式,仅在要创建数据库时才会被使用。 其默认值为八进制数 0o666 (并将被当前的 umask 所修改)。

In addition to the dictionary-like methods, ndbm objects provide the following method:

ndbm.close()

Close the ndbm database.

dbm.dumb --- Portable DBM implementation

源代码: Lib/dbm/dumb.py

注解

The dbm.dumb module is intended as a last resort fallback for the dbm module when a more robust module is not available. The dbm.dumb module is not written for speed and is not nearly as heavily used as the other database modules.


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

该模块定义以下内容:

exception dbm.dumb.error

Raised on dbm.dumb-specific errors, such as I/O errors. KeyError is raised for general mapping errors like specifying an incorrect key.

dbm.dumb.open(filename[, flag[, mode]])

Open a dumbdbm database and return a dumbdbm object. The filename argument is the basename of the database file (without any specific extensions). When a dumbdbm database is created, files with .dat and .dir extensions are created.

The optional flag argument supports only the semantics of 'c' and 'n' values. Other values will default to database being always opened for update, and will be created if it does not exist.

可选的 mode 参数是文件的 Unix 模式,仅在要创建数据库时才会被使用。 其默认值为八进制数 0o666 (并将被当前的 umask 所修改)。

警告

It is possible to crash the Python interpreter when loading a database with a sufficiently large/complex entry due to stack depth limitations in Python's AST compiler.

在 3.5 版更改: open() always creates a new database when the flag has the value 'n'.

Deprecated since version 3.6, will be removed in version 3.8: Creating database in 'r' and 'w' modes. Modifying database in 'r' mode.

In addition to the methods provided by the collections.abc.MutableMapping class, dumbdbm objects provide the following methods:

dumbdbm.sync()

Synchronize the on-disk directory and data files. This method is called by the Shelve.sync() method.

dumbdbm.close()

Close the dumbdbm database.