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