blob: 3f3c43d4383fba51737b821ee41537c199b7c793 [file] [log] [blame]
Georg Brandl0a7ac7d2008-05-26 10:29:35 +00001:mod:`dbm` --- Interfaces to Unix "databases"
2=============================================
Georg Brandl116aa622007-08-15 14:28:22 +00003
4.. module:: dbm
Georg Brandl0a7ac7d2008-05-26 10:29:35 +00005 :synopsis: Interfaces to various Unix "database" formats.
6
7:mod:`dbm` is a generic interface to variants of the DBM database ---
Georg Brandlac958ce2010-07-29 14:46:07 +00008:mod:`dbm.gnu` or :mod:`dbm.ndbm`. If none of these modules is installed, the
9slow-but-simple implementation in module :mod:`dbm.dumb` will be used. There
10is a `third party interface <http://www.jcea.es/programacion/pybsddb.htm>`_ to
Georg Brandlbb190152010-07-31 21:41:42 +000011the Oracle Berkeley DB.
Georg Brandl0a7ac7d2008-05-26 10:29:35 +000012
13
14.. exception:: error
15
16 A tuple containing the exceptions that can be raised by each of the supported
17 modules, with a unique exception also named :exc:`dbm.error` as the first
18 item --- the latter is used when :exc:`dbm.error` is raised.
19
20
21.. function:: whichdb(filename)
22
Georg Brandle8b0d612010-12-04 09:04:04 +000023 This function attempts to guess which of the several simple database modules
Georg Brandlac958ce2010-07-29 14:46:07 +000024 available --- :mod:`dbm.gnu`, :mod:`dbm.ndbm` or :mod:`dbm.dumb` --- should
25 be used to open a given file.
Georg Brandl0a7ac7d2008-05-26 10:29:35 +000026
27 Returns one of the following values: ``None`` if the file can't be opened
28 because it's unreadable or doesn't exist; the empty string (``''``) if the
29 file's format can't be guessed; or a string containing the required module
30 name, such as ``'dbm.ndbm'`` or ``'dbm.gnu'``.
31
32
Éric Araujo5c1a0c92011-04-20 19:11:12 +020033.. function:: open(file, flag='r', mode=0o666)
Georg Brandl0a7ac7d2008-05-26 10:29:35 +000034
Éric Araujo5c1a0c92011-04-20 19:11:12 +020035 Open the database file *file* and return a corresponding object.
Georg Brandl0a7ac7d2008-05-26 10:29:35 +000036
37 If the database file already exists, the :func:`whichdb` function is used to
38 determine its type and the appropriate module is used; if it does not exist,
39 the first module listed above that can be imported is used.
40
Georg Brandl1a040582009-05-25 21:15:01 +000041 The optional *flag* argument can be:
42
43 +---------+-------------------------------------------+
44 | Value | Meaning |
45 +=========+===========================================+
46 | ``'r'`` | Open existing database for reading only |
47 | | (default) |
48 +---------+-------------------------------------------+
49 | ``'w'`` | Open existing database for reading and |
50 | | writing |
51 +---------+-------------------------------------------+
52 | ``'c'`` | Open database for reading and writing, |
53 | | creating it if it doesn't exist |
54 +---------+-------------------------------------------+
55 | ``'n'`` | Always create a new, empty database, open |
56 | | for reading and writing |
57 +---------+-------------------------------------------+
Georg Brandl0a7ac7d2008-05-26 10:29:35 +000058
59 The optional *mode* argument is the Unix mode of the file, used only when the
60 database has to be created. It defaults to octal ``0o666`` (and will be
61 modified by the prevailing umask).
62
63
Georg Brandld9e833c2010-12-04 09:14:36 +000064The object returned by :func:`.open` supports the same basic functionality as
Georg Brandl0a7ac7d2008-05-26 10:29:35 +000065dictionaries; keys and their corresponding values can be stored, retrieved, and
66deleted, and the :keyword:`in` operator and the :meth:`keys` method are
Georg Brandld9e833c2010-12-04 09:14:36 +000067available, as well as :meth:`get` and :meth:`setdefault`.
68
69.. versionchanged:: 3.2
70 :meth:`get` and :meth:`setdefault` are now available in all database modules.
71
72Key and values are always stored as bytes. This means that when
Brett Cannon7317c1e2008-11-25 19:19:17 +000073strings are used they are implicitly converted to the default encoding before
74being stored.
Georg Brandl0a7ac7d2008-05-26 10:29:35 +000075
Nick Coghlanc610aba2013-11-17 15:59:51 +100076These objects also support being used in a :keyword:`with` statement, which
77will automatically close them when done.
78
79.. versionchanged:: 3.4
80 Added native support for the context management protocol to the objects
81 returned by :func:`.open`.
82
Georg Brandl0a7ac7d2008-05-26 10:29:35 +000083The following example records some hostnames and a corresponding title, and
84then prints out the contents of the database::
85
86 import dbm
87
88 # Open database, creating it if necessary.
Nick Coghlanc610aba2013-11-17 15:59:51 +100089 with dbm.open('cache', 'c') as db:
Georg Brandl0a7ac7d2008-05-26 10:29:35 +000090
Nick Coghlanc610aba2013-11-17 15:59:51 +100091 # Record some values
92 db[b'hello'] = b'there'
93 db['www.python.org'] = 'Python Website'
94 db['www.cnn.com'] = 'Cable News Network'
Georg Brandl0a7ac7d2008-05-26 10:29:35 +000095
Nick Coghlanc610aba2013-11-17 15:59:51 +100096 # Note that the keys are considered bytes now.
97 assert db[b'www.python.org'] == b'Python Website'
98 # Notice how the value is now in bytes.
99 assert db['www.cnn.com'] == b'Cable News Network'
Brett Cannon7317c1e2008-11-25 19:19:17 +0000100
Nick Coghlanc610aba2013-11-17 15:59:51 +1000101 # Often-used methods of the dict interface work too.
102 print(db.get('python.org', b'not present'))
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000103
Nick Coghlanc610aba2013-11-17 15:59:51 +1000104 # Storing a non-string key or value will raise an exception (most
105 # likely a TypeError).
106 db['www.yahoo.com'] = 4
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000107
Nick Coghlanc610aba2013-11-17 15:59:51 +1000108 # db is automatically closed when leaving the with statement.
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000109
110
111.. seealso::
112
113 Module :mod:`shelve`
114 Persistence module which stores non-string data.
115
116
117The individual submodules are described in the following sections.
118
119
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000120:mod:`dbm.gnu` --- GNU's reinterpretation of dbm
121------------------------------------------------
122
123.. module:: dbm.gnu
124 :platform: Unix
125 :synopsis: GNU's reinterpretation of dbm.
126
127
128This module is quite similar to the :mod:`dbm` module, but uses the GNU library
129``gdbm`` instead to provide some additional functionality. Please note that the
Brett Cannon7317c1e2008-11-25 19:19:17 +0000130file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are incompatible.
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000131
132The :mod:`dbm.gnu` module provides an interface to the GNU DBM library.
Brett Cannon7317c1e2008-11-25 19:19:17 +0000133``dbm.gnu.gdbm`` objects behave like mappings (dictionaries), except that keys and
134values are always converted to bytes before storing. Printing a ``gdbm``
135object doesn't print the
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000136keys and values, and the :meth:`items` and :meth:`values` methods are not
137supported.
138
139.. exception:: error
140
Brett Cannon7317c1e2008-11-25 19:19:17 +0000141 Raised on :mod:`dbm.gnu`-specific errors, such as I/O errors. :exc:`KeyError` is
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000142 raised for general mapping errors like specifying an incorrect key.
143
144
Georg Brandlc2a4f4f2009-04-10 09:03:43 +0000145.. function:: open(filename[, flag[, mode]])
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000146
147 Open a ``gdbm`` database and return a :class:`gdbm` object. The *filename*
148 argument is the name of the database file.
149
150 The optional *flag* argument can be:
151
152 +---------+-------------------------------------------+
153 | Value | Meaning |
154 +=========+===========================================+
155 | ``'r'`` | Open existing database for reading only |
156 | | (default) |
157 +---------+-------------------------------------------+
158 | ``'w'`` | Open existing database for reading and |
159 | | writing |
160 +---------+-------------------------------------------+
161 | ``'c'`` | Open database for reading and writing, |
162 | | creating it if it doesn't exist |
163 +---------+-------------------------------------------+
164 | ``'n'`` | Always create a new, empty database, open |
165 | | for reading and writing |
166 +---------+-------------------------------------------+
167
168 The following additional characters may be appended to the flag to control
169 how the database is opened:
170
171 +---------+--------------------------------------------+
172 | Value | Meaning |
173 +=========+============================================+
174 | ``'f'`` | Open the database in fast mode. Writes |
175 | | to the database will not be synchronized. |
176 +---------+--------------------------------------------+
177 | ``'s'`` | Synchronized mode. This will cause changes |
178 | | to the database to be immediately written |
179 | | to the file. |
180 +---------+--------------------------------------------+
181 | ``'u'`` | Do not lock database. |
182 +---------+--------------------------------------------+
183
184 Not all flags are valid for all versions of ``gdbm``. The module constant
185 :const:`open_flags` is a string of supported flag characters. The exception
186 :exc:`error` is raised if an invalid flag is specified.
187
188 The optional *mode* argument is the Unix mode of the file, used only when the
Georg Brandlf4a41232008-05-26 17:55:52 +0000189 database has to be created. It defaults to octal ``0o666``.
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000190
191 In addition to the dictionary-like methods, ``gdbm`` objects have the
192 following methods:
193
194 .. method:: gdbm.firstkey()
195
196 It's possible to loop over every key in the database using this method and the
197 :meth:`nextkey` method. The traversal is ordered by ``gdbm``'s internal
198 hash values, and won't be sorted by the key values. This method returns
199 the starting key.
200
201 .. method:: gdbm.nextkey(key)
202
203 Returns the key that follows *key* in the traversal. The following code prints
204 every key in the database ``db``, without having to create a list in memory that
205 contains them all::
206
207 k = db.firstkey()
208 while k != None:
209 print(k)
210 k = db.nextkey(k)
211
212 .. method:: gdbm.reorganize()
213
214 If you have carried out a lot of deletions and would like to shrink the space
215 used by the ``gdbm`` file, this routine will reorganize the database. ``gdbm``
Brett Cannon7317c1e2008-11-25 19:19:17 +0000216 objects will not shorten the length of a database file except by using this
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000217 reorganization; otherwise, deleted file space will be kept and reused as new
218 (key, value) pairs are added.
219
220 .. method:: gdbm.sync()
221
222 When the database has been opened in fast mode, this method forces any
223 unwritten data to be written to the disk.
224
Jesus Ceaac4b7f72014-06-25 13:05:31 +0200225 .. method:: gdbm.close()
226
227 Close the ``gdbm`` database.
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000228
229:mod:`dbm.ndbm` --- Interface based on ndbm
230-------------------------------------------
231
232.. module:: dbm.ndbm
Georg Brandl116aa622007-08-15 14:28:22 +0000233 :platform: Unix
234 :synopsis: The standard "database" interface, based on ndbm.
235
236
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000237The :mod:`dbm.ndbm` module provides an interface to the Unix "(n)dbm" library.
238Dbm objects behave like mappings (dictionaries), except that keys and values are
Brett Cannon7317c1e2008-11-25 19:19:17 +0000239always stored as bytes. Printing a ``dbm`` object doesn't print the keys and
240values, and the :meth:`items` and :meth:`values` methods are not supported.
Georg Brandl116aa622007-08-15 14:28:22 +0000241
Georg Brandlac958ce2010-07-29 14:46:07 +0000242This module can be used with the "classic" ndbm interface or the GNU GDBM
243compatibility interface. On Unix, the :program:`configure` script will attempt
244to locate the appropriate header file to simplify building this module.
Georg Brandl116aa622007-08-15 14:28:22 +0000245
Georg Brandl116aa622007-08-15 14:28:22 +0000246.. exception:: error
247
Brett Cannon7317c1e2008-11-25 19:19:17 +0000248 Raised on :mod:`dbm.ndbm`-specific errors, such as I/O errors. :exc:`KeyError` is raised
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000249 for general mapping errors like specifying an incorrect key.
Georg Brandl116aa622007-08-15 14:28:22 +0000250
251
252.. data:: library
253
254 Name of the ``ndbm`` implementation library used.
255
256
257.. function:: open(filename[, flag[, mode]])
258
Jesus Ceaac4b7f72014-06-25 13:05:31 +0200259 Open a dbm database and return a ``ndbm`` object. The *filename* argument is the
Georg Brandlac958ce2010-07-29 14:46:07 +0000260 name of the database file (without the :file:`.dir` or :file:`.pag` extensions).
Georg Brandl116aa622007-08-15 14:28:22 +0000261
262 The optional *flag* argument must be one of these values:
263
264 +---------+-------------------------------------------+
265 | Value | Meaning |
266 +=========+===========================================+
267 | ``'r'`` | Open existing database for reading only |
268 | | (default) |
269 +---------+-------------------------------------------+
270 | ``'w'`` | Open existing database for reading and |
271 | | writing |
272 +---------+-------------------------------------------+
273 | ``'c'`` | Open database for reading and writing, |
274 | | creating it if it doesn't exist |
275 +---------+-------------------------------------------+
276 | ``'n'`` | Always create a new, empty database, open |
277 | | for reading and writing |
278 +---------+-------------------------------------------+
279
280 The optional *mode* argument is the Unix mode of the file, used only when the
Georg Brandlf4a41232008-05-26 17:55:52 +0000281 database has to be created. It defaults to octal ``0o666`` (and will be
Georg Brandl116aa622007-08-15 14:28:22 +0000282 modified by the prevailing umask).
283
Jesus Ceaac4b7f72014-06-25 13:05:31 +0200284 In addition to the dictionary-like methods, ``ndbm`` objects
285 provide the following method:
286
287 .. method:: ndbm.close()
288
289 Close the ``ndbm`` database.
Georg Brandl116aa622007-08-15 14:28:22 +0000290
Georg Brandl116aa622007-08-15 14:28:22 +0000291
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000292:mod:`dbm.dumb` --- Portable DBM implementation
293-----------------------------------------------
Georg Brandl116aa622007-08-15 14:28:22 +0000294
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000295.. module:: dbm.dumb
296 :synopsis: Portable implementation of the simple DBM interface.
Georg Brandl116aa622007-08-15 14:28:22 +0000297
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000298.. index:: single: databases
Georg Brandl116aa622007-08-15 14:28:22 +0000299
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000300.. note::
301
302 The :mod:`dbm.dumb` module is intended as a last resort fallback for the
Brett Cannon7317c1e2008-11-25 19:19:17 +0000303 :mod:`dbm` module when a more robust module is not available. The :mod:`dbm.dumb`
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000304 module is not written for speed and is not nearly as heavily used as the other
305 database modules.
306
307The :mod:`dbm.dumb` module provides a persistent dictionary-like interface which
Brett Cannon7317c1e2008-11-25 19:19:17 +0000308is written entirely in Python. Unlike other modules such as :mod:`dbm.gnu` no
Benjamin Peterson9a46cab2008-09-08 02:49:30 +0000309external library is required. As with other persistent mappings, the keys and
Brett Cannon7317c1e2008-11-25 19:19:17 +0000310values are always stored as bytes.
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000311
312The module defines the following:
313
314
315.. exception:: error
316
Brett Cannon7317c1e2008-11-25 19:19:17 +0000317 Raised on :mod:`dbm.dumb`-specific errors, such as I/O errors. :exc:`KeyError` is
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000318 raised for general mapping errors like specifying an incorrect key.
319
320
321.. function:: open(filename[, flag[, mode]])
322
Brett Cannon7317c1e2008-11-25 19:19:17 +0000323 Open a ``dumbdbm`` database and return a dumbdbm object. The *filename* argument is
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000324 the basename of the database file (without any specific extensions). When a
325 dumbdbm database is created, files with :file:`.dat` and :file:`.dir` extensions
326 are created.
327
Serhiy Storchakab398d332014-06-10 21:16:00 +0300328 The optional *flag* argument supports only the semantics of ``'c'``
329 and ``'n'`` values. Other values will default to database being always
330 opened for update, and will be created if it does not exist.
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000331
332 The optional *mode* argument is the Unix mode of the file, used only when the
333 database has to be created. It defaults to octal ``0o666`` (and will be modified
334 by the prevailing umask).
335
Serhiy Storchakab398d332014-06-10 21:16:00 +0300336 .. versionchanged:: 3.5
337 :func:`.open` always creates a new database when the flag has the value
338 ``'n'``.
339
Serhiy Storchakabfdcd432013-10-13 23:09:14 +0300340 In addition to the methods provided by the
341 :class:`collections.abc.MutableMapping` class, :class:`dumbdbm` objects
Jesus Ceaac4b7f72014-06-25 13:05:31 +0200342 provide the following methods:
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000343
344 .. method:: dumbdbm.sync()
345
346 Synchronize the on-disk directory and data files. This method is called
347 by the :meth:`Shelve.sync` method.
Jesus Ceaac4b7f72014-06-25 13:05:31 +0200348
349 .. method:: dumbdbm.close()
350
351 Close the ``dumbdbm`` database.
352