Doc/library/dbhash.rst

   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@acm.org>
   7
   8 .. deprecated:: 2.6
   9     The :mod:`dbhash` module has been deprecated for removal in Python 3.0.
  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