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

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() 在所有数据库模块中均可用。

在 3.8 版更改: 从只读数据库中删除键将引发数据库模块专属的错误而不是 KeyError。

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

这些对象也支持在 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

---

This module is quite similar to the dbm module, but uses the GNU library gdbm instead to provide some additional functionality. Please note that the file formats created by dbm.gnu and dbm.ndbm are incompatible.

The dbm.gnu module provides an interface to the GNU DBM library. dbm.gnu.gdbm objects behave like mappings (dictionaries), except that keys and values are always converted to bytes before storing. Printing a gdbm object doesn't print the keys and values, and the items() and values() methods are not supported.

exception dbm.gnu.error

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

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

Open a gdbm database and return a gdbm object. The filename argument is the name of the database file.

可选的 flag 参数可以是：

值	意义
'r'	以只读方式打开现有数据库（默认）
'w'	以读写方式打开现有数据库
'c'	以读写方式打开数据库，如果不存在则创建它
'n'	始终创建一个新的空数据库，以读写方式打开

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

值	意义
'f'	以快速模式打开数据库。写入数据库将不会同步。
's'	同步模式。这将导致数据库的更改立即写入文件。
'u'	不要锁定数据库。

Not all flags are valid for all versions of gdbm. The module constant open_flags is a string of supported flag characters. The exception error is raised if an invalid flag is specified.

The optional mode argument is the Unix mode of the file, used only when the database has to be created. It defaults to octal 0o666.

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

gdbm.firstkey()

It's possible to loop over every key in the database using this method and the nextkey() method. The traversal is ordered by gdbm's internal hash values, and won't be sorted by the key values. This method returns the starting key.

gdbm.nextkey(key)

Returns the key that follows key in the traversal. The following code prints every key in the database db, without having to create a list in memory that contains them all:

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

gdbm.reorganize()

If you have carried out a lot of deletions and would like to shrink the space used by the gdbm file, this routine will reorganize the database. gdbm objects will not shorten the length of a database file except by using this reorganization; otherwise, deleted file space will be kept and reused as new (key, value) pairs are added.

gdbm.sync()

When the database has been opened in fast mode, this method forces any unwritten data to be written to the disk.

gdbm.close()

Close the gdbm database.

dbm.ndbm --- Interface based on 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.

可选的 flag 参数可以是：

值	意义
'r'	以只读方式打开现有数据库（默认）
'w'	以读写方式打开现有数据库
'c'	以读写方式打开数据库，如果不存在则创建它
'n'	始终创建一个新的空数据库，以读写方式打开

可选的 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'.

在 3.8 版更改: A database opened with flags 'r' is now read-only. Opening with flags 'r' and 'w' no longer creates a database if it does not exist.

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.