Home | History | Annotate | Download | only in library 
      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.  The
     10    :term:`2to3` tool will automatically adapt imports when converting your
     11    sources to Python 3.
     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,
     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 
     65 The object returned by :func:`.open` supports most of the same functionality as
     66 dictionaries; keys and their corresponding values can be stored, retrieved, and
     67 deleted, and the :meth:`has_key` and :meth:`keys` methods are available.  Keys
     68 and values must always be strings.
     69 
     70 The following example records some hostnames and a corresponding title,  and
     71 then 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 In addition to the dictionary-like methods, ``anydbm`` objects
     96 provide the following method:
     97 
     98 .. function:: close()
     99 
    100    Close the ``anydbm`` database.
    101 
    102 
    103 .. seealso::
    104 
    105    Module :mod:`dbhash`
    106       BSD ``db`` database interface.
    107 
    108    Module :mod:`dbm`
    109       Standard Unix database interface.
    110 
    111    Module :mod:`dumbdbm`
    112       Portable implementation of the ``dbm`` interface.
    113 
    114    Module :mod:`gdbm`
    115       GNU database interface, based on the ``dbm`` interface.
    116 
    117    Module :mod:`shelve`
    118       General object persistence built on top of  the Python ``dbm`` interface.
    119 
    120    Module :mod:`whichdb`
    121       Utility module used to determine the type of an existing database.
    122 
    123