1 :mod:`dbm` --- Simple "database" interface

     2 ==========================================

     3 

     4 .. module:: dbm

     5    :platform: Unix

     6    :synopsis: The standard "database" interface, based on ndbm.

     7 

     8 .. note::

     9    The :mod:`dbm` module has been renamed to :mod:`dbm.ndbm` in Python 3.0.  The

    10    :term:`2to3` tool will automatically adapt imports when converting your

    11    sources to 3.0.

    12 

    13 

    14 The :mod:`dbm` module provides an interface to the Unix "(n)dbm" library.  Dbm

    15 objects behave like mappings (dictionaries), except that keys and values are

    16 always strings. Printing a dbm object doesn't print the keys and values, and the

    17 :meth:`items` and :meth:`values` methods are not supported.

    18 

    19 This module can be used with the "classic" ndbm interface, the BSD DB

    20 compatibility interface, or the GNU GDBM compatibility interface. On Unix, the

    21 :program:`configure` script will attempt to locate the appropriate header file

    22 to simplify building this module.

    23 

    24 The module defines the following:

    25 

    26 

    27 .. exception:: error

    28 

    29    Raised on dbm-specific errors, such as I/O errors. :exc:`KeyError` is raised for

    30    general mapping errors like specifying an incorrect key.

    31 

    32 

    33 .. data:: library

    34 

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

    36 

    37 

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

    39 

    40    Open a dbm database and return a dbm object.  The *filename* argument is the

    41    name of the database file (without the :file:`.dir` or :file:`.pag` extensions;

    42    note that the BSD DB implementation of the interface will append the extension

    43    :file:`.db` and only create one file).

    44 

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

    46 

    47    +---------+-------------------------------------------+

    48    | Value   | Meaning                                   |

    49    +=========+===========================================+

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

    51    |         | (default)                                 |

    52    +---------+-------------------------------------------+

    53    | ``'w'`` | Open existing database for reading and    |

    54    |         | writing                                   |

    55    +---------+-------------------------------------------+

    56    | ``'c'`` | Open database for reading and writing,    |

    57    |         | creating it if it doesn't exist           |

    58    +---------+-------------------------------------------+

    59    | ``'n'`` | Always create a new, empty database, open |

    60    |         | for reading and writing                   |

    61    +---------+-------------------------------------------+

    62 

    63    The optional *mode* argument is the Unix mode of the file, used only when the

    64    database has to be created.  It defaults to octal ``0666`` (and will be

    65    modified by the prevailing umask).

    66 

    67 

    68 .. seealso::

    69 

    70    Module :mod:`anydbm`

    71       Generic interface to ``dbm``\ -style databases.

    72 

    73    Module :mod:`gdbm`

    74       Similar interface to the GNU GDBM library.

    75 

    76    Module :mod:`whichdb`

    77       Utility module used to determine the type of an existing database.

    78