rest25/library/bsddb.rst => rest262/library/bsddb.rst
f1
2:mod:`bsddb` --- Interface to Berkeley DB library
3=================================================
4
5.. module:: bsddb
n6-   :platform: Unix, Windows
7   :synopsis: Interface to Berkeley DB database library
n8-.. sectionauthor:: Skip Montanaro <skip@mojam.com>
n7+.. 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.
9
10
11The :mod:`bsddb` module provides an interface to the Berkeley DB library.  Users
12can create hash, btree or record based library files using the appropriate open
13call. Bsddb objects behave generally like dictionaries.  Keys and values must be
14strings, however, so to use other objects as keys or to store other kinds of
15objects the user must serialize them somehow, typically using
16:func:`marshal.dumps` or  :func:`pickle.dumps`.
17
n18-The :mod:`bsddb` module requires a Berkeley DB library version from 3.3 thru
n20+The :mod:`bsddb` module requires a Berkeley DB library version from 4.0 thru
19-4.4.
21+4.7.
20
21
22.. seealso::
23
n24-   http://pybsddb.sourceforge.net/
n26+   http://www.jcea.es/programacion/pybsddb.htm
25-      The website with documentation for the :mod:`bsddb.db` python Berkeley DB
27+      The website with documentation for the :mod:`bsddb.db` Python Berkeley DB
26-      interface that closely mirrors the Sleepycat object oriented interface provided
28+      interface that closely mirrors the object oriented interface provided in
27-      in Berkeley DB 3 and 4.
29+      Berkeley DB 4.x itself.
28
n29-   http://www.sleepycat.com/
n31+   http://www.oracle.com/database/berkeley-db/
30-      Sleepycat Software produces the Berkeley DB library.
32+      The Berkeley DB library.
31
32A more modern DB, DBEnv and DBSequence object interface is available in the
n33-:mod:`bsddb.db` module which closely matches the Sleepycat Berkeley DB C API
n35+:mod:`bsddb.db` module which closely matches the Berkeley DB C API documented at
34-documented at the above URLs.  Additional features provided by the
36+the above URLs.  Additional features provided by the :mod:`bsddb.db` API include
35-:mod:`bsddb.db` API include fine tuning, transactions, logging, and multiprocess
37+fine tuning, transactions, logging, and multiprocess concurrent database access.
36-concurrent database access.
37
38The following is a description of the legacy :mod:`bsddb` interface compatible
n39-with the old python bsddb module.  Starting in Python 2.5 this interface should
n40+with the old Python bsddb module.  Starting in Python 2.5 this interface should
40be safe for multithreaded access.  The :mod:`bsddb.db` API is recommended for
41threading users as it provides better control.
42
43The :mod:`bsddb` module defines the following functions that create objects that
44access the appropriate type of Berkeley DB file.  The first two arguments of
45each function are the same.  For ease of portability, only the first two
46arguments should be used in most instances.
47
48
n49-.. function:: hashopen(filename[, flag[, mode[, bsize[, ffactor[, nelem[, cachesize[, hash[, lorder]]]]]]]])
n50+.. function:: hashopen(filename[, flag[, mode[, pgsize[, ffactor[, nelem[, cachesize[, lorder[, hflags]]]]]]]])
50
51   Open the hash format file named *filename*.  Files never intended to be
52   preserved on disk may be created by passing ``None`` as the  *filename*.  The
53   optional *flag* identifies the mode used to open the file.  It may be ``'r'``
54   (read only), ``'w'`` (read-write) , ``'c'`` (read-write - create if necessary;
55   the default) or ``'n'`` (read-write - truncate to zero length).  The other
56   arguments are rarely used and are just passed to the low-level :cfunc:`dbopen`
57   function.  Consult the Berkeley DB documentation for their use and
64   preserved on disk may be created by passing ``None`` as the  *filename*.  The
65   optional *flag* identifies the mode used to open the file.  It may be ``'r'``
66   (read only), ``'w'`` (read-write), ``'c'`` (read-write - create if necessary;
67   the default) or ``'n'`` (read-write - truncate to zero length).  The other
68   arguments are rarely used and are just passed to the low-level dbopen function.
69   Consult the Berkeley DB documentation for their use and interpretation.
70
71
n72-.. function:: rnopen(filename[, flag[, mode[, rnflags[, cachesize[, pgsize[, lorder[, reclen[, bval[, bfname]]]]]]]]])
n73+.. function:: rnopen(filename[, flag[, mode[, rnflags[, cachesize[, pgsize[, lorder[, rlen[, delim[, source[, pad]]]]]]]]]])
73
74   Open a DB record format file named *filename*.  Files never intended  to be
75   preserved on disk may be created by passing ``None`` as the  *filename*.  The
76   optional *flag* identifies the mode used to open the file.  It may be ``'r'``
77   (read only), ``'w'`` (read-write), ``'c'`` (read-write - create if necessary;
78   the default) or ``'n'`` (read-write - truncate to zero length).  The other
79   arguments are rarely used and are just passed to the low-level dbopen function.
80   Consult the Berkeley DB documentation for their use and interpretation.
81
82.. note::
83
84   Beginning in 2.3 some Unix versions of Python may have a :mod:`bsddb185` module.
85   This is present *only* to allow backwards compatibility with systems which ship
86   with the old Berkeley DB 1.85 database library.  The :mod:`bsddb185` module
n87-   should never be used directly in new code.
n88+   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.
88
89
90.. seealso::
91
92   Module :mod:`dbhash`
93      DBM-style interface to the :mod:`bsddb`
94
95
100
101Once instantiated, hash, btree and record objects support the same methods as
102dictionaries.  In addition, they support the methods listed below.
103
104.. versionchanged:: 2.3.1
105   Added dictionary methods.
106
107
n108-.. method:: XXX Class.close()
n110+.. method:: bsddbobject.close()
109
110   Close the underlying file.  The object can no longer be accessed.  Since there
111   is no open :meth:`open` method for these objects, to open the file again a new
112   :mod:`bsddb` module open function must be called.
113
114
n115-.. method:: XXX Class.keys()
n117+.. method:: bsddbobject.keys()
116
117   Return the list of keys contained in the DB file.  The order of the list is
118   unspecified and should not be relied on.  In particular, the order of the list
119   returned is different for different file formats.
120
121
n122-.. method:: XXX Class.has_key(key)
n124+.. method:: bsddbobject.has_key(key)
123
124   Return ``1`` if the DB file contains the argument as a key.
125
126
n127-.. method:: XXX Class.set_location(key)
n129+.. method:: bsddbobject.set_location(key)
128
129   Set the cursor to the item indicated by *key* and return a tuple containing the
130   key and its value.  For binary tree databases (opened using :func:`btopen`), if
131   *key* does not actually exist in the database, the cursor will point to the next
132   item in sorted order and return that key and value.  For other databases,
133   :exc:`KeyError` will be raised if *key* is not found in the database.
134
135
n136-.. method:: XXX Class.first()
n138+.. method:: bsddbobject.first()
137
138   Set the cursor to the first item in the DB file and return it.  The order of
139   keys in the file is unspecified, except in the case of B-Tree databases. This
140   method raises :exc:`bsddb.error` if the database is empty.
141
142
n143-.. method:: XXX Class.next()
n145+.. method:: bsddbobject.next()
144
145   Set the cursor to the next item in the DB file and return it.  The order of
146   keys in the file is unspecified, except in the case of B-Tree databases.
147
148
n149-.. method:: XXX Class.previous()
n151+.. method:: bsddbobject.previous()
150
151   Set the cursor to the previous item in the DB file and return it.  The order of
152   keys in the file is unspecified, except in the case of B-Tree databases.  This
153   is not supported on hashtable databases (those opened with :func:`hashopen`).
154
155
n156-.. method:: XXX Class.last()
n158+.. method:: bsddbobject.last()
157
158   Set the cursor to the last item in the DB file and return it.  The order of keys
159   in the file is unspecified.  This is not supported on hashtable databases (those
160   opened with :func:`hashopen`). This method raises :exc:`bsddb.error` if the
161   database is empty.
162
163
n164-.. method:: XXX Class.sync()
n166+.. method:: bsddbobject.sync()
165
166   Synchronize the database on disk.
167
168Example::
169
170   >>> import bsddb
171   >>> db = bsddb.btopen('/tmp/spam.db', 'c')
172   >>> for i in range(10): db['%d'%i] = '%d'% (i*i)
n173-   ... 
n175+   ...
174   >>> db['3']
175   '9'
176   >>> db.keys()
177   ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9']
178   >>> db.first()
179   ('0', '0')
180   >>> db.next()
181   ('1', '1')
182   >>> db.last()
183   ('9', '81')
184   >>> db.set_location('2')
185   ('2', '4')
t186-   >>> db.previous() 
t188+   >>> db.previous()
187   ('1', '1')
188   >>> for k, v in db.iteritems():
189   ...     print k, v
190   0 0
191   1 1
192   2 4
193   3 9
194   4 16
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op