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