l4/pkg/python/contrib/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
  16 This module is quite similar to the :mod:`dbm` module, but uses ``gdbm`` instead
  17 to provide some additional functionality.  Please note that the file formats
  18 created by ``gdbm`` and ``dbm`` are incompatible.
  19
  20 The :mod:`gdbm` module provides an interface to the GNU DBM library.  ``gdbm``
  21 objects behave like mappings (dictionaries), except that keys and values are
  22 always strings. Printing a ``gdbm`` object doesn't print the keys and values,
  23 and the :meth:`items` and :meth:`values` methods are not supported.
  24
  25 The 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
  80 In addition to the dictionary-like methods, ``gdbm`` objects have the following
  81 methods:
  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