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 3.3 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