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 removed in Python 3. 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 116