dbm — Interfaces to Unix “databases”

Source code:Lib/dbm/__init__.py

dbm is a generic interface to variants of the DBM database —dbm.gnu ordbm.ndbm. If none of these modules is installed, theslow-but-simple implementation in moduledbm.dumb will be used. Thereis athird party interface tothe Oracle Berkeley DB.

exceptiondbm.error

A tuple containing the exceptions that can be raised by each of the supportedmodules, with a unique exception also nameddbm.error as the firstitem — the latter is used whendbm.error is raised.

dbm.whichdb(filename)

This function attempts to guess which of the several simple database modulesavailable —dbm.gnu,dbm.ndbm ordbm.dumb — shouldbe used to open a given file.

Returns one of the following values:None if the file can’t be openedbecause it’s unreadable or doesn’t exist; the empty string ('') if thefile’s format can’t be guessed; or a string containing the required modulename, such as'dbm.ndbm' or'dbm.gnu'.

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

Open the database filefile and return a corresponding object.

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

The optionalflag argument can be:

Value

Meaning

'r'

Open existing database for reading only(default)

'w'

Open existing database for reading andwriting

'c'

Open database for reading and writing,creating it if it doesn’t exist

'n'

Always create a new, empty database, openfor reading and writing

The optionalmode argument is the Unix mode of the file, used only when thedatabase has to be created. It defaults to octal0o666 (and will bemodified by the prevailing umask).

The object returned byopen() supports the same basic functionality asdictionaries; keys and their corresponding values can be stored, retrieved, anddeleted, and thein operator and thekeys() method areavailable, as well asget() andsetdefault().

Changed in version 3.2:get() andsetdefault() are now available in all database modules.

Changed in version 3.8:Deleting a key from a read-only database raises database module specific errorinstead ofKeyError.

Key and values are always stored as bytes. This means that whenstrings are used they are implicitly converted to the default encoding beforebeing stored.

These objects also support being used in awith statement, whichwill automatically close them when done.

Changed in version 3.4:Added native support for the context management protocol to the objectsreturned byopen().

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

importdbm# Open database, creating it if necessary.withdbm.open('cache','c')asdb:# Record some valuesdb[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.assertdb[b'www.python.org']==b'Python Website'# Notice how the value is now in bytes.assertdb['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.

See also

Moduleshelve

Persistence module which stores non-string data.

The individual submodules are described in the following sections.

dbm.gnu — GNU’s reinterpretation of dbm

Source code:Lib/dbm/gnu.py

This module is quite similar to thedbm module, but uses the GNU librarygdbm instead to provide some additional functionality. Please note that thefile formats created bydbm.gnu anddbm.ndbm are incompatible.

Thedbm.gnu module provides an interface to the GNU DBM library.dbm.gnu.gdbm objects behave like mappings (dictionaries), except that keys andvalues are always converted to bytes before storing. Printing agdbmobject doesn’t print thekeys and values, and theitems() andvalues() methods are notsupported.

exceptiondbm.gnu.error

Raised ondbm.gnu-specific errors, such as I/O errors.KeyError israised for general mapping errors like specifying an incorrect key.

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

Open agdbm database and return agdbm object. Thefilenameargument is the name of the database file.

The optionalflag argument can be:

Value

Meaning

'r'

Open existing database for reading only(default)

'w'

Open existing database for reading andwriting

'c'

Open database for reading and writing,creating it if it doesn’t exist

'n'

Always create a new, empty database, openfor reading and writing

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

Value

Meaning

'f'

Open the database in fast mode. Writesto the database will not be synchronized.

's'

Synchronized mode. This will cause changesto the database to be immediately writtento the file.

'u'

Do not lock database.

Not all flags are valid for all versions ofgdbm. The module constantopen_flags is a string of supported flag characters. The exceptionerror is raised if an invalid flag is specified.

The optionalmode argument is the Unix mode of the file, used only when thedatabase has to be created. It defaults to octal0o666.

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

gdbm.firstkey()

It’s possible to loop over every key in the database using this method and thenextkey() method. The traversal is ordered bygdbm’s internalhash values, and won’t be sorted by the key values. This method returnsthe starting key.

gdbm.nextkey(key)

Returns the key that followskey in the traversal. The following code printsevery key in the databasedb, without having to create a list in memory thatcontains them all:

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

If you have carried out a lot of deletions and would like to shrink the spaceused by thegdbm file, this routine will reorganize the database.gdbmobjects will not shorten the length of a database file except by using thisreorganization; 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 anyunwritten data to be written to the disk.

gdbm.close()

Close thegdbm database.

dbm.ndbm — Interface based on ndbm

Source code:Lib/dbm/ndbm.py

Thedbm.ndbm module provides an interface to the Unix “(n)dbm” library.Dbm objects behave like mappings (dictionaries), except that keys and values arealways stored as bytes. Printing adbm object doesn’t print the keys andvalues, and theitems() andvalues() methods are not supported.

This module can be used with the “classic” ndbm interface or the GNU GDBMcompatibility interface. On Unix, theconfigure script will attemptto locate the appropriate header file to simplify building this module.

exceptiondbm.ndbm.error

Raised ondbm.ndbm-specific errors, such as I/O errors.KeyError is raisedfor general mapping errors like specifying an incorrect key.

dbm.ndbm.library

Name of thendbm implementation library used.

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

Open a dbm database and return andbm object. Thefilename argument is thename of the database file (without the.dir or.pag extensions).

The optionalflag argument must be one of these values:

Value

Meaning

'r'

Open existing database for reading only(default)

'w'

Open existing database for reading andwriting

'c'

Open database for reading and writing,creating it if it doesn’t exist

'n'

Always create a new, empty database, openfor reading and writing

The optionalmode argument is the Unix mode of the file, used only when thedatabase has to be created. It defaults to octal0o666 (and will bemodified by the prevailing umask).

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

ndbm.close()

Close thendbm database.

dbm.dumb — Portable DBM implementation

Source code:Lib/dbm/dumb.py

Note

Thedbm.dumb module is intended as a last resort fallback for thedbm module when a more robust module is not available. Thedbm.dumbmodule is not written for speed and is not nearly as heavily used as the otherdatabase modules.

Thedbm.dumb module provides a persistent dictionary-like interface whichis written entirely in Python. Unlike other modules such asdbm.gnu noexternal library is required. As with other persistent mappings, the keys andvalues are always stored as bytes.

The module defines the following:

exceptiondbm.dumb.error

Raised ondbm.dumb-specific errors, such as I/O errors.KeyError israised for general mapping errors like specifying an incorrect key.

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

Open adumbdbm database and return a dumbdbm object. Thefilename argument isthe basename of the database file (without any specific extensions). When adumbdbm database is created, files with.dat and.dir extensionsare created.

The optionalflag argument can be:

Value

Meaning

'r'

Open existing database for reading only(default)

'w'

Open existing database for reading andwriting

'c'

Open database for reading and writing,creating it if it doesn’t exist

'n'

Always create a new, empty database, openfor reading and writing

The optionalmode argument is the Unix mode of the file, used only when thedatabase has to be created. It defaults to octal0o666 (and will be modifiedby the prevailing umask).

Warning

It is possible to crash the Python interpreter when loading a databasewith a sufficiently large/complex entry due to stack depth limitations inPython’s AST compiler.

Changed in version 3.5:open() always creates a new database when the flag has the value'n'.

Changed in version 3.8:A database opened with flags'r' is now read-only. Opening withflags'r' and'w' no longer creates a database if it does notexist.

In addition to the methods provided by thecollections.abc.MutableMapping class,dumbdbm objectsprovide the following methods:

dumbdbm.sync()

Synchronize the on-disk directory and data files. This method is calledby theShelve.sync() method.

dumbdbm.close()

Close thedumbdbm database.