Home | History | Annotate | Download | only in library 
      1 :mod:`dbhash` --- DBM-style interface to the BSD database library
      2 =================================================================
      3 
      4 .. module:: dbhash
      5    :synopsis: DBM-style interface to the BSD database library.
      6 .. sectionauthor:: Fred L. Drake, Jr. <fdrake (a] acm.org>
      7 
      8 .. deprecated:: 2.6
      9    The :mod:`dbhash` module has been removed in Python 3.
     10 
     11 .. index:: module: bsddb
     12 
     13 The :mod:`dbhash` module provides a function to open databases using the BSD
     14 ``db`` library.  This module mirrors the interface of the other Python database
     15 modules that provide access to DBM-style databases.  The :mod:`bsddb` module is
     16 required  to use :mod:`dbhash`.
     17 
     18 This module provides an exception and a function:
     19 
     20 
     21 .. exception:: error
     22 
     23    Exception raised on database errors other than :exc:`KeyError`.  It is a synonym
     24    for :exc:`bsddb.error`.
     25 
     26 
     27 .. function:: open(path[, flag[, mode]])
     28 
     29    Open a ``db`` database and return the database object.  The *path* argument is
     30    the name of the database file.
     31 
     32    The *flag* argument can be:
     33 
     34    +---------+-------------------------------------------+
     35    | Value   | Meaning                                   |
     36    +=========+===========================================+
     37    | ``'r'`` | Open existing database for reading only   |
     38    |         | (default)                                 |
     39    +---------+-------------------------------------------+
     40    | ``'w'`` | Open existing database for reading and    |
     41    |         | writing                                   |
     42    +---------+-------------------------------------------+
     43    | ``'c'`` | Open database for reading and writing,    |
     44    |         | creating it if it doesn't exist           |
     45    +---------+-------------------------------------------+
     46    | ``'n'`` | Always create a new, empty database, open |
     47    |         | for reading and writing                   |
     48    +---------+-------------------------------------------+
     49 
     50    For platforms on which the BSD ``db`` library supports locking, an ``'l'``
     51    can be appended to indicate that locking should be used.
     52 
     53    The optional *mode* parameter is used to indicate the Unix permission bits that
     54    should be set if a new database must be created; this will be masked by the
     55    current umask value for the process.
     56 
     57 
     58 .. seealso::
     59 
     60    Module :mod:`anydbm`
     61       Generic interface to ``dbm``\ -style databases.
     62 
     63    Module :mod:`bsddb`
     64       Lower-level interface to the BSD ``db`` library.
     65 
     66    Module :mod:`whichdb`
     67       Utility module used to determine the type of an existing database.
     68 
     69 
     70 .. _dbhash-objects:
     71 
     72 Database Objects
     73 ----------------
     74 
     75 The database objects returned by :func:`.open` provide the methods  common to all
     76 the DBM-style databases and mapping objects.  The following methods are
     77 available in addition to the standard methods.
     78 
     79 
     80 .. method:: dbhash.first()
     81 
     82    It's possible to loop over every key/value pair in the database using this
     83    method and the :meth:`!next` method.  The traversal is ordered by the databases
     84    internal hash values, and won't be sorted by the key values.  This method
     85    returns the starting key.
     86 
     87 
     88 .. method:: dbhash.last()
     89 
     90    Return the last key/value pair in a database traversal.  This may be used to
     91    begin a reverse-order traversal; see :meth:`previous`.
     92 
     93 
     94 .. method:: dbhash.next()
     95 
     96    Returns the key next key/value pair in a database traversal.  The following code
     97    prints every key in the database ``db``, without having to create a list in
     98    memory that contains them all::
     99 
    100       print db.first()
    101       for i in xrange(1, len(db)):
    102           print db.next()
    103 
    104 
    105 .. method:: dbhash.previous()
    106 
    107    Returns the previous key/value pair in a forward-traversal of the database. In
    108    conjunction with :meth:`last`, this may be used to implement a reverse-order
    109    traversal.
    110 
    111 
    112 .. method:: dbhash.sync()
    113 
    114    This method forces any unwritten data to be written to the disk.
    115 
    116