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