Doc/library/bsddb.rst

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