1:mod:`gdbm` --- GNU's reinterpretation of dbm 2============================================= 3 4.. module:: gdbm 5 :platform: Unix 6 :synopsis: GNU's reinterpretation of dbm. 7 8.. note:: 9 The :mod:`gdbm` module has been renamed to :mod:`dbm.gnu` in Python 3. The 10 :term:`2to3` tool will automatically adapt imports when converting your 11 sources to Python 3. 12 13 14.. index:: module: dbm 15 16This module is quite similar to the :mod:`dbm` module, but uses ``gdbm`` instead 17to provide some additional functionality. Please note that the file formats 18created by ``gdbm`` and ``dbm`` are incompatible. 19 20The :mod:`gdbm` module provides an interface to the GNU DBM library. ``gdbm`` 21objects behave like mappings (dictionaries), except that keys and values are 22always strings. Printing a ``gdbm`` object doesn't print the keys and values, 23and the :meth:`items` and :meth:`values` methods are not supported. 24 25The module defines the following constant and functions: 26 27 28.. exception:: error 29 30 Raised on ``gdbm``\ -specific errors, such as I/O errors. :exc:`KeyError` is 31 raised for general mapping errors like specifying an incorrect key. 32 33 34.. function:: open(filename, [flag, [mode]]) 35 36 Open a ``gdbm`` database and return a ``gdbm`` object. The *filename* argument 37 is the name of the database file. 38 39 The optional *flag* argument can be: 40 41 +---------+-------------------------------------------+ 42 | Value | Meaning | 43 +=========+===========================================+ 44 | ``'r'`` | Open existing database for reading only | 45 | | (default) | 46 +---------+-------------------------------------------+ 47 | ``'w'`` | Open existing database for reading and | 48 | | writing | 49 +---------+-------------------------------------------+ 50 | ``'c'`` | Open database for reading and writing, | 51 | | creating it if it doesn't exist | 52 +---------+-------------------------------------------+ 53 | ``'n'`` | Always create a new, empty database, open | 54 | | for reading and writing | 55 +---------+-------------------------------------------+ 56 57 The following additional characters may be appended to the flag to control 58 how the database is opened: 59 60 +---------+--------------------------------------------+ 61 | Value | Meaning | 62 +=========+============================================+ 63 | ``'f'`` | Open the database in fast mode. Writes | 64 | | to the database will not be synchronized. | 65 +---------+--------------------------------------------+ 66 | ``'s'`` | Synchronized mode. This will cause changes | 67 | | to the database to be immediately written | 68 | | to the file. | 69 +---------+--------------------------------------------+ 70 | ``'u'`` | Do not lock database. | 71 +---------+--------------------------------------------+ 72 73 Not all flags are valid for all versions of ``gdbm``. The module constant 74 :const:`open_flags` is a string of supported flag characters. The exception 75 :exc:`error` is raised if an invalid flag is specified. 76 77 The optional *mode* argument is the Unix mode of the file, used only when the 78 database has to be created. It defaults to octal ``0666``. 79 80In addition to the dictionary-like methods, ``gdbm`` objects have the following 81methods: 82 83 84.. function:: firstkey() 85 86 It's possible to loop over every key in the database using this method and the 87 :meth:`nextkey` method. The traversal is ordered by ``gdbm``'s internal hash 88 values, and won't be sorted by the key values. This method returns the starting 89 key. 90 91 92.. function:: nextkey(key) 93 94 Returns the key that follows *key* in the traversal. The following code prints 95 every key in the database ``db``, without having to create a list in memory that 96 contains them all:: 97 98 k = db.firstkey() 99 while k != None: 100 print k 101 k = db.nextkey(k) 102 103 104.. function:: reorganize() 105 106 If you have carried out a lot of deletions and would like to shrink the space 107 used by the ``gdbm`` file, this routine will reorganize the database. ``gdbm`` 108 will not shorten the length of a database file except by using this 109 reorganization; otherwise, deleted file space will be kept and reused as new 110 (key, value) pairs are added. 111 112 113.. function:: sync() 114 115 When the database has been opened in fast mode, this method forces any 116 unwritten data to be written to the disk. 117 118 119.. function:: close() 120 121 Close the ``gdbm`` database. 122 123 124.. seealso:: 125 126 Module :mod:`anydbm` 127 Generic interface to ``dbm``\ -style databases. 128 129 Module :mod:`whichdb` 130 Utility module used to determine the type of an existing database. 131 132