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 | |
| 7 | :mod:`dbm` is a generic interface to variants of the DBM database --- |
Benjamin Peterson | 905aa66 | 2008-09-08 21:35:37 +0000 | [diff] [blame] | 8 | :mod:`dbm.gnu` or :mod:`dbm.ndbm`. If none of these modules is installed, the |
| 9 | slow-but-simple implementation in module :mod:`dbm.dumb` will be used. There |
| 10 | is a `third party interface <http://www.jcea.es/programacion/pybsddb.htm>`_ to |
| 11 | the Oracle Berkely DB. |
Georg Brandl | 0a7ac7d | 2008-05-26 10:29:35 +0000 | [diff] [blame] | 12 | |
| 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 | |
| 23 | This functionattempts to guess which of the several simple database modules |
| 24 | available --- :mod:`dbm.bsd`, :mod:`dbm.gnu`, :mod:`dbm.ndbm` or |
| 25 | :mod:`dbm.dumb` --- should be used to open a given file. |
| 26 | |
| 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 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 33 | .. function:: open(filename, flag='r', mode=0o666) |
Georg Brandl | 0a7ac7d | 2008-05-26 10:29:35 +0000 | [diff] [blame] | 34 | |
| 35 | Open the database file *filename* and return a corresponding object. |
| 36 | |
| 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 Brandl | 1a04058 | 2009-05-25 21:15:01 +0000 | [diff] [blame] | 41 | 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 Brandl | 0a7ac7d | 2008-05-26 10:29:35 +0000 | [diff] [blame] | 58 | |
| 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 | |
| 64 | The object returned by :func:`open` supports most of the same functionality as |
| 65 | dictionaries; keys and their corresponding values can be stored, retrieved, and |
| 66 | deleted, and the :keyword:`in` operator and the :meth:`keys` method are |
Brett Cannon | 7317c1e | 2008-11-25 19:19:17 +0000 | [diff] [blame] | 67 | available. Key and values are always stored as bytes. This means that when |
| 68 | strings are used they are implicitly converted to the default encoding before |
| 69 | being stored. |
Georg Brandl | 0a7ac7d | 2008-05-26 10:29:35 +0000 | [diff] [blame] | 70 | |
| 71 | The following example records some hostnames and a corresponding title, and |
| 72 | then prints out the contents of the database:: |
| 73 | |
| 74 | import dbm |
| 75 | |
| 76 | # Open database, creating it if necessary. |
| 77 | db = dbm.open('cache', 'c') |
| 78 | |
| 79 | # Record some values |
Brett Cannon | 7317c1e | 2008-11-25 19:19:17 +0000 | [diff] [blame] | 80 | db[b'hello'] = b'there' |
Georg Brandl | 0a7ac7d | 2008-05-26 10:29:35 +0000 | [diff] [blame] | 81 | db['www.python.org'] = 'Python Website' |
| 82 | db['www.cnn.com'] = 'Cable News Network' |
| 83 | |
Brett Cannon | 7317c1e | 2008-11-25 19:19:17 +0000 | [diff] [blame] | 84 | # Note that the keys are considered bytes now. |
| 85 | assert db[b'www.python.org'] == b'Python Website' |
| 86 | # Notice how the value is now in bytes. |
| 87 | assert db['www.cnn.com'] == b'Cable News Network' |
| 88 | |
Georg Brandl | 0a7ac7d | 2008-05-26 10:29:35 +0000 | [diff] [blame] | 89 | # Loop through contents. Other dictionary methods |
| 90 | # such as .keys(), .values() also work. |
| 91 | for k, v in db.iteritems(): |
| 92 | print(k, '\t', v) |
| 93 | |
| 94 | # Storing a non-string key or value will raise an exception (most |
| 95 | # likely a TypeError). |
| 96 | db['www.yahoo.com'] = 4 |
| 97 | |
| 98 | # Close when done. |
| 99 | db.close() |
| 100 | |
| 101 | |
| 102 | .. seealso:: |
| 103 | |
| 104 | Module :mod:`shelve` |
| 105 | Persistence module which stores non-string data. |
| 106 | |
| 107 | |
| 108 | The individual submodules are described in the following sections. |
| 109 | |
| 110 | |
Georg Brandl | 0a7ac7d | 2008-05-26 10:29:35 +0000 | [diff] [blame] | 111 | :mod:`dbm.gnu` --- GNU's reinterpretation of dbm |
| 112 | ------------------------------------------------ |
| 113 | |
| 114 | .. module:: dbm.gnu |
| 115 | :platform: Unix |
| 116 | :synopsis: GNU's reinterpretation of dbm. |
| 117 | |
| 118 | |
| 119 | This module is quite similar to the :mod:`dbm` module, but uses the GNU library |
| 120 | ``gdbm`` instead to provide some additional functionality. Please note that the |
Brett Cannon | 7317c1e | 2008-11-25 19:19:17 +0000 | [diff] [blame] | 121 | 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] | 122 | |
| 123 | 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] | 124 | ``dbm.gnu.gdbm`` objects behave like mappings (dictionaries), except that keys and |
| 125 | values are always converted to bytes before storing. Printing a ``gdbm`` |
| 126 | object doesn't print the |
Georg Brandl | 0a7ac7d | 2008-05-26 10:29:35 +0000 | [diff] [blame] | 127 | keys and values, and the :meth:`items` and :meth:`values` methods are not |
| 128 | supported. |
| 129 | |
| 130 | .. exception:: error |
| 131 | |
Brett Cannon | 7317c1e | 2008-11-25 19:19:17 +0000 | [diff] [blame] | 132 | 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] | 133 | raised for general mapping errors like specifying an incorrect key. |
| 134 | |
| 135 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 136 | .. function:: open(filename[, flag[, mode]]) |
Georg Brandl | 0a7ac7d | 2008-05-26 10:29:35 +0000 | [diff] [blame] | 137 | |
| 138 | Open a ``gdbm`` database and return a :class:`gdbm` object. The *filename* |
| 139 | argument is the name of the database file. |
| 140 | |
| 141 | The optional *flag* argument can be: |
| 142 | |
| 143 | +---------+-------------------------------------------+ |
| 144 | | Value | Meaning | |
| 145 | +=========+===========================================+ |
| 146 | | ``'r'`` | Open existing database for reading only | |
| 147 | | | (default) | |
| 148 | +---------+-------------------------------------------+ |
| 149 | | ``'w'`` | Open existing database for reading and | |
| 150 | | | writing | |
| 151 | +---------+-------------------------------------------+ |
| 152 | | ``'c'`` | Open database for reading and writing, | |
| 153 | | | creating it if it doesn't exist | |
| 154 | +---------+-------------------------------------------+ |
| 155 | | ``'n'`` | Always create a new, empty database, open | |
| 156 | | | for reading and writing | |
| 157 | +---------+-------------------------------------------+ |
| 158 | |
| 159 | The following additional characters may be appended to the flag to control |
| 160 | how the database is opened: |
| 161 | |
| 162 | +---------+--------------------------------------------+ |
| 163 | | Value | Meaning | |
| 164 | +=========+============================================+ |
| 165 | | ``'f'`` | Open the database in fast mode. Writes | |
| 166 | | | to the database will not be synchronized. | |
| 167 | +---------+--------------------------------------------+ |
| 168 | | ``'s'`` | Synchronized mode. This will cause changes | |
| 169 | | | to the database to be immediately written | |
| 170 | | | to the file. | |
| 171 | +---------+--------------------------------------------+ |
| 172 | | ``'u'`` | Do not lock database. | |
| 173 | +---------+--------------------------------------------+ |
| 174 | |
| 175 | Not all flags are valid for all versions of ``gdbm``. The module constant |
| 176 | :const:`open_flags` is a string of supported flag characters. The exception |
| 177 | :exc:`error` is raised if an invalid flag is specified. |
| 178 | |
| 179 | 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] | 180 | database has to be created. It defaults to octal ``0o666``. |
Georg Brandl | 0a7ac7d | 2008-05-26 10:29:35 +0000 | [diff] [blame] | 181 | |
| 182 | In addition to the dictionary-like methods, ``gdbm`` objects have the |
| 183 | following methods: |
| 184 | |
| 185 | .. method:: gdbm.firstkey() |
| 186 | |
| 187 | It's possible to loop over every key in the database using this method and the |
| 188 | :meth:`nextkey` method. The traversal is ordered by ``gdbm``'s internal |
| 189 | hash values, and won't be sorted by the key values. This method returns |
| 190 | the starting key. |
| 191 | |
| 192 | .. method:: gdbm.nextkey(key) |
| 193 | |
| 194 | Returns the key that follows *key* in the traversal. The following code prints |
| 195 | every key in the database ``db``, without having to create a list in memory that |
| 196 | contains them all:: |
| 197 | |
| 198 | k = db.firstkey() |
| 199 | while k != None: |
| 200 | print(k) |
| 201 | k = db.nextkey(k) |
| 202 | |
| 203 | .. method:: gdbm.reorganize() |
| 204 | |
| 205 | If you have carried out a lot of deletions and would like to shrink the space |
| 206 | used by the ``gdbm`` file, this routine will reorganize the database. ``gdbm`` |
Brett Cannon | 7317c1e | 2008-11-25 19:19:17 +0000 | [diff] [blame] | 207 | 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] | 208 | reorganization; otherwise, deleted file space will be kept and reused as new |
| 209 | (key, value) pairs are added. |
| 210 | |
| 211 | .. method:: gdbm.sync() |
| 212 | |
| 213 | When the database has been opened in fast mode, this method forces any |
| 214 | unwritten data to be written to the disk. |
| 215 | |
| 216 | |
| 217 | :mod:`dbm.ndbm` --- Interface based on ndbm |
| 218 | ------------------------------------------- |
| 219 | |
| 220 | .. module:: dbm.ndbm |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 221 | :platform: Unix |
| 222 | :synopsis: The standard "database" interface, based on ndbm. |
| 223 | |
| 224 | |
Georg Brandl | 0a7ac7d | 2008-05-26 10:29:35 +0000 | [diff] [blame] | 225 | The :mod:`dbm.ndbm` module provides an interface to the Unix "(n)dbm" library. |
| 226 | Dbm objects behave like mappings (dictionaries), except that keys and values are |
Brett Cannon | 7317c1e | 2008-11-25 19:19:17 +0000 | [diff] [blame] | 227 | always stored as bytes. Printing a ``dbm`` object doesn't print the keys and |
| 228 | values, and the :meth:`items` and :meth:`values` methods are not supported. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 229 | |
| 230 | This module can be used with the "classic" ndbm interface, the BSD DB |
| 231 | compatibility interface, or the GNU GDBM compatibility interface. On Unix, the |
| 232 | :program:`configure` script will attempt to locate the appropriate header file |
| 233 | to simplify building this module. |
| 234 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 235 | .. exception:: error |
| 236 | |
Brett Cannon | 7317c1e | 2008-11-25 19:19:17 +0000 | [diff] [blame] | 237 | 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] | 238 | for general mapping errors like specifying an incorrect key. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 239 | |
| 240 | |
| 241 | .. data:: library |
| 242 | |
| 243 | Name of the ``ndbm`` implementation library used. |
| 244 | |
| 245 | |
| 246 | .. function:: open(filename[, flag[, mode]]) |
| 247 | |
Brett Cannon | 7317c1e | 2008-11-25 19:19:17 +0000 | [diff] [blame] | 248 | Open a dbm database and return a ``dbm`` object. The *filename* argument is the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 249 | name of the database file (without the :file:`.dir` or :file:`.pag` extensions; |
| 250 | note that the BSD DB implementation of the interface will append the extension |
| 251 | :file:`.db` and only create one file). |
| 252 | |
| 253 | The optional *flag* argument must be one of these values: |
| 254 | |
| 255 | +---------+-------------------------------------------+ |
| 256 | | Value | Meaning | |
| 257 | +=========+===========================================+ |
| 258 | | ``'r'`` | Open existing database for reading only | |
| 259 | | | (default) | |
| 260 | +---------+-------------------------------------------+ |
| 261 | | ``'w'`` | Open existing database for reading and | |
| 262 | | | writing | |
| 263 | +---------+-------------------------------------------+ |
| 264 | | ``'c'`` | Open database for reading and writing, | |
| 265 | | | creating it if it doesn't exist | |
| 266 | +---------+-------------------------------------------+ |
| 267 | | ``'n'`` | Always create a new, empty database, open | |
| 268 | | | for reading and writing | |
| 269 | +---------+-------------------------------------------+ |
| 270 | |
| 271 | 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] | 272 | 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] | 273 | modified by the prevailing umask). |
| 274 | |
| 275 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 276 | |
Georg Brandl | 0a7ac7d | 2008-05-26 10:29:35 +0000 | [diff] [blame] | 277 | :mod:`dbm.dumb` --- Portable DBM implementation |
| 278 | ----------------------------------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 279 | |
Georg Brandl | 0a7ac7d | 2008-05-26 10:29:35 +0000 | [diff] [blame] | 280 | .. module:: dbm.dumb |
| 281 | :synopsis: Portable implementation of the simple DBM interface. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 282 | |
Georg Brandl | 0a7ac7d | 2008-05-26 10:29:35 +0000 | [diff] [blame] | 283 | .. index:: single: databases |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 284 | |
Georg Brandl | 0a7ac7d | 2008-05-26 10:29:35 +0000 | [diff] [blame] | 285 | .. note:: |
| 286 | |
| 287 | 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] | 288 | :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] | 289 | module is not written for speed and is not nearly as heavily used as the other |
| 290 | database modules. |
| 291 | |
| 292 | The :mod:`dbm.dumb` module provides a persistent dictionary-like interface which |
Brett Cannon | 7317c1e | 2008-11-25 19:19:17 +0000 | [diff] [blame] | 293 | 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] | 294 | external library is required. As with other persistent mappings, the keys and |
Brett Cannon | 7317c1e | 2008-11-25 19:19:17 +0000 | [diff] [blame] | 295 | values are always stored as bytes. |
Georg Brandl | 0a7ac7d | 2008-05-26 10:29:35 +0000 | [diff] [blame] | 296 | |
| 297 | The module defines the following: |
| 298 | |
| 299 | |
| 300 | .. exception:: error |
| 301 | |
Brett Cannon | 7317c1e | 2008-11-25 19:19:17 +0000 | [diff] [blame] | 302 | 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] | 303 | raised for general mapping errors like specifying an incorrect key. |
| 304 | |
| 305 | |
| 306 | .. function:: open(filename[, flag[, mode]]) |
| 307 | |
Brett Cannon | 7317c1e | 2008-11-25 19:19:17 +0000 | [diff] [blame] | 308 | 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] | 309 | the basename of the database file (without any specific extensions). When a |
| 310 | dumbdbm database is created, files with :file:`.dat` and :file:`.dir` extensions |
| 311 | are created. |
| 312 | |
| 313 | The optional *flag* argument is currently ignored; the database is always opened |
| 314 | for update, and will be created if it does not exist. |
| 315 | |
| 316 | The optional *mode* argument is the Unix mode of the file, used only when the |
| 317 | database has to be created. It defaults to octal ``0o666`` (and will be modified |
| 318 | by the prevailing umask). |
| 319 | |
| 320 | In addition to the methods provided by the :class:`collections.MutableMapping` class, |
| 321 | :class:`dumbdbm` objects provide the following method: |
| 322 | |
| 323 | .. method:: dumbdbm.sync() |
| 324 | |
| 325 | Synchronize the on-disk directory and data files. This method is called |
| 326 | by the :meth:`Shelve.sync` method. |