Source

cpython-withatomic / Doc / library / dbm.rst

Full commit

:mod:`dbm` --- Interfaces to Unix "databases"

:mod:`dbm` is a generic interface to variants of the DBM database --- :mod:`dbm.gnu` or :mod:`dbm.ndbm`. If none of these modules is installed, the slow-but-simple implementation in module :mod:`dbm.dumb` will be used. There is a third party interface to the Oracle Berkeley DB.

The object returned by :func:`.open` supports the same basic functionality as dictionaries; keys and their corresponding values can be stored, retrieved, and deleted, and the :keyword:`in` operator and the :meth:`keys` method are available, as well as :meth:`get` and :meth:`setdefault`.

Key and values are always stored as bytes. This means that when strings are used they are implicitly converted to the default encoding before being stored.

The following example records some hostnames and a corresponding title, and then prints out the contents of the database:

import dbm

# Open database, creating it if necessary.
db = dbm.open('cache', 'c')

# 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

# Close when done.
db.close()

The individual submodules are described in the following sections.

:mod:`dbm.gnu` --- GNU's reinterpretation of dbm

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

The :mod:`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 :meth:`items` and :meth:`values` methods are not supported.

:mod:`dbm.ndbm` --- Interface based on ndbm

The :mod:`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 :meth:`items` and :meth:`values` methods are not supported.

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

:mod:`dbm.dumb` --- Portable DBM implementation

Note

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

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

The module defines the following: