/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
 13The :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
 15modules that provide access to DBM-style databases.  The :mod:`bsddb` module is
 16required  to use :mod:`dbhash`.
 17
 18This 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
 72Database Objects
 73----------------
 74
 75The database objects returned by :func:`open` provide the methods  common to all
 76the DBM-style databases and mapping objects.  The following methods are
 77available 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