Home | History | Annotate | Download | only in library 
      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 
     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 .. 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