• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1:mod:`dbm` --- Simple "database" interface
2==========================================
3
4.. module:: dbm
5   :platform: Unix
6   :synopsis: The standard "database" interface, based on ndbm.
7
8.. note::
9   The :mod:`dbm` module has been renamed to :mod:`dbm.ndbm` in Python 3.  The
10   :term:`2to3` tool will automatically adapt imports when converting your
11   sources to Python 3.
12
13
14The :mod:`dbm` module provides an interface to the Unix "(n)dbm" library.  Dbm
15objects behave like mappings (dictionaries), except that keys and values are
16always strings. Printing a dbm object doesn't print the keys and values, and the
17:meth:`items` and :meth:`values` methods are not supported.
18
19This module can be used with the "classic" ndbm interface, the BSD DB
20compatibility interface, or the GNU GDBM compatibility interface. On Unix, the
21:program:`configure` script will attempt to locate the appropriate header file
22to simplify building this module.
23
24The module defines the following:
25
26
27.. exception:: error
28
29   Raised on dbm-specific errors, such as I/O errors. :exc:`KeyError` is raised for
30   general mapping errors like specifying an incorrect key.
31
32
33.. data:: library
34
35   Name of the ``ndbm`` implementation library used.
36
37
38.. function:: open(filename[, flag[, mode]])
39
40   Open a dbm database and return a dbm object.  The *filename* argument is the
41   name of the database file (without the :file:`.dir` or :file:`.pag` extensions;
42   note that the BSD DB implementation of the interface will append the extension
43   :file:`.db` and only create one file).
44
45   The optional *flag* argument must be one of these values:
46
47   +---------+-------------------------------------------+
48   | Value   | Meaning                                   |
49   +=========+===========================================+
50   | ``'r'`` | Open existing database for reading only   |
51   |         | (default)                                 |
52   +---------+-------------------------------------------+
53   | ``'w'`` | Open existing database for reading and    |
54   |         | writing                                   |
55   +---------+-------------------------------------------+
56   | ``'c'`` | Open database for reading and writing,    |
57   |         | creating it if it doesn't exist           |
58   +---------+-------------------------------------------+
59   | ``'n'`` | Always create a new, empty database, open |
60   |         | for reading and writing                   |
61   +---------+-------------------------------------------+
62
63   The optional *mode* argument is the Unix mode of the file, used only when the
64   database has to be created.  It defaults to octal ``0666`` (and will be
65   modified by the prevailing umask).
66
67   In addition to the dictionary-like methods, ``dbm`` objects
68   provide the following method:
69
70
71   .. function:: close()
72
73      Close the ``dbm`` database.
74
75
76.. seealso::
77
78   Module :mod:`anydbm`
79      Generic interface to ``dbm``\ -style databases.
80
81   Module :mod:`gdbm`
82      Similar interface to the GNU GDBM library.
83
84   Module :mod:`whichdb`
85      Utility module used to determine the type of an existing database.
86
87