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 13* :mod:`dbm.sqlite3` 14* :mod:`dbm.gnu` 15* :mod:`dbm.ndbm` 16 17If none of these modules are installed, the 18slow-but-simple implementation in module :mod:`dbm.dumb` will be used. There 19is a `third party interface <https://www.jcea.es/programacion/pybsddb.htm>`_ to 20the Oracle Berkeley DB. 21 22.. exception:: error 23 24 A tuple containing the exceptions that can be raised by each of the supported 25 modules, with a unique exception also named :exc:`dbm.error` as the first 26 item --- the latter is used when :exc:`dbm.error` is raised. 27 28 29.. function:: whichdb(filename) 30 31 This function attempts to guess which of the several simple database modules 32 available --- :mod:`dbm.sqlite3`, :mod:`dbm.gnu`, :mod:`dbm.ndbm`, 33 or :mod:`dbm.dumb` --- should be used to open a given file. 34 35 Return one of the following values: 36 37 * ``None`` if the file can't be opened because it's unreadable or doesn't exist 38 * the empty string (``''``) if the file's format can't be guessed 39 * a string containing the required module name, such as ``'dbm.ndbm'`` or ``'dbm.gnu'`` 40 41 .. versionchanged:: 3.11 42 *filename* accepts a :term:`path-like object`. 43 44.. Substitutions for the open() flag param docs; 45 all submodules use the same text. 46 47.. |flag_r| replace:: 48 Open existing database for reading only. 49 50.. |flag_w| replace:: 51 Open existing database for reading and writing. 52 53.. |flag_c| replace:: 54 Open database for reading and writing, creating it if it doesn't exist. 55 56.. |flag_n| replace:: 57 Always create a new, empty database, open for reading and writing. 58 59.. |mode_param_doc| replace:: 60 The Unix file access mode of the file (default: octal ``0o666``), 61 used only when the database has to be created. 62 63.. function:: open(file, flag='r', mode=0o666) 64 65 Open a database and return the corresponding database object. 66 67 :param file: 68 The database file to open. 69 70 If the database file already exists, the :func:`whichdb` function is used to 71 determine its type and the appropriate module is used; if it does not exist, 72 the first submodule listed above that can be imported is used. 73 :type file: :term:`path-like object` 74 75 :param str flag: 76 * ``'r'`` (default): |flag_r| 77 * ``'w'``: |flag_w| 78 * ``'c'``: |flag_c| 79 * ``'n'``: |flag_n| 80 81 :param int mode: 82 |mode_param_doc| 83 84 .. versionchanged:: 3.11 85 *file* accepts a :term:`path-like object`. 86 87The object returned by :func:`~dbm.open` supports the same basic functionality as a 88:class:`dict`; keys and their corresponding values can be stored, retrieved, and 89deleted, and the :keyword:`in` operator and the :meth:`!keys` method are 90available, as well as :meth:`!get` and :meth:`!setdefault` methods. 91 92Key and values are always stored as :class:`bytes`. This means that when 93strings are used they are implicitly converted to the default encoding before 94being stored. 95 96These objects also support being used in a :keyword:`with` statement, which 97will automatically close them when done. 98 99.. versionchanged:: 3.2 100 :meth:`!get` and :meth:`!setdefault` methods are now available for all 101 :mod:`dbm` backends. 102 103.. versionchanged:: 3.4 104 Added native support for the context management protocol to the objects 105 returned by :func:`~dbm.open`. 106 107.. versionchanged:: 3.8 108 Deleting a key from a read-only database raises a database module specific exception 109 instead of :exc:`KeyError`. 110 111The following example records some hostnames and a corresponding title, and 112then prints out the contents of the database:: 113 114 import dbm 115 116 # Open database, creating it if necessary. 117 with dbm.open('cache', 'c') as db: 118 119 # Record some values 120 db[b'hello'] = b'there' 121 db['www.python.org'] = 'Python Website' 122 db['www.cnn.com'] = 'Cable News Network' 123 124 # Note that the keys are considered bytes now. 125 assert db[b'www.python.org'] == b'Python Website' 126 # Notice how the value is now in bytes. 127 assert db['www.cnn.com'] == b'Cable News Network' 128 129 # Often-used methods of the dict interface work too. 130 print(db.get('python.org', b'not present')) 131 132 # Storing a non-string key or value will raise an exception (most 133 # likely a TypeError). 134 db['www.yahoo.com'] = 4 135 136 # db is automatically closed when leaving the with statement. 137 138 139.. seealso:: 140 141 Module :mod:`shelve` 142 Persistence module which stores non-string data. 143 144 145The individual submodules are described in the following sections. 146 147:mod:`dbm.sqlite3` --- SQLite backend for dbm 148--------------------------------------------- 149 150.. module:: dbm.sqlite3 151 :platform: All 152 :synopsis: SQLite backend for dbm 153 154.. versionadded:: 3.13 155 156**Source code:** :source:`Lib/dbm/sqlite3.py` 157 158-------------- 159 160This module uses the standard library :mod:`sqlite3` module to provide an 161SQLite backend for the :mod:`dbm` module. 162The files created by :mod:`dbm.sqlite3` can thus be opened by :mod:`sqlite3`, 163or any other SQLite browser, including the SQLite CLI. 164 165.. include:: ../includes/wasm-notavail.rst 166 167.. function:: open(filename, /, flag="r", mode=0o666) 168 169 Open an SQLite database. 170 The returned object behaves like a :term:`mapping`, 171 implements a :meth:`!close` method, 172 and supports a "closing" context manager via the :keyword:`with` keyword. 173 174 :param filename: 175 The path to the database to be opened. 176 :type filename: :term:`path-like object` 177 178 :param str flag: 179 180 * ``'r'`` (default): |flag_r| 181 * ``'w'``: |flag_w| 182 * ``'c'``: |flag_c| 183 * ``'n'``: |flag_n| 184 185 :param mode: 186 The Unix file access mode of the file (default: octal ``0o666``), 187 used only when the database has to be created. 188 189 190:mod:`dbm.gnu` --- GNU database manager 191--------------------------------------- 192 193.. module:: dbm.gnu 194 :platform: Unix 195 :synopsis: GNU database manager 196 197**Source code:** :source:`Lib/dbm/gnu.py` 198 199-------------- 200 201The :mod:`dbm.gnu` module provides an interface to the :abbr:`GDBM (GNU dbm)` 202library, similar to the :mod:`dbm.ndbm` module, but with additional 203functionality like crash tolerance. 204 205.. note:: 206 207 The file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are incompatible 208 and can not be used interchangeably. 209 210.. include:: ../includes/wasm-mobile-notavail.rst 211 212.. exception:: error 213 214 Raised on :mod:`dbm.gnu`-specific errors, such as I/O errors. :exc:`KeyError` is 215 raised for general mapping errors like specifying an incorrect key. 216 217 218.. function:: open(filename, flag="r", mode=0o666, /) 219 220 Open a GDBM database and return a :class:`!gdbm` object. 221 222 :param filename: 223 The database file to open. 224 :type filename: :term:`path-like object` 225 226 :param str flag: 227 * ``'r'`` (default): |flag_r| 228 * ``'w'``: |flag_w| 229 * ``'c'``: |flag_c| 230 * ``'n'``: |flag_n| 231 232 The following additional characters may be appended 233 to control how the database is opened: 234 235 * ``'f'``: Open the database in fast mode. 236 Writes to the database will not be synchronized. 237 * ``'s'``: Synchronized mode. 238 Changes to the database will be written immediately to the file. 239 * ``'u'``: Do not lock database. 240 241 Not all flags are valid for all versions of GDBM. 242 See the :data:`open_flags` member for a list of supported flag characters. 243 244 :param int mode: 245 |mode_param_doc| 246 247 :raises error: 248 If an invalid *flag* argument is passed. 249 250 .. versionchanged:: 3.11 251 *filename* accepts a :term:`path-like object`. 252 253 .. data:: open_flags 254 255 A string of characters the *flag* parameter of :meth:`~dbm.gnu.open` supports. 256 257 :class:`!gdbm` objects behave similar to :term:`mappings <mapping>`, 258 but :meth:`!items` and :meth:`!values` methods are not supported. 259 The following methods are also provided: 260 261 .. method:: gdbm.firstkey() 262 263 It's possible to loop over every key in the database using this method and the 264 :meth:`nextkey` method. The traversal is ordered by GDBM's internal 265 hash values, and won't be sorted by the key values. This method returns 266 the starting key. 267 268 .. method:: gdbm.nextkey(key) 269 270 Returns the key that follows *key* in the traversal. The following code prints 271 every key in the database ``db``, without having to create a list in memory that 272 contains them all:: 273 274 k = db.firstkey() 275 while k is not None: 276 print(k) 277 k = db.nextkey(k) 278 279 .. method:: gdbm.reorganize() 280 281 If you have carried out a lot of deletions and would like to shrink the space 282 used by the GDBM file, this routine will reorganize the database. :class:`!gdbm` 283 objects will not shorten the length of a database file except by using this 284 reorganization; otherwise, deleted file space will be kept and reused as new 285 (key, value) pairs are added. 286 287 .. method:: gdbm.sync() 288 289 When the database has been opened in fast mode, this method forces any 290 unwritten data to be written to the disk. 291 292 .. method:: gdbm.close() 293 294 Close the GDBM database. 295 296 .. method:: gdbm.clear() 297 298 Remove all items from the GDBM database. 299 300 .. versionadded:: 3.13 301 302 303:mod:`dbm.ndbm` --- New Database Manager 304---------------------------------------- 305 306.. module:: dbm.ndbm 307 :platform: Unix 308 :synopsis: The New Database Manager 309 310**Source code:** :source:`Lib/dbm/ndbm.py` 311 312-------------- 313 314The :mod:`dbm.ndbm` module provides an interface to the 315:abbr:`NDBM (New Database Manager)` library. 316This module can be used with the "classic" NDBM interface or the 317:abbr:`GDBM (GNU dbm)` compatibility interface. 318 319.. note:: 320 321 The file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are incompatible 322 and can not be used interchangeably. 323 324.. warning:: 325 326 The NDBM library shipped as part of macOS has an undocumented limitation on the 327 size of values, which can result in corrupted database files 328 when storing values larger than this limit. Reading such corrupted files can 329 result in a hard crash (segmentation fault). 330 331.. include:: ../includes/wasm-mobile-notavail.rst 332 333.. exception:: error 334 335 Raised on :mod:`dbm.ndbm`-specific errors, such as I/O errors. :exc:`KeyError` is raised 336 for general mapping errors like specifying an incorrect key. 337 338 339.. data:: library 340 341 Name of the NDBM implementation library used. 342 343 344.. function:: open(filename, flag="r", mode=0o666, /) 345 346 Open an NDBM database and return an :class:`!ndbm` object. 347 348 :param filename: 349 The basename of the database file 350 (without the :file:`.dir` or :file:`.pag` extensions). 351 :type filename: :term:`path-like object` 352 353 :param str flag: 354 * ``'r'`` (default): |flag_r| 355 * ``'w'``: |flag_w| 356 * ``'c'``: |flag_c| 357 * ``'n'``: |flag_n| 358 359 :param int mode: 360 |mode_param_doc| 361 362 :class:`!ndbm` objects behave similar to :term:`mappings <mapping>`, 363 but :meth:`!items` and :meth:`!values` methods are not supported. 364 The following methods are also provided: 365 366 .. versionchanged:: 3.11 367 Accepts :term:`path-like object` for filename. 368 369 .. method:: ndbm.close() 370 371 Close the NDBM database. 372 373 .. method:: ndbm.clear() 374 375 Remove all items from the NDBM database. 376 377 .. versionadded:: 3.13 378 379 380:mod:`dbm.dumb` --- Portable DBM implementation 381----------------------------------------------- 382 383.. module:: dbm.dumb 384 :synopsis: Portable implementation of the simple DBM interface. 385 386**Source code:** :source:`Lib/dbm/dumb.py` 387 388.. index:: single: databases 389 390.. note:: 391 392 The :mod:`dbm.dumb` module is intended as a last resort fallback for the 393 :mod:`dbm` module when a more robust module is not available. The :mod:`dbm.dumb` 394 module is not written for speed and is not nearly as heavily used as the other 395 database modules. 396 397-------------- 398 399The :mod:`dbm.dumb` module provides a persistent :class:`dict`-like 400interface which is written entirely in Python. 401Unlike other :mod:`dbm` backends, such as :mod:`dbm.gnu`, no 402external library is required. 403 404The :mod:`!dbm.dumb` module defines the following: 405 406.. exception:: error 407 408 Raised on :mod:`dbm.dumb`-specific errors, such as I/O errors. :exc:`KeyError` is 409 raised for general mapping errors like specifying an incorrect key. 410 411 412.. function:: open(filename, flag="c", mode=0o666) 413 414 Open a :mod:`!dbm.dumb` database. 415 The returned database object behaves similar to a :term:`mapping`, 416 in addition to providing :meth:`~dumbdbm.sync` and :meth:`~dumbdbm.close` 417 methods. 418 419 :param filename: 420 The basename of the database file (without extensions). 421 A new database creates the following files: 422 423 - :file:`{filename}.dat` 424 - :file:`{filename}.dir` 425 :type database: :term:`path-like object` 426 427 :param str flag: 428 * ``'r'``: |flag_r| 429 * ``'w'``: |flag_w| 430 * ``'c'`` (default): |flag_c| 431 * ``'n'``: |flag_n| 432 433 :param int mode: 434 |mode_param_doc| 435 436 .. warning:: 437 It is possible to crash the Python interpreter when loading a database 438 with a sufficiently large/complex entry due to stack depth limitations in 439 Python's AST compiler. 440 441 .. versionchanged:: 3.5 442 :func:`~dbm.dumb.open` always creates a new database when *flag* is ``'n'``. 443 444 .. versionchanged:: 3.8 445 A database opened read-only if *flag* is ``'r'``. 446 A database is not created if it does not exist if *flag* is ``'r'`` or ``'w'``. 447 448 .. versionchanged:: 3.11 449 *filename* accepts a :term:`path-like object`. 450 451 In addition to the methods provided by the 452 :class:`collections.abc.MutableMapping` class, 453 the following methods are provided: 454 455 .. method:: dumbdbm.sync() 456 457 Synchronize the on-disk directory and data files. This method is called 458 by the :meth:`Shelve.sync` method. 459 460 .. method:: dumbdbm.close() 461 462 Close the database. 463