1 :mod:`anydbm` --- Generic access to DBM-style databases

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

     3 

     4 .. module:: anydbm

     5    :synopsis: Generic interface to DBM-style database modules.

     6 

     7 

     8 .. note::

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

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

    11    sources to 3.0.

    12 

    13 .. index::

    14    module: dbhash

    15    module: bsddb

    16    module: gdbm

    17    module: dbm

    18    module: dumbdbm

    19 

    20 :mod:`anydbm` is a generic interface to variants of the DBM database ---

    21 :mod:`dbhash` (requires :mod:`bsddb`), :mod:`gdbm`, or :mod:`dbm`.  If none of

    22 these modules is installed, the slow-but-simple implementation in module

    23 :mod:`dumbdbm` will be used.

    24 

    25 

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

    27 

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

    29 

    30    If the database file already exists, the :mod:`whichdb` module is  used to

    31    determine its type and the appropriate module is used; if it does not exist, the

    32    first module listed above that can be imported is used.

    33 

    34    The optional *flag* argument can be ``'r'`` to open an existing database for

    35    reading only, ``'w'`` to open an existing database for reading and writing,

    36    ``'c'`` to create the database if it doesn't exist, or ``'n'``, which will

    37    always create a new empty database.  If not specified, the default value is

    38    ``'r'``.

    39 

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

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

    42    by the prevailing umask).

    43 

    44 

    45 .. exception:: error

    46 

    47    A tuple containing the exceptions that can be raised by each of the supported

    48    modules, with a unique exception also named :exc:`anydbm.error` as the first

    49    item --- the latter is used when :exc:`anydbm.error` is raised.

    50 

    51 The object returned by :func:`open` supports most of the same functionality as

    52 dictionaries; keys and their corresponding values can be stored, retrieved, and

    53 deleted, and the :meth:`has_key` and :meth:`keys` methods are available.  Keys

    54 and values must always be strings.

    55 

    56 The following example records some hostnames and a corresponding title,  and

    57 then prints out the contents of the database::

    58 

    59    import anydbm

    60 

    61    # Open database, creating it if necessary.

    62    db = anydbm.open('cache', 'c')

    63 

    64    # Record some values

    65    db['www.python.org'] = 'Python Website'

    66    db['www.cnn.com'] = 'Cable News Network'

    67 

    68    # Loop through contents.  Other dictionary methods

    69    # such as .keys(), .values() also work.

    70    for k, v in db.iteritems():

    71        print k, '\t', v

    72 

    73    # Storing a non-string key or value will raise an exception (most

    74    # likely a TypeError).

    75    db['www.yahoo.com'] = 4

    76 

    77    # Close when done.

    78    db.close()

    79 

    80 

    81 .. seealso::

    82 

    83    Module :mod:`dbhash`

    84       BSD ``db`` database interface.

    85 

    86    Module :mod:`dbm`

    87       Standard Unix database interface.

    88 

    89    Module :mod:`dumbdbm`

    90       Portable implementation of the ``dbm`` interface.

    91 

    92    Module :mod:`gdbm`

    93       GNU database interface, based on the ``dbm`` interface.

    94 

    95    Module :mod:`shelve`

    96       General object persistence built on top of  the Python ``dbm`` interface.

    97 

    98    Module :mod:`whichdb`

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

   100