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 removed in Python 3.
11
12
13The :mod:`bsddb` module provides an interface to the Berkeley DB library.  Users
14can create hash, btree or record based library files using the appropriate open
15call. Bsddb objects behave generally like dictionaries.  Keys and values must be
16strings, however, so to use other objects as keys or to store other kinds of
17objects the user must serialize them somehow, typically using
18:func:`marshal.dumps` or  :func:`pickle.dumps`.
19
20The :mod:`bsddb` module requires a Berkeley DB library version from 4.0 thru
214.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
34A 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
36the above URLs.  Additional features provided by the :mod:`bsddb.db` API include
37fine tuning, transactions, logging, and multiprocess concurrent database access.
38
39The following is a description of the legacy :mod:`bsddb` interface compatible
40with the old Python bsddb module.  Starting in Python 2.5 this interface should
41be safe for multithreaded access.  The :mod:`bsddb.db` API is recommended for
42threading users as it provides better control.
43
44The :mod:`bsddb` module defines the following functions that create objects that
45access the appropriate type of Berkeley DB file.  The first two arguments of
46each function are the same.  For ease of portability, only the first two
47arguments 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 :c:func:`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.  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
100Hash, BTree and Record Objects
101------------------------------
102
103Once instantiated, hash, btree and record objects support the same methods as
104dictionaries.  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
170Example::
171
172   >>> import bsddb
173   >>> db = bsddb.btopen('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
207