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}.  Files never intended
  41 to be preserved on disk may be created by passing \code{None} as the
  42 \var{filename}.  The optional
  43 \var{flag} identifies the mode used to open the file.  It may be
  44 \character{r} (read only), \character{w} (read-write),
  45 \character{c} (read-write - create if necessary) or
  46 \character{n} (read-write - truncate to zero length).  The other
  47 arguments are rarely used and are just passed to the low-level
  48 \cfunction{dbopen()} function.  Consult the Berkeley DB documentation
  49 for their use and interpretation.
  50 \end{funcdesc}
  51
  52 \begin{funcdesc}{btopen}{filename\optional{, flag\optional{,
  53 mode\optional{, btflags\optional{, cachesize\optional{, maxkeypage\optional{,
  54 minkeypage\optional{, psize\optional{, lorder}}}}}}}}}
  55
  56 Open the btree format file named \var{filename}.  Files never intended
  57 to be preserved on disk may be created by passing \code{None} as the
  58 \var{filename}.  The optional
  59 \var{flag} identifies the mode used to open the file.  It may be
  60 \character{r} (read only), \character{w} (read-write),
  61 \character{c} (read-write - create if necessary) or
  62 \character{n} (read-write - truncate to zero length).  The other
  63 arguments are rarely used and are just passed to the low-level dbopen
  64 function.  Consult the Berkeley DB documentation for their use and
  65 interpretation.
  66 \end{funcdesc}
  67
  68 \begin{funcdesc}{rnopen}{filename\optional{, flag\optional{, mode\optional{,
  69 rnflags\optional{, cachesize\optional{, psize\optional{, lorder\optional{,
  70 reclen\optional{, bval\optional{, bfname}}}}}}}}}}
  71
  72 Open a DB record format file named \var{filename}.  Files never intended
  73 to be preserved on disk may be created by passing \code{None} as the
  74 \var{filename}.  The optional
  75 \var{flag} identifies the mode used to open the file.  It may be
  76 \character{r} (read only), \character{w} (read-write),
  77 \character{c} (read-write - create if necessary) or
  78 \character{n} (read-write - truncate to zero length).  The other
  79 arguments are rarely used and are just passed to the low-level dbopen
  80 function.  Consult the Berkeley DB documentation for their use and
  81 interpretation.
  82 \end{funcdesc}
  83
  84
  85 \begin{seealso}
  86   \seemodule{dbhash}{DBM-style interface to the \module{bsddb}}
  87 \end{seealso}
  88
  89
  90 \subsection{Hash, BTree and Record Objects \label{bsddb-objects}}
  91
  92 Once instantiated, hash, btree and record objects support the following
  93 methods:
  94
  95 \begin{methoddesc}{close}{}
  96 Close the underlying file.  The object can no longer be accessed.  Since
  97 there is no open \method{open} method for these objects, to open the file
  98 again a new \module{bsddb} module open function must be called.
  99 \end{methoddesc}
 100
 101 \begin{methoddesc}{keys}{}
 102 Return the list of keys contained in the DB file.  The order of the list is
 103 unspecified and should not be relied on.  In particular, the order of the
 104 list returned is different for different file formats.
 105 \end{methoddesc}
 106
 107 \begin{methoddesc}{has_key}{key}
 108 Return \code{1} if the DB file contains the argument as a key.
 109 \end{methoddesc}
 110
 111 \begin{methoddesc}{set_location}{key}
 112 Set the cursor to the item indicated by \var{key} and return a tuple
 113 containing the key and its value.  For binary tree databases (opened
 114 using \function{btopen()}), if \var{key} does not actually exist in
 115 the database, the cursor will point to the next item in sorted order
 116 and return that key and value.  For other databases,
 117 \exception{KeyError} will be raised if \var{key} is not found in the
 118 database.
 119 \end{methoddesc}
 120
 121 \begin{methoddesc}{first}{}
 122 Set the cursor to the first item in the DB file and return it.  The order of
 123 keys in the file is unspecified, except in the case of B-Tree databases.
 124 \end{methoddesc}
 125
 126 \begin{methoddesc}{next}{}
 127 Set the cursor to the next item in the DB file and return it.  The order of
 128 keys in the file is unspecified, except in the case of B-Tree databases.
 129 \end{methoddesc}
 130
 131 \begin{methoddesc}{previous}{}
 132 Set the cursor to the first item in the DB file and return it.  The
 133 order of keys in the file is unspecified, except in the case of B-Tree
 134 databases.  This is not supported on hashtable databases (those opened
 135 with \function{hashopen()}).
 136 \end{methoddesc}
 137
 138 \begin{methoddesc}{last}{}
 139 Set the cursor to the last item in the DB file and return it.  The
 140 order of keys in the file is unspecified.  This is not supported on
 141 hashtable databases (those opened with \function{hashopen()}).
 142 \end{methoddesc}
 143
 144 \begin{methoddesc}{sync}{}
 145 Synchronize the database on disk.
 146 \end{methoddesc}
 147
 148 Example:
 149
 150 \begin{verbatim}
 151 >>> import bsddb
 152 >>> db = bsddb.btopen('/tmp/spam.db', 'c')
 153 >>> for i in range(10): db['%d'%i] = '%d'% (i*i)
 154 ...
 155 >>> db['3']
 156 '9'
 157 >>> db.keys()
 158 ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9']
 159 >>> db.first()
 160 ('0', '0')
 161 >>> db.next()
 162 ('1', '1')
 163 >>> db.last()
 164 ('9', '81')
 165 >>> db.set_location('2')
 166 ('2', '4')
 167 >>> db.previous()
 168 ('1', '1')
 169 >>> db.sync()
 170 0
 171 \end{verbatim}