/Doc/library/gdbm.rst

  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.0.  The
 10   :term:`2to3` tool will automatically adapt imports when converting your
 11   sources to 3.0.
 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.. seealso::
120
121   Module :mod:`anydbm`
122      Generic interface to ``dbm``\ -style databases.
123
124   Module :mod:`whichdb`
125      Utility module used to determine the type of an existing database.
126