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 \function{marshal.dumps()} or
  16 \function{pickle.dumps()}.
  17
  18 The \module{bsddb} module requires a Berkeley DB library version from
  19 3.3 thru 4.5.
  20
  21 \begin{seealso}
  22   \seeurl{http://pybsddb.sourceforge.net/}
  23          {The website with documentation for the \module{bsddb.db}
  24           Python Berkeley DB interface that closely mirrors the object
  25           oriented interface provided in Berkeley DB 3 and 4.}
  26
  27   \seeurl{http://www.oracle.com/database/berkeley-db/}
  28          {The Berkeley DB library.}
  29 \end{seealso}
  30
  31 A more modern DB, DBEnv and DBSequence object interface is available in the
  32 \module{bsddb.db} module which closely matches the Berkeley DB C API
  33 documented at the above URLs.  Additional features provided by the
  34 \module{bsddb.db} API include fine tuning, transactions, logging, and
  35 multiprocess concurrent database access.
  36
  37 The following is a description of the legacy \module{bsddb} interface
  38 compatible with the old Python bsddb module.  Starting in Python 2.5 this
  39 interface should be safe for multithreaded access.  The \module{bsddb.db}
  40 API is recommended for threading users as it provides better control.
  41
  42 The \module{bsddb} module defines the following functions that create
  43 objects that access the appropriate type of Berkeley DB file.  The
  44 first two arguments of each function are the same.  For ease of
  45 portability, only the first two arguments should be used in most
  46 instances.
  47
  48 \begin{funcdesc}{hashopen}{filename\optional{, flag\optional{,
  49                            mode\optional{, bsize\optional{,
  50                            ffactor\optional{, nelem\optional{,
  51                            cachesize\optional{, hash\optional{,
  52                            lorder}}}}}}}}}
  53 Open the hash format file named \var{filename}.  Files never intended
  54 to be preserved on disk may be created by passing \code{None} as the
  55 \var{filename}.  The optional
  56 \var{flag} identifies the mode used to open the file.  It may be
  57 \character{r} (read only), \character{w} (read-write) ,
  58 \character{c} (read-write - create if necessary; the default) or
  59 \character{n} (read-write - truncate to zero length).  The other
  60 arguments are rarely used and are just passed to the low-level
  61 \cfunction{dbopen()} function.  Consult the Berkeley DB documentation
  62 for their use and interpretation.
  63 \end{funcdesc}
  64
  65 \begin{funcdesc}{btopen}{filename\optional{, flag\optional{,
  66 mode\optional{, btflags\optional{, cachesize\optional{, maxkeypage\optional{,
  67 minkeypage\optional{, pgsize\optional{, lorder}}}}}}}}}
  68
  69 Open the btree format file named \var{filename}.  Files never intended
  70 to be preserved on disk may be created by passing \code{None} as the
  71 \var{filename}.  The optional
  72 \var{flag} identifies the mode used to open the file.  It may be
  73 \character{r} (read only), \character{w} (read-write),
  74 \character{c} (read-write - create if necessary; the default) or
  75 \character{n} (read-write - truncate to zero length).  The other
  76 arguments are rarely used and are just passed to the low-level dbopen
  77 function.  Consult the Berkeley DB documentation for their use and
  78 interpretation.
  79 \end{funcdesc}
  80
  81 \begin{funcdesc}{rnopen}{filename\optional{, flag\optional{, mode\optional{,
  82 rnflags\optional{, cachesize\optional{, pgsize\optional{, lorder\optional{,
  83 reclen\optional{, bval\optional{, bfname}}}}}}}}}}
  84
  85 Open a DB record format file named \var{filename}.  Files never intended
  86 to be preserved on disk may be created by passing \code{None} as the
  87 \var{filename}.  The optional
  88 \var{flag} identifies the mode used to open the file.  It may be
  89 \character{r} (read only), \character{w} (read-write),
  90 \character{c} (read-write - create if necessary; the default) or
  91 \character{n} (read-write - truncate to zero length).  The other
  92 arguments are rarely used and are just passed to the low-level dbopen
  93 function.  Consult the Berkeley DB documentation for their use and
  94 interpretation.
  95 \end{funcdesc}
  96
  97
  98 \begin{notice}
  99 Beginning in 2.3 some \UNIX{} versions of Python may have a \module{bsddb185}
 100 module.  This is present \emph{only} to allow backwards compatibility with
 101 systems which ship with the old Berkeley DB 1.85 database library.  The
 102 \module{bsddb185} module should never be used directly in new code.
 103 \end{notice}
 104
 105
 106 \begin{seealso}
 107   \seemodule{dbhash}{DBM-style interface to the \module{bsddb}}
 108 \end{seealso}
 109
 110 \subsection{Hash, BTree and Record Objects \label{bsddb-objects}}
 111
 112 Once instantiated, hash, btree and record objects support
 113 the same methods as dictionaries.  In addition, they support
 114 the methods listed below.
 115 \versionchanged[Added dictionary methods]{2.3.1}
 116
 117 \begin{methoddesc}{close}{}
 118 Close the underlying file.  The object can no longer be accessed.  Since
 119 there is no open \method{open} method for these objects, to open the file
 120 again a new \module{bsddb} module open function must be called.
 121 \end{methoddesc}
 122
 123 \begin{methoddesc}{keys}{}
 124 Return the list of keys contained in the DB file.  The order of the list is
 125 unspecified and should not be relied on.  In particular, the order of the
 126 list returned is different for different file formats.
 127 \end{methoddesc}
 128
 129 \begin{methoddesc}{has_key}{key}
 130 Return \code{1} if the DB file contains the argument as a key.
 131 \end{methoddesc}
 132
 133 \begin{methoddesc}{set_location}{key}
 134 Set the cursor to the item indicated by \var{key} and return a tuple
 135 containing the key and its value.  For binary tree databases (opened
 136 using \function{btopen()}), if \var{key} does not actually exist in
 137 the database, the cursor will point to the next item in sorted order
 138 and return that key and value.  For other databases,
 139 \exception{KeyError} will be raised if \var{key} is not found in the
 140 database.
 141 \end{methoddesc}
 142
 143 \begin{methoddesc}{first}{}
 144 Set the cursor to the first item in the DB file and return it.  The order of
 145 keys in the file is unspecified, except in the case of B-Tree databases.
 146 This method raises \exception{bsddb.error} if the database is empty.
 147 \end{methoddesc}
 148
 149 \begin{methoddesc}{next}{}
 150 Set the cursor to the next item in the DB file and return it.  The order of
 151 keys in the file is unspecified, except in the case of B-Tree databases.
 152 \end{methoddesc}
 153
 154 \begin{methoddesc}{previous}{}
 155 Set the cursor to the previous item in the DB file and return it.  The
 156 order of keys in the file is unspecified, except in the case of B-Tree
 157 databases.  This is not supported on hashtable databases (those opened
 158 with \function{hashopen()}).
 159 \end{methoddesc}
 160
 161 \begin{methoddesc}{last}{}
 162 Set the cursor to the last item in the DB file and return it.  The
 163 order of keys in the file is unspecified.  This is not supported on
 164 hashtable databases (those opened with \function{hashopen()}).
 165 This method raises \exception{bsddb.error} if the database is empty.
 166 \end{methoddesc}
 167
 168 \begin{methoddesc}{sync}{}
 169 Synchronize the database on disk.
 170 \end{methoddesc}
 171
 172 Example:
 173
 174 \begin{verbatim}
 175 >>> import bsddb
 176 >>> db = bsddb.btopen('/tmp/spam.db', 'c')
 177 >>> for i in range(10): db['%d'%i] = '%d'% (i*i)
 178 ...
 179 >>> db['3']
 180 '9'
 181 >>> db.keys()
 182 ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9']
 183 >>> db.first()
 184 ('0', '0')
 185 >>> db.next()
 186 ('1', '1')
 187 >>> db.last()
 188 ('9', '81')
 189 >>> db.set_location('2')
 190 ('2', '4')
 191 >>> db.previous()
 192 ('1', '1')
 193 >>> for k, v in db.iteritems():
 194 ...     print k, v
 195 0 0
 196 1 1
 197 2 4
 198 3 9
 199 4 16
 200 5 25
 201 6 36
 202 7 49
 203 8 64
 204 9 81
 205 >>> '8' in db
 206 True
 207 >>> db.sync()
 208 0
 209 \end{verbatim}