Doc/library/dbm.rst

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

.. module:: dbm
   :synopsis: Interfaces to various Unix "database" formats.

:mod:`dbm` is a generic interface to variants of the DBM database ---
:mod:`dbm.bsd` (requires :mod:`bsddb`), :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.


.. exception:: error

   A tuple containing the exceptions that can be raised by each of the supported
   modules, with a unique exception also named :exc:`dbm.error` as the first
   item --- the latter is used when :exc:`dbm.error` is raised.


.. function:: whichdb(filename)

   This functionattempts to guess which of the several simple database modules
   available --- :mod:`dbm.bsd`, :mod:`dbm.gnu`, :mod:`dbm.ndbm` or
   :mod:`dbm.dumb` --- should be used to open a given file.

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


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

   Open the database file *filename* and return a corresponding object.

   If the database file already exists, the :func:`whichdb` function is used to
   determine 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 optional *flag* argument can be ``'r'`` to open an existing database for
   reading only, ``'w'`` to open an existing database for reading and writing,
   ``'c'`` to create the database if it doesn't exist, or ``'n'``, which will
   always create a new empty database.  If not specified, the default value is
   ``'r'``.

   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`` (and will be
   modified by the prevailing umask).


The object returned by :func:`open` supports most of the same 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.  Keys and values must always be strings.

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['www.python.org'] = 'Python Website'
   db['www.cnn.com'] = 'Cable News Network'

   # Loop through contents.  Other dictionary methods
   # such as .keys(), .values() also work.
   for k, v in db.iteritems():
       print(k, '\t', v)

   # 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()


.. seealso::

   Module :mod:`shelve`
      Persistence module which stores non-string data.


The individual submodules are described in the following sections.


: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. <fdrake@acm.org>

.. 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::

         print(db.first())
         for i in range(1, len(db)):
             print(db.next())

   .. 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.


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

.. module:: dbm.gnu
   :platform: Unix
   :synopsis: 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 ``gdbm`` and ``dbm`` are incompatible.

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

.. exception:: error

   Raised on ``gdbm``\ -specific errors, such as I/O errors. :exc:`KeyError` is
   raised for general mapping errors like specifying an incorrect key.


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

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

   The optional *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                   |
   +---------+-------------------------------------------+

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

   +---------+--------------------------------------------+
   | Value   | Meaning                                    |
   +=========+============================================+
   | ``'f'`` | Open the database in fast mode.  Writes    |
   |         | to the database will not be synchronized.  |
   +---------+--------------------------------------------+
   | ``'s'`` | Synchronized mode. This will cause changes |
   |         | to the database to be immediately written  |
   |         | to the file.                               |
   +---------+--------------------------------------------+
   | ``'u'`` | Do not lock database.                      |
   +---------+--------------------------------------------+

   Not all flags are valid for all versions of ``gdbm``.  The module constant
   :const:`open_flags` is a string of supported flag characters.  The exception
   :exc:`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:

   .. method:: gdbm.firstkey()

      It's possible to loop over every key in the database using this method  and the
      :meth:`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.

   .. method:: 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)

   .. method:: 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``
      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.

   .. method:: gdbm.sync()

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


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

.. module:: dbm.ndbm
   :platform: Unix
   :synopsis: The standard "database" 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 strings. 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, the BSD DB
compatibility 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.

.. exception:: error

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


.. data:: library

   Name of the ``ndbm`` implementation library used.


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

   Open a dbm database and return a dbm object.  The *filename* argument is the
   name of the database file (without the :file:`.dir` or :file:`.pag` extensions;
   note that the BSD DB implementation of the interface will append the extension
   :file:`.db` and only create one file).

   The optional *flag* argument must be one of these values:

   +---------+-------------------------------------------+
   | 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                   |
   +---------+-------------------------------------------+

   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`` (and will be
   modified by the prevailing umask).



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

.. module:: dbm.dumb
   :synopsis: Portable implementation of the simple DBM interface.

.. index:: single: databases

.. note::

   The :mod:`dbm.dumb` module is intended as a last resort fallback for the
   :mod:`dbm` module when no more robust module is 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:`gdbm` and
:mod:`bsddb`, no external library is required.  As with other persistent
mappings, the keys and values must always be strings.

The module defines the following:


.. exception:: error

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


.. function:: 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 :file:`.dat` and :file:`.dir` extensions
   are created.

   The optional *flag* argument is currently ignored; the database is always opened
   for update, and will be created if it does not exist.

   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`` (and will be modified
   by the prevailing umask).

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

   .. method:: dumbdbm.sync()

      Synchronize the on-disk directory and data files.  This method is called
      by the :meth:`Shelve.sync` method.