/Doc/library/anydbm.rst

  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
 22these 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,
 32   the first module listed above that can be imported is used.
 33
 34   The optional *flag* argument must be one of these values:
 35
 36   +---------+-------------------------------------------+
 37   | Value   | Meaning                                   |
 38   +=========+===========================================+
 39   | ``'r'`` | Open existing database for reading only   |
 40   |         | (default)                                 |
 41   +---------+-------------------------------------------+
 42   | ``'w'`` | Open existing database for reading and    |
 43   |         | writing                                   |
 44   +---------+-------------------------------------------+
 45   | ``'c'`` | Open database for reading and writing,    |
 46   |         | creating it if it doesn't exist           |
 47   +---------+-------------------------------------------+
 48   | ``'n'`` | Always create a new, empty database, open |
 49   |         | for reading and writing                   |
 50   +---------+-------------------------------------------+
 51
 52   If not specified, the default value is ``'r'``.
 53
 54   The optional *mode* argument is the Unix mode of the file, used only when the
 55   database has to be created.  It defaults to octal ``0666`` (and will be
 56   modified by the prevailing umask).
 57
 58
 59.. exception:: error
 60
 61   A tuple containing the exceptions that can be raised by each of the supported
 62   modules, with a unique exception also named :exc:`anydbm.error` as the first
 63   item --- the latter is used when :exc:`anydbm.error` is raised.
 64
 65The object returned by :func:`open` supports most of the same functionality as
 66dictionaries; keys and their corresponding values can be stored, retrieved, and
 67deleted, and the :meth:`has_key` and :meth:`keys` methods are available.  Keys
 68and values must always be strings.
 69
 70The following example records some hostnames and a corresponding title,  and
 71then prints out the contents of the database::
 72
 73   import anydbm
 74
 75   # Open database, creating it if necessary.
 76   db = anydbm.open('cache', 'c')
 77
 78   # Record some values
 79   db['www.python.org'] = 'Python Website'
 80   db['www.cnn.com'] = 'Cable News Network'
 81
 82   # Loop through contents.  Other dictionary methods
 83   # such as .keys(), .values() also work.
 84   for k, v in db.iteritems():
 85       print k, '\t', v
 86
 87   # Storing a non-string key or value will raise an exception (most
 88   # likely a TypeError).
 89   db['www.yahoo.com'] = 4
 90
 91   # Close when done.
 92   db.close()
 93
 94
 95.. seealso::
 96
 97   Module :mod:`dbhash`
 98      BSD ``db`` database interface.
 99
100   Module :mod:`dbm`
101      Standard Unix database interface.
102
103   Module :mod:`dumbdbm`
104      Portable implementation of the ``dbm`` interface.
105
106   Module :mod:`gdbm`
107      GNU database interface, based on the ``dbm`` interface.
108
109   Module :mod:`shelve`
110      General object persistence built on top of  the Python ``dbm`` interface.
111
112   Module :mod:`whichdb`
113      Utility module used to determine the type of an existing database.
114