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 is not 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