
``bsddb`` --- Interface to Berkeley DB library
**********************************************

Deprecated since version 2.6: The ``bsddb`` module has been deprecated
for removal in Python 3.0.

The ``bsddb`` module provides an interface to the Berkeley DB library.
Users can create hash, btree or record based library files using the
appropriate open call. Bsddb objects behave generally like
dictionaries.  Keys and values must be strings, however, so to use
other objects as keys or to store other kinds of objects the user must
serialize them somehow, typically using ``marshal.dumps()`` or
``pickle.dumps()``.

The ``bsddb`` module requires a Berkeley DB library version from 4.0
thru 4.7.

See also:

   http://www.jcea.es/programacion/pybsddb.htm
      The website with documentation for the ``bsddb.db`` Python
      Berkeley DB interface that closely mirrors the object oriented
      interface provided in Berkeley DB 4.x itself.

   http://www.oracle.com/database/berkeley-db/
      The Berkeley DB library.

A more modern DB, DBEnv and DBSequence object interface is available
in the ``bsddb.db`` module which closely matches the Berkeley DB C API
documented at the above URLs.  Additional features provided by the
``bsddb.db`` API include fine tuning, transactions, logging, and
multiprocess concurrent database access.

The following is a description of the legacy ``bsddb`` interface
compatible with the old Python bsddb module.  Starting in Python 2.5
this interface should be safe for multithreaded access.  The
``bsddb.db`` API is recommended for threading users as it provides
better control.

The ``bsddb`` module defines the following functions that create
objects that access the appropriate type of Berkeley DB file.  The
first two arguments of each function are the same.  For ease of
portability, only the first two arguments should be used in most
instances.

bsddb.hashopen(filename[, flag[, mode[, pgsize[, ffactor[, nelem[, cachesize[, lorder[, hflags]]]]]]]])

   Open the hash format file named *filename*.  Files never intended
   to be preserved on disk may be created by passing ``None`` as the
   *filename*.  The optional *flag* identifies the mode used to open
   the file.  It may be ``'r'`` (read only), ``'w'`` (read-write) ,
   ``'c'`` (read-write - create if necessary; the default) or ``'n'``
   (read-write - truncate to zero length).  The other arguments are
   rarely used and are just passed to the low-level ``dbopen()``
   function.  Consult the Berkeley DB documentation for their use and
   interpretation.

bsddb.btopen(filename[, flag[, mode[, btflags[, cachesize[, maxkeypage[, minkeypage[, pgsize[, lorder]]]]]]]])

   Open the btree format file named *filename*.  Files never intended
   to be preserved on disk may be created by passing ``None`` as the
   *filename*.  The optional *flag* identifies the mode used to open
   the file.  It may be ``'r'`` (read only), ``'w'`` (read-write),
   ``'c'`` (read-write - create if necessary; the default) or ``'n'``
   (read-write - truncate to zero length).  The other arguments are
   rarely used and are just passed to the low-level dbopen function.
   Consult the Berkeley DB documentation for their use and
   interpretation.

bsddb.rnopen(filename[, flag[, mode[, rnflags[, cachesize[, pgsize[, lorder[, rlen[, delim[, source[, pad]]]]]]]]]])

   Open a DB record format file named *filename*.  Files never
   intended  to be preserved on disk may be created by passing
   ``None`` as the  *filename*.  The optional *flag* identifies the
   mode used to open the file.  It may be ``'r'`` (read only), ``'w'``
   (read-write), ``'c'`` (read-write - create if necessary; the
   default) or ``'n'`` (read-write - truncate to zero length).  The
   other arguments are rarely used and are just passed to the low-
   level dbopen function. Consult the Berkeley DB documentation for
   their use and interpretation.

Note: Beginning in 2.3 some Unix versions of Python may have a
  ``bsddb185`` module. This is present *only* to allow backwards
  compatibility with systems which ship with the old Berkeley DB 1.85
  database library.  The ``bsddb185`` module should never be used
  directly in new code. The module has been removed in Python 3.0.  If
  you find you still need it look in PyPI.

See also:

   Module ``dbhash``
      DBM-style interface to the ``bsddb``


Hash, BTree and Record Objects
==============================

Once instantiated, hash, btree and record objects support the same
methods as dictionaries.  In addition, they support the methods listed
below.

Changed in version 2.3.1: Added dictionary methods.

bsddbobject.close()

   Close the underlying file.  The object can no longer be accessed.
   Since there is no open ``open()`` method for these objects, to open
   the file again a new ``bsddb`` module open function must be called.

bsddbobject.keys()

   Return the list of keys contained in the DB file.  The order of the
   list is unspecified and should not be relied on.  In particular,
   the order of the list returned is different for different file
   formats.

bsddbobject.has_key(key)

   Return ``1`` if the DB file contains the argument as a key.

bsddbobject.set_location(key)

   Set the cursor to the item indicated by *key* and return a tuple
   containing the key and its value.  For binary tree databases
   (opened using ``btopen()``), if *key* does not actually exist in
   the database, the cursor will point to the next item in sorted
   order and return that key and value.  For other databases,
   ``KeyError`` will be raised if *key* is not found in the database.

bsddbobject.first()

   Set the cursor to the first item in the DB file and return it.  The
   order of keys in the file is unspecified, except in the case of
   B-Tree databases. This method raises ``bsddb.error`` if the
   database is empty.

bsddbobject.next()

   Set the cursor to the next item in the DB file and return it.  The
   order of keys in the file is unspecified, except in the case of
   B-Tree databases.

bsddbobject.previous()

   Set the cursor to the previous item in the DB file and return it.
   The order of keys in the file is unspecified, except in the case of
   B-Tree databases.  This is not supported on hashtable databases
   (those opened with ``hashopen()``).

bsddbobject.last()

   Set the cursor to the last item in the DB file and return it.  The
   order of keys in the file is unspecified.  This is not supported on
   hashtable databases (those opened with ``hashopen()``). This method
   raises ``bsddb.error`` if the database is empty.

bsddbobject.sync()

   Synchronize the database on disk.

Example:

   >>> import bsddb
   >>> db = bsddb.btopen('/tmp/spam.db', 'c')
   >>> for i in range(10): db['%d'%i] = '%d'% (i*i)
   ...
   >>> db['3']
   '9'
   >>> db.keys()
   ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9']
   >>> db.first()
   ('0', '0')
   >>> db.next()
   ('1', '1')
   >>> db.last()
   ('9', '81')
   >>> db.set_location('2')
   ('2', '4')
   >>> db.previous()
   ('1', '1')
   >>> for k, v in db.iteritems():
   ...     print k, v
   0 0
   1 1
   2 4
   3 9
   4 16
   5 25
   6 36
   7 49
   8 64
   9 81
   >>> '8' in db
   True
   >>> db.sync()
   0
