Guido van Rossum | b69e095 | 1994-08-08 08:03:24 +0000 | [diff] [blame] | 1 | \section{Built-in Module \sectcode{gdbm}} |
Guido van Rossum | 3c2a056 | 1997-07-17 16:29:42 +0000 | [diff] [blame] | 2 | \label{module-gdbm} |
Guido van Rossum | b69e095 | 1994-08-08 08:03:24 +0000 | [diff] [blame] | 3 | \bimodindex{gdbm} |
| 4 | |
Fred Drake | c2297c1 | 1997-12-04 04:45:28 +0000 | [diff] [blame] | 5 | This module is quite similar to the \code{dbm} module, but uses \code{gdbm} |
Guido van Rossum | 3c2a056 | 1997-07-17 16:29:42 +0000 | [diff] [blame] | 6 | instead to provide some additional functionality. Please note that |
Fred Drake | c2297c1 | 1997-12-04 04:45:28 +0000 | [diff] [blame] | 7 | the file formats created by \code{gdbm} and \code{dbm} are incompatible. |
Fred Drake | 4f496cc | 1997-12-16 04:08:24 +0000 | [diff] [blame] | 8 | \refbimodindex{dbm} |
Guido van Rossum | 3c2a056 | 1997-07-17 16:29:42 +0000 | [diff] [blame] | 9 | |
| 10 | The \code{gdbm} module provides an interface to the GNU DBM |
Fred Drake | c2297c1 | 1997-12-04 04:45:28 +0000 | [diff] [blame] | 11 | library. \code{gdbm} objects behave like mappings |
Guido van Rossum | 3c2a056 | 1997-07-17 16:29:42 +0000 | [diff] [blame] | 12 | (dictionaries), except that keys and values are always strings. |
Fred Drake | c2297c1 | 1997-12-04 04:45:28 +0000 | [diff] [blame] | 13 | Printing a \code{gdbm} object doesn't print the keys and values, and the |
Guido van Rossum | 3c2a056 | 1997-07-17 16:29:42 +0000 | [diff] [blame] | 14 | \code{items()} and \code{values()} methods are not supported. |
| 15 | |
| 16 | The module defines the following constant and functions: |
| 17 | |
Fred Drake | c2297c1 | 1997-12-04 04:45:28 +0000 | [diff] [blame] | 18 | \renewcommand{\indexsubitem}{(in module gdbm)} |
Guido van Rossum | 3c2a056 | 1997-07-17 16:29:42 +0000 | [diff] [blame] | 19 | \begin{excdesc}{error} |
Fred Drake | c2297c1 | 1997-12-04 04:45:28 +0000 | [diff] [blame] | 20 | Raised on \code{gdbm}-specific errors, such as I/O errors. \code{KeyError} is |
Guido van Rossum | 3c2a056 | 1997-07-17 16:29:42 +0000 | [diff] [blame] | 21 | raised for general mapping errors like specifying an incorrect key. |
| 22 | \end{excdesc} |
| 23 | |
| 24 | \begin{funcdesc}{open}{filename\, \optional{flag\, \optional{mode}}} |
Fred Drake | c2297c1 | 1997-12-04 04:45:28 +0000 | [diff] [blame] | 25 | Open a \code{gdbm} database and return a \code{gdbm} object. The |
| 26 | \var{filename} argument is the name of the database file. |
Guido van Rossum | 3c2a056 | 1997-07-17 16:29:42 +0000 | [diff] [blame] | 27 | |
| 28 | The optional \var{flag} argument can be |
| 29 | \code{'r'} (to open an existing database for reading only --- default), |
| 30 | \code{'w'} (to open an existing database for reading and writing), |
| 31 | \code{'c'} (which creates the database if it doesn't exist), or |
| 32 | \code{'n'} (which always creates a new empty database). |
| 33 | |
| 34 | Appending \code{f} to the flag opens the database in fast mode; |
| 35 | altered data will not automatically be written to the disk after every |
| 36 | change. This results in faster writes to the database, but may result |
| 37 | in an inconsistent database if the program crashes while the database |
| 38 | is still open. Use the \code{sync()} method to force any unwritten |
| 39 | data to be written to the disk. |
| 40 | |
| 41 | The optional \var{mode} argument is the \UNIX{} mode of the file, used |
| 42 | only when the database has to be created. It defaults to octal |
| 43 | \code{0666}. |
| 44 | \end{funcdesc} |
| 45 | |
Fred Drake | c2297c1 | 1997-12-04 04:45:28 +0000 | [diff] [blame] | 46 | In addition to the dictionary-like methods, \code{gdbm} objects have the |
Guido van Rossum | 3c2a056 | 1997-07-17 16:29:42 +0000 | [diff] [blame] | 47 | following methods: |
| 48 | |
| 49 | \begin{funcdesc}{firstkey}{} |
| 50 | It's possible to loop over every key in the database using this method |
Fred Drake | c2297c1 | 1997-12-04 04:45:28 +0000 | [diff] [blame] | 51 | and the \code{nextkey()} method. The traversal is ordered by \code{gdbm}'s |
Guido van Rossum | 3c2a056 | 1997-07-17 16:29:42 +0000 | [diff] [blame] | 52 | internal hash values, and won't be sorted by the key values. This |
| 53 | method returns the starting key. |
| 54 | \end{funcdesc} |
| 55 | |
| 56 | \begin{funcdesc}{nextkey}{key} |
| 57 | Returns the key that follows \var{key} in the traversal. The |
| 58 | following code prints every key in the database \code{db}, without having to |
| 59 | create a list in memory that contains them all: |
| 60 | \bcode\begin{verbatim} |
| 61 | k=db.firstkey() |
| 62 | while k!=None: |
| 63 | print k |
| 64 | k=db.nextkey(k) |
| 65 | \end{verbatim}\ecode |
| 66 | \end{funcdesc} |
| 67 | |
| 68 | \begin{funcdesc}{reorganize}{} |
| 69 | If you have carried out a lot of deletions and would like to shrink |
Fred Drake | c2297c1 | 1997-12-04 04:45:28 +0000 | [diff] [blame] | 70 | the space used by the \code{gdbm} file, this routine will reorganize the |
| 71 | database. \code{gdbm} will not shorten the length of a database file except |
Guido van Rossum | 3c2a056 | 1997-07-17 16:29:42 +0000 | [diff] [blame] | 72 | by using this reorganization; otherwise, deleted file space will be |
| 73 | kept and reused as new (key,value) pairs are added. |
| 74 | \end{funcdesc} |
| 75 | |
| 76 | \begin{funcdesc}{sync}{} |
| 77 | When the database has been opened in fast mode, this method forces any |
| 78 | unwritten data to be written to the disk. |
| 79 | \end{funcdesc} |
| 80 | |