1:mod:`dbm` --- Interfaces to Unix "databases"
2=============================================
3
4.. module:: dbm
5   :synopsis: Interfaces to various Unix "database" formats.
6
7**Source code:** :source:`Lib/dbm/__init__.py`
8
9--------------
10
11:mod:`dbm` is a generic interface to variants of the DBM database ---
12:mod:`dbm.gnu` or :mod:`dbm.ndbm`.  If none of these modules is installed, the
13slow-but-simple implementation in module :mod:`dbm.dumb` will be used.  There
14is a `third party interface <https://www.jcea.es/programacion/pybsddb.htm>`_ to
15the Oracle Berkeley DB.
16
17
18.. exception:: error
19
20   A tuple containing the exceptions that can be raised by each of the supported
21   modules, with a unique exception also named :exc:`dbm.error` as the first
22   item --- the latter is used when :exc:`dbm.error` is raised.
23
24
25.. function:: whichdb(filename)
26
27   This function attempts to guess which of the several simple database modules
28   available --- :mod:`dbm.gnu`, :mod:`dbm.ndbm` or :mod:`dbm.dumb` --- should
29   be used to open a given file.
30
31   Returns one of the following values: ``None`` if the file can't be opened
32   because it's unreadable or doesn't exist; the empty string (``''``) if the
33   file's format can't be guessed; or a string containing the required module
34   name, such as ``'dbm.ndbm'`` or ``'dbm.gnu'``.
35
36
37.. function:: open(file, flag='r', mode=0o666)
38
39   Open the database file *file* and return a corresponding object.
40
41   If the database file already exists, the :func:`whichdb` function is used to
42   determine its type and the appropriate module is used; if it does not exist,
43   the first module listed above that can be imported is used.
44
45   The optional *flag* argument can be:
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 ``0o666`` (and will be
65   modified by the prevailing umask).
66
67
68The object returned by :func:`.open` supports the same basic functionality as
69dictionaries; keys and their corresponding values can be stored, retrieved, and
70deleted, and the :keyword:`in` operator and the :meth:`keys` method are
71available, as well as :meth:`get` and :meth:`setdefault`.
72
73.. versionchanged:: 3.2
74   :meth:`get` and :meth:`setdefault` are now available in all database modules.
75
76.. versionchanged:: 3.8
77   Deleting a key from a read-only database raises database module specific error
78   instead of :exc:`KeyError`.
79
80Key and values are always stored as bytes. This means that when
81strings are used they are implicitly converted to the default encoding before
82being stored.
83
84These objects also support being used in a :keyword:`with` statement, which
85will automatically close them when done.
86
87.. versionchanged:: 3.4
88   Added native support for the context management protocol to the objects
89   returned by :func:`.open`.
90
91The following example records some hostnames and a corresponding title,  and
92then prints out the contents of the database::
93
94   import dbm
95
96   # Open database, creating it if necessary.
97   with dbm.open('cache', 'c') as db:
98
99       # Record some values
100       db[b'hello'] = b'there'
101       db['www.python.org'] = 'Python Website'
102       db['www.cnn.com'] = 'Cable News Network'
103
104       # Note that the keys are considered bytes now.
105       assert db[b'www.python.org'] == b'Python Website'
106       # Notice how the value is now in bytes.
107       assert db['www.cnn.com'] == b'Cable News Network'
108
109       # Often-used methods of the dict interface work too.
110       print(db.get('python.org', b'not present'))
111
112       # Storing a non-string key or value will raise an exception (most
113       # likely a TypeError).
114       db['www.yahoo.com'] = 4
115
116   # db is automatically closed when leaving the with statement.
117
118
119.. seealso::
120
121   Module :mod:`shelve`
122      Persistence module which stores non-string data.
123
124
125The individual submodules are described in the following sections.
126
127
128:mod:`dbm.gnu` --- GNU's reinterpretation of dbm
129------------------------------------------------
130
131.. module:: dbm.gnu
132   :platform: Unix
133   :synopsis: GNU's reinterpretation of dbm.
134
135**Source code:** :source:`Lib/dbm/gnu.py`
136
137--------------
138
139This module is quite similar to the :mod:`dbm` module, but uses the GNU library
140``gdbm`` instead to provide some additional functionality.  Please note that the
141file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are incompatible.
142
143The :mod:`dbm.gnu` module provides an interface to the GNU DBM library.
144``dbm.gnu.gdbm`` objects behave like mappings (dictionaries), except that keys and
145values are always converted to bytes before storing.  Printing a ``gdbm``
146object doesn't print the
147keys and values, and the :meth:`items` and :meth:`values` methods are not
148supported.
149
150.. exception:: error
151
152   Raised on :mod:`dbm.gnu`-specific errors, such as I/O errors. :exc:`KeyError` is
153   raised for general mapping errors like specifying an incorrect key.
154
155
156.. function:: open(filename[, flag[, mode]])
157
158   Open a ``gdbm`` database and return a :class:`gdbm` object.  The *filename*
159   argument is the name of the database file.
160
161   The optional *flag* argument can be:
162
163   +---------+-------------------------------------------+
164   | Value   | Meaning                                   |
165   +=========+===========================================+
166   | ``'r'`` | Open existing database for reading only   |
167   |         | (default)                                 |
168   +---------+-------------------------------------------+
169   | ``'w'`` | Open existing database for reading and    |
170   |         | writing                                   |
171   +---------+-------------------------------------------+
172   | ``'c'`` | Open database for reading and writing,    |
173   |         | creating it if it doesn't exist           |
174   +---------+-------------------------------------------+
175   | ``'n'`` | Always create a new, empty database, open |
176   |         | for reading and writing                   |
177   +---------+-------------------------------------------+
178
179   The following additional characters may be appended to the flag to control
180   how the database is opened:
181
182   +---------+--------------------------------------------+
183   | Value   | Meaning                                    |
184   +=========+============================================+
185   | ``'f'`` | Open the database in fast mode.  Writes    |
186   |         | to the database will not be synchronized.  |
187   +---------+--------------------------------------------+
188   | ``'s'`` | Synchronized mode. This will cause changes |
189   |         | to the database to be immediately written  |
190   |         | to the file.                               |
191   +---------+--------------------------------------------+
192   | ``'u'`` | Do not lock database.                      |
193   +---------+--------------------------------------------+
194
195   Not all flags are valid for all versions of ``gdbm``.  The module constant
196   :const:`open_flags` is a string of supported flag characters.  The exception
197   :exc:`error` is raised if an invalid flag is specified.
198
199   The optional *mode* argument is the Unix mode of the file, used only when the
200   database has to be created.  It defaults to octal ``0o666``.
201
202   In addition to the dictionary-like methods, ``gdbm`` objects have the
203   following methods:
204
205   .. method:: gdbm.firstkey()
206
207      It's possible to loop over every key in the database using this method  and the
208      :meth:`nextkey` method.  The traversal is ordered by ``gdbm``'s internal
209      hash values, and won't be sorted by the key values.  This method returns
210      the starting key.
211
212   .. method:: gdbm.nextkey(key)
213
214      Returns the key that follows *key* in the traversal.  The following code prints
215      every key in the database ``db``, without having to create a list in memory that
216      contains them all::
217
218         k = db.firstkey()
219         while k != None:
220             print(k)
221             k = db.nextkey(k)
222
223   .. method:: gdbm.reorganize()
224
225      If you have carried out a lot of deletions and would like to shrink the space
226      used by the ``gdbm`` file, this routine will reorganize the database.  ``gdbm``
227      objects will not shorten the length of a database file except by using this
228      reorganization; otherwise, deleted file space will be kept and reused as new
229      (key, value) pairs are added.
230
231   .. method:: gdbm.sync()
232
233      When the database has been opened in fast mode, this method forces any
234      unwritten data to be written to the disk.
235
236   .. method:: gdbm.close()
237
238      Close the ``gdbm`` database.
239
240:mod:`dbm.ndbm` --- Interface based on ndbm
241-------------------------------------------
242
243.. module:: dbm.ndbm
244   :platform: Unix
245   :synopsis: The standard "database" interface, based on ndbm.
246
247**Source code:** :source:`Lib/dbm/ndbm.py`
248
249--------------
250
251The :mod:`dbm.ndbm` module provides an interface to the Unix "(n)dbm" library.
252Dbm objects behave like mappings (dictionaries), except that keys and values are
253always stored as bytes. Printing a ``dbm`` object doesn't print the keys and
254values, and the :meth:`items` and :meth:`values` methods are not supported.
255
256This module can be used with the "classic" ndbm interface or the GNU GDBM
257compatibility interface. On Unix, the :program:`configure` script will attempt
258to locate the appropriate header file to simplify building this module.
259
260.. exception:: error
261
262   Raised on :mod:`dbm.ndbm`-specific errors, such as I/O errors. :exc:`KeyError` is raised
263   for general mapping errors like specifying an incorrect key.
264
265
266.. data:: library
267
268   Name of the ``ndbm`` implementation library used.
269
270
271.. function:: open(filename[, flag[, mode]])
272
273   Open a dbm database and return a ``ndbm`` object.  The *filename* argument is the
274   name of the database file (without the :file:`.dir` or :file:`.pag` extensions).
275
276   The optional *flag* argument must be one of these values:
277
278   +---------+-------------------------------------------+
279   | Value   | Meaning                                   |
280   +=========+===========================================+
281   | ``'r'`` | Open existing database for reading only   |
282   |         | (default)                                 |
283   +---------+-------------------------------------------+
284   | ``'w'`` | Open existing database for reading and    |
285   |         | writing                                   |
286   +---------+-------------------------------------------+
287   | ``'c'`` | Open database for reading and writing,    |
288   |         | creating it if it doesn't exist           |
289   +---------+-------------------------------------------+
290   | ``'n'`` | Always create a new, empty database, open |
291   |         | for reading and writing                   |
292   +---------+-------------------------------------------+
293
294   The optional *mode* argument is the Unix mode of the file, used only when the
295   database has to be created.  It defaults to octal ``0o666`` (and will be
296   modified by the prevailing umask).
297
298   In addition to the dictionary-like methods, ``ndbm`` objects
299   provide the following method:
300
301   .. method:: ndbm.close()
302
303      Close the ``ndbm`` database.
304
305
306:mod:`dbm.dumb` --- Portable DBM implementation
307-----------------------------------------------
308
309.. module:: dbm.dumb
310   :synopsis: Portable implementation of the simple DBM interface.
311
312**Source code:** :source:`Lib/dbm/dumb.py`
313
314.. index:: single: databases
315
316.. note::
317
318   The :mod:`dbm.dumb` module is intended as a last resort fallback for the
319   :mod:`dbm` module when a more robust module is not available. The :mod:`dbm.dumb`
320   module is not written for speed and is not nearly as heavily used as the other
321   database modules.
322
323--------------
324
325The :mod:`dbm.dumb` module provides a persistent dictionary-like interface which
326is written entirely in Python.  Unlike other modules such as :mod:`dbm.gnu` no
327external library is required.  As with other persistent mappings, the keys and
328values are always stored as bytes.
329
330The module defines the following:
331
332
333.. exception:: error
334
335   Raised on :mod:`dbm.dumb`-specific errors, such as I/O errors.  :exc:`KeyError` is
336   raised for general mapping errors like specifying an incorrect key.
337
338
339.. function:: open(filename[, flag[, mode]])
340
341   Open a ``dumbdbm`` database and return a dumbdbm object.  The *filename* argument is
342   the basename of the database file (without any specific extensions).  When a
343   dumbdbm database is created, files with :file:`.dat` and :file:`.dir` extensions
344   are created.
345
346   The optional *flag* argument can be:
347
348   +---------+-------------------------------------------+
349   | Value   | Meaning                                   |
350   +=========+===========================================+
351   | ``'r'`` | Open existing database for reading only   |
352   |         | (default)                                 |
353   +---------+-------------------------------------------+
354   | ``'w'`` | Open existing database for reading and    |
355   |         | writing                                   |
356   +---------+-------------------------------------------+
357   | ``'c'`` | Open database for reading and writing,    |
358   |         | creating it if it doesn't exist           |
359   +---------+-------------------------------------------+
360   | ``'n'`` | Always create a new, empty database, open |
361   |         | for reading and writing                   |
362   +---------+-------------------------------------------+
363
364   The optional *mode* argument is the Unix mode of the file, used only when the
365   database has to be created.  It defaults to octal ``0o666`` (and will be modified
366   by the prevailing umask).
367
368   .. warning::
369      It is possible to crash the Python interpreter when loading a database
370      with a sufficiently large/complex entry due to stack depth limitations in
371      Python's AST compiler.
372
373   .. versionchanged:: 3.5
374      :func:`.open` always creates a new database when the flag has the value
375      ``'n'``.
376
377   .. versionchanged:: 3.8
378      A database opened with flags ``'r'`` is now read-only.  Opening with
379      flags ``'r'`` and ``'w'`` no longer creates a database if it does not
380      exist.
381
382   In addition to the methods provided by the
383   :class:`collections.abc.MutableMapping` class, :class:`dumbdbm` objects
384   provide the following methods:
385
386   .. method:: dumbdbm.sync()
387
388      Synchronize the on-disk directory and data files.  This method is called
389      by the :meth:`Shelve.sync` method.
390
391   .. method:: dumbdbm.close()
392
393      Close the ``dumbdbm`` database.
394
395