Doc/lib/libbsddb.tex

   1 \section{\module{bsddb} ---
   2          Interface to Berkeley DB library}
   3
   4 \declaremodule{extension}{bsddb}
   5   \platform{Unix, Windows}
   6 \modulesynopsis{Interface to Berkeley DB database library}
   7 \sectionauthor{Skip Montanaro}{skip@mojam.com}
   8
   9
  10 The \module{bsddb} module provides an interface to the Berkeley DB
  11 library.  Users can create hash, btree or record based library files
  12 using the appropriate open call. Bsddb objects behave generally like
  13 dictionaries.  Keys and values must be strings, however, so to use
  14 other objects as keys or to store other kinds of objects the user must
  15 serialize them somehow, typically using marshal.dumps or pickle.dumps.
  16
  17 There are two incompatible versions of the underlying library.
  18 Version 1.85 is widely available, but has some known bugs.  Version 2
  19 is not quite as widely used, but does offer some improvements.  The
  20 \module{bsddb} module uses the 1.85 interface.  Starting with Python
  21 2.0, the \program{configure} script can usually determine the
  22 version of the library which is available and build it correctly.  If
  23 you have difficulty getting \program{configure} to do the right thing,
  24 run it with the \longprogramopt{help} option to get information about
  25 additional options that can help.  On Windows, you will need to define
  26 the \code{HAVE_DB_185_H} macro if you are building Python from source
  27 and using version 2 of the DB library.
  28
  29 The \module{bsddb} module defines the following functions that create
  30 objects that access the appropriate type of Berkeley DB file.  The
  31 first two arguments of each function are the same.  For ease of
  32 portability, only the first two arguments should be used in most
  33 instances.
  34
  35 \begin{funcdesc}{hashopen}{filename\optional{, flag\optional{,
  36                            mode\optional{, bsize\optional{,
  37                            ffactor\optional{, nelem\optional{,
  38                            cachesize\optional{, hash\optional{,
  39                            lorder}}}}}}}}}
  40 Open the hash format file named \var{filename}.  The optional
  41 \var{flag} identifies the mode used to open the file.  It may be
  42 \character{r} (read only), \character{w} (read-write),
  43 \character{c} (read-write - create if necessary) or
  44 \character{n} (read-write - truncate to zero length).  The other
  45 arguments are rarely used and are just passed to the low-level
  46 \cfunction{dbopen()} function.  Consult the Berkeley DB documentation
  47 for their use and interpretation.
  48 \end{funcdesc}
  49
  50 \begin{funcdesc}{btopen}{filename\optional{, flag\optional{,
  51 mode\optional{, btflags\optional{, cachesize\optional{, maxkeypage\optional{,
  52 minkeypage\optional{, psize\optional{, lorder}}}}}}}}}
  53
  54 Open the btree format file named \var{filename}.  The optional
  55 \var{flag} identifies the mode used to open the file.  It may be
  56 \character{r} (read only), \character{w} (read-write),
  57 \character{c} (read-write - create if necessary) or
  58 \character{n} (read-write - truncate to zero length).  The other
  59 arguments are rarely used and are just passed to the low-level dbopen
  60 function.  Consult the Berkeley DB documentation for their use and
  61 interpretation.
  62 \end{funcdesc}
  63
  64 \begin{funcdesc}{rnopen}{filename\optional{, flag\optional{, mode\optional{,
  65 rnflags\optional{, cachesize\optional{, psize\optional{, lorder\optional{,
  66 reclen\optional{, bval\optional{, bfname}}}}}}}}}}
  67
  68 Open a DB record format file named \var{filename}.  The optional
  69 \var{flag} identifies the mode used to open the file.  It may be
  70 \character{r} (read only), \character{w} (read-write),
  71 \character{c} (read-write - create if necessary) or
  72 \character{n} (read-write - truncate to zero length).  The other
  73 arguments are rarely used and are just passed to the low-level dbopen
  74 function.  Consult the Berkeley DB documentation for their use and
  75 interpretation.
  76 \end{funcdesc}
  77
  78
  79 \begin{seealso}
  80   \seemodule{dbhash}{DBM-style interface to the \module{bsddb}}
  81 \end{seealso}
  82
  83
  84 \subsection{Hash, BTree and Record Objects \label{bsddb-objects}}
  85
  86 Once instantiated, hash, btree and record objects support the following
  87 methods:
  88
  89 \begin{methoddesc}{close}{}
  90 Close the underlying file.  The object can no longer be accessed.  Since
  91 there is no open \method{open} method for these objects, to open the file
  92 again a new \module{bsddb} module open function must be called.
  93 \end{methoddesc}
  94
  95 \begin{methoddesc}{keys}{}
  96 Return the list of keys contained in the DB file.  The order of the list is
  97 unspecified and should not be relied on.  In particular, the order of the
  98 list returned is different for different file formats.
  99 \end{methoddesc}
 100
 101 \begin{methoddesc}{has_key}{key}
 102 Return \code{1} if the DB file contains the argument as a key.
 103 \end{methoddesc}
 104
 105 \begin{methoddesc}{set_location}{key}
 106 Set the cursor to the item indicated by \var{key} and return a tuple
 107 containing the key and its value.  For binary tree databases (opened
 108 using \function{btopen()}), if \var{key} does not actually exist in
 109 the database, the cursor will point to the next item in sorted order
 110 and return that key and value.  For other databases,
 111 \exception{KeyError} will be raised if \var{key} is not found in the
 112 database.
 113 \end{methoddesc}
 114
 115 \begin{methoddesc}{first}{}
 116 Set the cursor to the first item in the DB file and return it.  The order of
 117 keys in the file is unspecified, except in the case of B-Tree databases.
 118 \end{methoddesc}
 119
 120 \begin{methoddesc}{next}{}
 121 Set the cursor to the next item in the DB file and return it.  The order of
 122 keys in the file is unspecified, except in the case of B-Tree databases.
 123 \end{methoddesc}
 124
 125 \begin{methoddesc}{previous}{}
 126 Set the cursor to the first item in the DB file and return it.  The
 127 order of keys in the file is unspecified, except in the case of B-Tree
 128 databases.  This is not supported on hashtable databases (those opened
 129 with \function{hashopen()}).
 130 \end{methoddesc}
 131
 132 \begin{methoddesc}{last}{}
 133 Set the cursor to the last item in the DB file and return it.  The
 134 order of keys in the file is unspecified.  This is not supported on
 135 hashtable databases (those opened with \function{hashopen()}).
 136 \end{methoddesc}
 137
 138 \begin{methoddesc}{sync}{}
 139 Synchronize the database on disk.
 140 \end{methoddesc}
 141
 142 Example:
 143
 144 \begin{verbatim}
 145 >>> import bsddb
 146 >>> db = bsddb.btopen('/tmp/spam.db', 'c')
 147 >>> for i in range(10): db['%d'%i] = '%d'% (i*i)
 148 ...
 149 >>> db['3']
 150 '9'
 151 >>> db.keys()
 152 ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9']
 153 >>> db.first()
 154 ('0', '0')
 155 >>> db.next()
 156 ('1', '1')
 157 >>> db.last()
 158 ('9', '81')
 159 >>> db.set_location('2')
 160 ('2', '4')
 161 >>> db.previous()
 162 ('1', '1')
 163 >>> db.sync()
 164 0
 165 \end{verbatim}