mirror of https://github.com/python/cpython
203 lines
7.2 KiB
ReStructuredText
203 lines
7.2 KiB
ReStructuredText
|
|
:mod:`bsddb` --- Interface to Berkeley DB library
|
|
=================================================
|
|
|
|
.. module:: bsddb
|
|
:synopsis: Interface to Berkeley DB database library
|
|
.. sectionauthor:: Skip Montanaro <skip@mojam.com>
|
|
|
|
|
|
The :mod:`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
|
|
:func:`marshal.dumps` or :func:`pickle.dumps`.
|
|
|
|
The :mod:`bsddb` module requires a Berkeley DB library version from 3.3 thru
|
|
4.5.
|
|
|
|
|
|
.. seealso::
|
|
|
|
http://pybsddb.sourceforge.net/
|
|
The website with documentation for the :mod:`bsddb.db` Python Berkeley DB
|
|
interface that closely mirrors the object oriented interface provided in
|
|
Berkeley DB 3 and 4.
|
|
|
|
http://www.oracle.com/database/berkeley-db/
|
|
The Berkeley DB library.
|
|
|
|
A more modern DB, DBEnv and DBSequence object interface is available in the
|
|
:mod:`bsddb.db` module which closely matches the Berkeley DB C API documented at
|
|
the above URLs. Additional features provided by the :mod:`bsddb.db` API include
|
|
fine tuning, transactions, logging, and multiprocess concurrent database access.
|
|
|
|
The following is a description of the legacy :mod:`bsddb` interface compatible
|
|
with the old Python bsddb module. Starting in Python 2.5 this interface should
|
|
be safe for multithreaded access. The :mod:`bsddb.db` API is recommended for
|
|
threading users as it provides better control.
|
|
|
|
The :mod:`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.
|
|
|
|
|
|
.. function:: 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 :cfunc:`dbopen`
|
|
function. Consult the Berkeley DB documentation for their use and
|
|
interpretation.
|
|
|
|
|
|
.. function:: 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.
|
|
|
|
|
|
.. function:: 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 :mod:`bsddb185` module.
|
|
This is present *only* to allow backwards compatibility with systems which ship
|
|
with the old Berkeley DB 1.85 database library. The :mod:`bsddb185` module
|
|
should never be used directly in new code.
|
|
|
|
|
|
.. seealso::
|
|
|
|
Module :mod:`dbhash`
|
|
DBM-style interface to the :mod:`bsddb`
|
|
|
|
|
|
.. _bsddb-objects:
|
|
|
|
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.
|
|
|
|
.. versionchanged:: 2.3.1
|
|
Added dictionary methods.
|
|
|
|
|
|
.. method:: bsddbobject.close()
|
|
|
|
Close the underlying file. The object can no longer be accessed. Since there
|
|
is no open :meth:`open` method for these objects, to open the file again a new
|
|
:mod:`bsddb` module open function must be called.
|
|
|
|
|
|
.. method:: 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.
|
|
|
|
|
|
.. method:: bsddbobject.has_key(key)
|
|
|
|
Return ``1`` if the DB file contains the argument as a key.
|
|
|
|
|
|
.. method:: 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 :func:`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,
|
|
:exc:`KeyError` will be raised if *key* is not found in the database.
|
|
|
|
|
|
.. method:: 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 :exc:`bsddb.error` if the database is empty.
|
|
|
|
|
|
.. method:: 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.
|
|
|
|
|
|
.. method:: 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 :func:`hashopen`).
|
|
|
|
|
|
.. method:: 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 :func:`hashopen`). This method raises :exc:`bsddb.error` if the
|
|
database is empty.
|
|
|
|
|
|
.. method:: 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
|
|
|