:mod:`dbm.bsd` --- DBM-style interface to the BSD database library

.. module:: dbm.bsd

:synopsis: DBM-style interface to the BSD database library.

.. sectionauthor:: Fred L. Drake, Jr. <[email protected]>

.. index:: module: bsddb

The :mod:`dbm.bsd` module provides a function to open databases using the BSD

``db`` library. This module mirrors the interface of the other Python database

modules that provide access to DBM-style databases. The :mod:`bsddb` module is

required to use :mod:`dbm.bsd`.

.. exception:: error

Exception raised on database errors other than :exc:`KeyError`. It is a synonym

for :exc:`bsddb.error`.

.. function:: open(path[, flag[, mode]])

Open a ``db`` database and return the database object. The *path* argument is

the name of the database file.

The *flag* argument can be:

+---------+-------------------------------------------+

| Value | Meaning |

+=========+===========================================+

| ``'r'`` | Open existing database for reading only |

| | (default) |

+---------+-------------------------------------------+

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

+---------+-------------------------------------------+

For platforms on which the BSD ``db`` library supports locking, an ``'l'``

can be appended to indicate that locking should be used.

The optional *mode* parameter is used to indicate the Unix permission bits that

should be set if a new database must be created; this will be masked by the

current umask value for the process.

The database objects returned by :func:`open` provide the methods common to all

the DBM-style databases and mapping objects. The following methods are

available in addition to the standard methods:

.. method:: dbhash.first()

It's possible to loop over every key/value pair in the database using this

method and the :meth:`next` method. The traversal is ordered by the databases

internal hash values, and won't be sorted by the key values. This method

returns the starting key.

.. method:: dbhash.last()

Return the last key/value pair in a database traversal. This may be used to

begin a reverse-order traversal; see :meth:`previous`.

.. method:: dbhash.next()

Returns the key next key/value pair in a database traversal. The following code

prints every key in the database ``db``, without having to create a list in

memory that contains them all::

.. method:: dbhash.previous()

Returns the previous key/value pair in a forward-traversal of the database. In

conjunction with :meth:`last`, this may be used to implement a reverse-order

traversal.

.. method:: dbhash.sync()

This method forces any unwritten data to be written to the disk.