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